@callcium/sdk 0.11.1 → 0.13.0

package/src/signature.ts

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

package/src/type-desc.ts

@@ -9,10 +9,8 @@ import { CallciumError } from "./errors";
 /**
  * Extract the staticWords count from a descriptor node.
  *
- * For elementary types (typeCode < STATIC_ARRAY), returns 1 unless the type is
- * BYTES or STRING, which are ABI-dynamic and return 0. For composite types,
- * reads the 24-bit meta field at offset 1 and shifts right by
- * META_STATIC_WORDS_SHIFT.
+ * For elementary types (typeCode < STATIC_ARRAY), returns 1 unless the type is BYTES or STRING, which are ABI-dynamic
+ * and return 0. For composite types, returns the 24-bit meta at offset 1 right-shifted by META_STATIC_WORDS_SHIFT.
  */
 function extractStaticWords(desc: Uint8Array): number {
   const typeCode = desc[0]!;
@@ -44,11 +42,11 @@ export function function_(): Uint8Array {
 /**
  * Build a descriptor node for `uintN`.
  * @param bits - Bit width, 8–256 in steps of 8.
- * @throws {CallciumError} With code `UNKNOWN_TYPE` if bits is out of range or not a multiple of 8.
+ * @throws {CallciumError} With code `INVALID_UINT_BITS` if bits is out of range or not a multiple of 8.
  */
 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("INVALID_UINT_BITS", `Invalid uint width ${bits}`);
   }
   return new Uint8Array([TypeCode.UINT_MIN + (bits / 8 - 1)]);
 }
@@ -56,11 +54,11 @@ export function uintN(bits: number): Uint8Array {
 /**
  * Build a descriptor node for `intN`.
  * @param bits - Bit width, 8–256 in steps of 8.
- * @throws {CallciumError} With code `UNKNOWN_TYPE` if bits is out of range or not a multiple of 8.
+ * @throws {CallciumError} With code `INVALID_INT_BITS` if bits is out of range or not a multiple of 8.
  */
 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("INVALID_INT_BITS", `Invalid int width ${bits}`);
   }
   return new Uint8Array([TypeCode.INT_MIN + (bits / 8 - 1)]);
 }
@@ -78,11 +76,11 @@ export function string_(): Uint8Array {
 /**
  * Build a descriptor node for `bytesN`.
  * @param length - Byte width, 1–32.
- * @throws {CallciumError} With code `UNKNOWN_TYPE` if length is out of range.
+ * @throws {CallciumError} With code `INVALID_BYTES_LENGTH` if length is out of range.
  */
 export function bytesN(length: number): Uint8Array {
   if (length < 1 || length > 32) {
-    throw new CallciumError("UNKNOWN_TYPE", `Invalid bytesN size: ${length}. Must be 1–32`);
+    throw new CallciumError("INVALID_BYTES_LENGTH", `Invalid bytes length ${length}`);
   }
   return new Uint8Array([TypeCode.FIXED_BYTES_MIN + (length - 1)]);
 }
@@ -99,7 +97,8 @@ export function bytesN(length: number): Uint8Array {
  *
  * @param elemDesc - Descriptor bytes for the element type.
  * @param length - Fixed array length. When omitted, produces a dynamic array.
- * @throws {CallciumError} If length is 0 or exceeds MAX_STATIC_ARRAY_LENGTH.
+ * @throws {CallciumError} If length is 0 or above MAX_STATIC_ARRAY_LENGTH.
+ * @throws {CallciumError} If the node exceeds MAX_NODE_LENGTH or MAX_STATIC_WORDS.
  */
 export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
   if (length === undefined) {
@@ -156,7 +155,8 @@ export function array(elemDesc: Uint8Array, length?: number): Uint8Array {
  * Format: `[0x90][meta:3][fieldCount:be16][field0][field1]...`
  *
  * @param fieldDescs - Descriptor bytes for each field, in order.
- * @throws {CallciumError} If fieldDescs is empty, exceeds MAX_TUPLE_FIELDS, or nodeLength overflows MAX_NODE_LENGTH.
+ * @throws {CallciumError} If fieldDescs is empty or above MAX_TUPLE_FIELDS.
+ * @throws {CallciumError} If the node exceeds MAX_NODE_LENGTH or MAX_STATIC_WORDS.
  */
 export function tuple(fieldDescs: Uint8Array[]): Uint8Array {
   if (fieldDescs.length === 0 || fieldDescs.length > DF.MAX_TUPLE_FIELDS) {

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { ComparisonCode, QuantifierCode, Scope, ScopeCode, Source } from "./constants";
+
 ///////////////////////////////////////////////////////////////////////////
 // Primitives
 ///////////////////////////////////////////////////////////////////////////
@@ -11,14 +13,16 @@ export type Address = `0x${string}`;
 /** Byte range in a source blob. */
 export type Span = { start: number; end: number };
 
+/** A decoded value with its byte position in the source blob. */
+export type Field<T> = { value: T; span: Span };
+
 ///////////////////////////////////////////////////////////////////////////
 // Enforce
 ///////////////////////////////////////////////////////////////////////////
 
 /**
- * Execution context for context-scoped rules.
- * Each property maps to a well-known EVM execution environment value.
- * Only the properties referenced by the policy need to be supplied.
+ * Execution context for context-scoped rules. Each property maps to a well-known EVM execution environment value. Only
+ * the properties referenced by the policy need to be supplied.
  */
 export type Context = {
   msgSender?: Address;
@@ -52,53 +56,54 @@ export type SelectorMismatchViolation = {
 };
 
 /**
- * A rule referenced a context property not supplied in the execution context — a context-scoped
- * subject, or an `EQ_CTX` operand on either scope.
+ * A test read a context property not supplied in the execution context — a context test's subject, or a context
+ * operand on either kind of test.
+ *
+ * `group` and `rule` locate the root rule. A test in a loop body adds `bodyRule` and `elementIndex`.
  */
 export type MissingContextViolation = {
   code: "MISSING_CONTEXT";
   group: number;
   rule: number;
-  scope: number;
+  scope: ScopeCode;
+  /** The test's path: a context test's property ID, or a calldata test's steps (in a loop body, from the element). */
   path: Hex;
   /** Declared type of the missing context property. */
   typeCode: number;
-  /** Operator code with the `Op.NOT` bit intact; absent for a context-scoped subject. */
-  opCode?: number;
-  /** Operator payload; absent for a context-scoped subject. */
-  operandData?: Hex;
+  /** The test's operator, absent for a context test's subject. */
+  operator?: DecodedOperator;
+  /** Position of the test in the loop body, absent for a root test. */
+  bodyRule?: number;
+  /** Position of the element the body test read, absent for a root test. */
+  elementIndex?: number;
 };
 
 /**
- * A rule's operator returned false against the loaded value.
- *
- * Field combinations:
- * - `resolvedValue` present, `elementIndex` absent — scalar leaf or context value that failed the operator.
- * - `resolvedValue` present, `elementIndex` present — universal-quantifier per-element failure.
- * - `resolvedValue` absent, `elementIndex` absent — existential-aggregate failure (no element satisfied).
- * - `resolvedValue` absent, `elementIndex` present — per-element failure where the leaf could not be loaded.
+ * A test's operator returned false against the loaded value.
  *
- * For length operations (`isLengthOp(opCode)`), `resolvedValue` is a hex-encoded count
- * rather than a 32-byte ABI word.
+ * `resolvedValue` is the value the operator compared: a word, or for length operators the length as a 32-byte word.
+ * `group` and `rule` locate the root rule. A test in a loop body adds `bodyRule` and `elementIndex`.
  */
 export type ValueMismatchViolation = {
   code: "VALUE_MISMATCH";
   group: number;
   rule: number;
-  scope: number;
+  scope: ScopeCode;
+  /** The test's path: a context test's property ID, or a calldata test's steps (in a loop body, from the element). */
   path: Hex;
-  /** Operator code with the `Op.NOT` bit intact. */
-  opCode: number;
-  /** Full untruncated operand bytes declared by the rule. */
-  operandData: Hex;
-  /** Type code of the failing value's leaf. */
+  /** The test's operator. */
+  operator: DecodedOperator;
+  /** Type code of the failing value. */
   typeCode: number;
-  resolvedValue?: Hex;
+  resolvedValue: Hex;
   /**
-   * Resolved runtime value of a reference operand as a 32-byte word; present when the
-   * operator's operand names a reference resolved at enforcement, not a literal.
+   * Resolved runtime value of a context operand as a 32-byte word, present when the operator's operand names a context
+   * property, not a constant.
    */
   resolvedOperand?: Hex;
+  /** Position of the test in the loop body, absent for a root test. */
+  bodyRule?: number;
+  /** Position of the element the body test read, absent for a root test. */
   elementIndex?: number;
 };
 
@@ -110,19 +115,21 @@ type CalldataNavigationVariant<C extends NavigationViolationCode> = {
   code: C;
   group: number;
   rule: number;
-  scope: number;
+  scope: ScopeCode;
   path: Hex;
-  opCode?: number;
-  operandData?: Hex;
+  operator?: DecodedOperator;
   typeCode?: number;
+  bodyRule?: number;
   elementIndex?: number;
 };
 
 /**
- * Calldata structure prevented the rule from being evaluated.
+ * Calldata structure prevented a rule from being evaluated.
  *
- * The operator was never applied; `opCode`, `operandData`, `typeCode`, and `elementIndex`
- * are diagnostic context describing the failing site, not a constraint claim.
+ * The operator was never applied. `operator`, `typeCode`, `bodyRule` and `elementIndex` are diagnostic context
+ * describing the failing site, not a constraint claim. A failure resolving a loop's array carries the loop
+ * rule's scope and array path and no operator. A failure resolving an element adds `elementIndex`. A failure in a body
+ * test adds the test's fields and `bodyRule`.
  *
  * A union of per-code variants, narrowable with `Extract<Violation, { code: "..." }>`.
  */
@@ -130,12 +137,13 @@ export type CalldataNavigationViolation =
   | CalldataNavigationVariant<"CALLDATA_OUT_OF_BOUNDS">
   | CalldataNavigationVariant<"ARRAY_INDEX_OUT_OF_BOUNDS">;
 
-/** A quantified array exceeded `PolicyFormat.MAX_QUANTIFIED_ARRAY_LENGTH`. */
+/** A loop's array exceeded `MAX_QUANTIFIED_ARRAY_LENGTH`. */
 export type QuantifierLimitExceededViolation = {
   code: "QUANTIFIER_LIMIT_EXCEEDED";
   group: number;
   rule: number;
-  scope: number;
+  scope: ScopeCode;
+  /** The loop's array path. */
   path: Hex;
   /** Hex-encoded element count of the offending array. */
   resolvedValue: Hex;
@@ -150,31 +158,34 @@ export type NonCanonicalValueViolation = {
   code: "NON_CANONICAL_VALUE";
   group: number;
   rule: number;
-  scope: number;
+  scope: ScopeCode;
   path: Hex;
   /** Type code of the target whose encoding was violated. */
   typeCode: number;
   /** Raw 32-byte word as it appeared in calldata, before any masking. */
   resolvedValue: Hex;
-  opCode?: number;
-  operandData?: Hex;
+  /** The test's operator. */
+  operator: DecodedOperator;
+  /** Position of the test in the loop body, absent for a root test. */
+  bodyRule?: number;
+  /** Position of the element the body test read, absent for a root test. */
   elementIndex?: number;
 };
 
-/** An `ANY` quantifier was applied to an empty array. */
-export type QuantifierEmptyArrayViolation = {
-  code: "QUANTIFIER_EMPTY_ARRAY";
+/** No element satisfied an `ANY` loop's body, the empty array included. No element and no test is to blame. */
+export type QuantifierNoMatchViolation = {
+  code: "QUANTIFIER_NO_MATCH";
   group: number;
   rule: number;
-  scope: number;
+  scope: ScopeCode;
+  /** The loop's array path. */
   path: Hex;
 };
 
 /**
  * Structured details of a single rule failure during enforcement.
  *
- * Carries semantic data only; no message strings.
- * Discriminate on `code` to narrow to the matching variant.
+ * Carries semantic data only, with no message strings. Discriminate on `code` to narrow to the matching variant.
  */
 export type Violation =
   | MissingSelectorViolation
@@ -184,66 +195,188 @@ export type Violation =
   | CalldataNavigationViolation
   | NonCanonicalValueViolation
   | QuantifierLimitExceededViolation
-  | QuantifierEmptyArrayViolation;
+  | QuantifierNoMatchViolation;
 
 /** Machine-readable reason code for an enforcement violation. Derived from `Violation` to prevent drift. */
 export type ViolationCode = Violation["code"];
 
 ///////////////////////////////////////////////////////////////////////////
-// Canonical policy types
+// Policy types
 ///////////////////////////////////////////////////////////////////////////
 
-/** Canonical structured representation of a policy. */
+/** A test or a context test of a loop body, or of a group. */
+export type BodyRule = {
+  scope: typeof Scope.CONTEXT | typeof Scope.CALLDATA;
+  /** BE16-encoded path from the starting point. A context test's path is its property ID. */
+  path: Hex;
+  /** The hint a blob carries for the path, absent for a context test and in data not read from a blob. */
+  hint?: Hex;
+  /** Encoded operator: opCode(1) || each operand value as a 32-byte word, a context property as its ID. */
+  operator: Hex;
+};
+
+/** A loop: its body over each element of the array at `path`. */
+export type LoopRule = {
+  scope: typeof Scope.LOOP;
+  quantifier: QuantifierCode;
+  /** BE16-encoded path from the arguments to the array. */
+  path: Hex;
+  /** The frame hint a blob carries for the path, absent in data not read from a blob. */
+  hint?: Hex;
+  body: BodyRule[];
+};
+
+/** A rule of a group: a test, a context test or a loop. */
+export type Rule = BodyRule | LoopRule;
+
+/** A policy: its selector, its descriptor and its groups of rules. */
 export type PolicyData = {
   isSelectorless: boolean;
   selector: Hex;
   descriptor: Hex;
-  groups: Constraint[][];
-  span?: Span;
+  groups: Rule[][];
 };
 
+/**
+ * An operator as a policy stores it: its comparison, its polarity and its operands. Constants are loaded to 32-byte
+ * words of `operandType`. A context operand names its property.
+ */
+export type DecodedOperator = {
+  /** Operator code with the `Op.NOT` bit intact. */
+  opCode: number;
+  /** Comparison bits of `opCode`. */
+  comparison: ComparisonCode;
+  /** True when `opCode` carries the `Op.NOT` bit. */
+  negated: boolean;
+  /**
+   * Type code of the operands: the target's type, the type a length compares as for a length comparison,
+   * or the context property's type.
+   */
+  operandType: number;
+} & (
+  | {
+      source: typeof Source.CONSTANT;
+      /** Each constant loaded to its 32-byte word. */
+      values: Hex[];
+    }
+  | {
+      source: typeof Source.CONTEXT;
+      /** The context property the operand names. */
+      contextPropertyId: number;
+    }
+);
+
 /** A collection of operators targeting a specific value. */
 export type Constraint = {
-  scope: number;
+  scope: typeof Scope.CONTEXT | typeof Scope.CALLDATA;
   path: Hex;
   operators: Hex[];
-  /** Compiled hint block as carried on the wire; absent when the constraint has no encoding. */
-  hint?: Hex;
-  span?: Span;
 };
 
 ///////////////////////////////////////////////////////////////////////////
-// Structural inspection types
+// Inspection
 ///////////////////////////////////////////////////////////////////////////
 
-/** A decoded value with its byte position in the source blob. */
-export type Field<T> = { value: T; span: Span };
-
-/** Structural representation of a decoded parameter within the descriptor. */
-export type DecodedParam = {
-  index: number;
+/** A descriptor node: its type, its head size and the bytes it spans, with its fields or its element. */
+export type DecodedNode = {
   typeCode: number;
   isDynamic: boolean;
+  /** Head size in bytes, zero for a dynamic type. */
   staticSize: number;
-  path: Hex;
+  span: Span;
+} & (
+  | { typeClass: "elementary" }
+  | { typeClass: "tuple"; fields: DecodedNode[] }
+  | { typeClass: "staticArray"; length: number; element: DecodedNode }
+  | { typeClass: "dynamicArray"; element: DecodedNode }
+);
+
+/** A descriptor: its header fields and one node per parameter. */
+export type DecodedDescriptor = {
+  version: Field<number>;
+  paramCount: Field<number>;
+  params: DecodedNode[];
+  span: Span;
+};
+
+/** An array's meta word. */
+export type ArrayMeta = {
+  /** The element type is dynamic. An offset word points to each element. */
+  isElementDynamic: boolean;
+  /** The array is dynamic. A length word is before the elements. */
+  isDynamicArray: boolean;
+  /** Element head size in words. */
+  strideWords: number;
+};
+
+/** A hop of a compiled hint: a plain hop enters the node behind an offset word, an element hop selects an element. */
+export type DecodedHop = {
+  kind: "plain" | "element";
+  delta: Field<number>;
+  index: Field<number>;
+  meta: Field<ArrayMeta>;
   span: Span;
 };
 
-/** Structural representation of a decoded rule with per-field spans. */
-export type DecodedRule = {
+/** A test hint: its hops, then the target's position, meta word and type code. */
+export type DecodedHint = {
+  hopCount: Field<number>;
+  hops: DecodedHop[];
+  targetDelta: Field<number>;
+  /** The target's meta word. Every field is false or zero unless the target is a dynamic array. */
+  targetMeta: Field<ArrayMeta>;
+  typeCode: Field<number>;
+  span: Span;
+};
+
+/** A frame hint: its hops, then the array's position, declared length and meta word. */
+export type DecodedFrameHint = {
+  hopCount: Field<number>;
+  hops: DecodedHop[];
+  arrayDelta: Field<number>;
+  /** Declared length of a static array, or zero for a dynamic array. */
+  count: Field<number>;
+  meta: Field<ArrayMeta>;
+  span: Span;
+};
+
+/** A test or a context test, each field with the bytes that contain it. */
+export type DecodedTest = {
   ruleSize: Field<number>;
-  scope: Field<number>;
+  scope: Field<typeof Scope.CONTEXT | typeof Scope.CALLDATA>;
   pathDepth: Field<number>;
+  /** The path steps, or a context test's property ID. */
   path: Field<Hex>;
-  /** Compiled hint block; present for calldata rules only. */
-  hint?: Field<Hex>;
+  /** The test hint, absent for a context test. */
+  hint?: DecodedHint;
+  /** Type code of the target: the hint's, or the context property's. */
+  targetType: number;
   opCode: Field<number>;
   dataLength: Field<number>;
+  /** The operands as stored. */
   data: Field<Hex>;
+  operator: DecodedOperator;
+  span: Span;
+};
+
+/** A loop rule, each field with the bytes that contain it. */
+export type DecodedLoop = {
+  ruleSize: Field<number>;
+  scope: Field<typeof Scope.LOOP>;
+  quantifier: Field<QuantifierCode>;
+  pathDepth: Field<number>;
+  /** The array's path. */
+  path: Field<Hex>;
+  hint: DecodedFrameHint;
+  ruleCount: Field<number>;
+  body: DecodedTest[];
   span: Span;
 };
 
-/** Structural representation of a decoded group with metadata spans. */
+/** A rule of a group: a test, a context test or a loop. */
+export type DecodedRule = DecodedTest | DecodedLoop;
+
+/** A group, each field with the bytes that contain it. */
 export type DecodedGroup = {
   ruleCount: Field<number>;
   groupSize: Field<number>;
@@ -251,102 +384,65 @@ export type DecodedGroup = {
   span: Span;
 };
 
-/** Structural representation of a decoded policy with full byte-level spans. */
+/** A policy blob, each field with the bytes that contain it. */
 export type DecodedPolicy = {
-  header: Field<number>;
+  header: Field<{ major: number; minor: number; isSelectorless: boolean }>;
+  /** The selector slot, zero for a selectorless policy. */
   selector: Field<Hex>;
   descLength: Field<number>;
-  descriptor: { raw: Hex; header: Field<{ version: number; paramCount: number }>; params: DecodedParam[]; span: Span };
+  descriptor: DecodedDescriptor;
   groupCount: Field<number>;
   groups: DecodedGroup[];
   span: Span;
-  version: number;
-  isSelectorless: boolean;
 };
 
 ///////////////////////////////////////////////////////////////////////////
-// Validation issues
+// Validation
 ///////////////////////////////////////////////////////////////////////////
 
 /** Severity of a validation issue. */
 export type IssueSeverity = "info" | "warning" | "error";
 
-/** Category of a validation issue. */
+/** Kind of defect a validation issue reports. */
 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.
- */
+/** Machine-readable code of a validation issue. */
 export type IssueCode =
-  // Type mismatch.
-  | "VALUE_OP_ON_DYNAMIC"
-  | "VALUE_OP_ON_COMPOSITE"
+  | "INVALID_DESCRIPTOR"
+  | "UNNAVIGABLE_PATH"
+  | "QUANTIFIER_ON_NON_ARRAY"
+  | "HINT_MISMATCH"
   | "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.
+  | "CONTRADICTORY_RULE"
+  | "REDUNDANT_RULE"
   | "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"
+  | "VACUOUS_RULE"
   | "QUANTIFIER_OVER_STATIC_LIMIT"
-  | "UNKNOWN_CONTEXT_PROPERTY"
-  | "NEGATION_UNDER_ANY";
+  | "CONTEXT_ONLY_BODY";
+
+/**
+ * The rule an issue names: its group, its position in the group and, for a test in a loop body, its position in the
+ * body. The location also carries the rule's scope, path and operator as decoded.
+ * A path in a body starts at the element.
+ */
+export type RuleLocation = {
+  groupIndex: number;
+  ruleIndex: number;
+  bodyRuleIndex?: number;
+  scope: ScopeCode;
+  path: Hex;
+  operator?: Hex;
+};
 
-/** A single validation issue found during policy analysis. */
-export type Issue = {
+/** A validation issue: the rule it names, absent for one about the descriptor, and the values that show the defect. */
+export type Issue = Partial<RuleLocation> & {
   severity: IssueSeverity;
   category: IssueCategory;
-  groupIndex: number;
-  constraintIndex: number;
   code: IssueCode;
   value1: Hex;
   value2: Hex;