@callcium/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,701 @@
+//#region src/types.d.ts
+/** Hex-encoded byte string, 0x-prefixed. */
+type Hex = `0x${string}`;
+/** Ethereum address, 0x-prefixed. */
+type Address = `0x${string}`;
+/** Byte range in a source blob. */
+type Span = {
+  start: number;
+  end: number;
+};
+/**
+ * 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.
+ */
+type Context = {
+  msgSender?: Address;
+  msgValue?: bigint;
+  blockTimestamp?: bigint;
+  blockNumber?: bigint;
+  chainId?: bigint;
+  txOrigin?: Address;
+};
+/** Result of enforcing a policy: pass with matched group index, or fail with one violation per failed group. */
+type EnforceResult = {
+  ok: true;
+  matchedGroup: number;
+} | {
+  ok: false;
+  violations: Violation[];
+};
+/** Machine-readable reason code for an enforcement violation. */
+type ViolationCode = "VALUE_MISMATCH" | "SELECTOR_MISMATCH" | "MISSING_SELECTOR" | "CALLDATA_OUT_OF_BOUNDS" | "ARRAY_INDEX_OUT_OF_BOUNDS" | "MISSING_CONTEXT" | "QUANTIFIER_LIMIT_EXCEEDED" | "QUANTIFIER_EMPTY_ARRAY";
+/** Details of a single rule failure during enforcement. */
+type Violation = {
+  /** Group index that failed. Absent for pre-group failures (e.g. selector mismatch). */group?: number; /** Rule index within the group. Absent for pre-rule failures. */
+  rule?: number;
+  code: ViolationCode;
+  message: string; /** Rule path that was being evaluated when the violation occurred. */
+  path?: Hex; /** The actual value found in calldata or context, for diagnostic display. */
+  resolvedValue?: Hex;
+};
+/** Canonical structured representation of a policy. */
+type PolicyData = {
+  isSelectorless: boolean;
+  selector: Hex;
+  descriptor: Hex;
+  groups: Constraint[][];
+  span?: Span;
+};
+/** A collection of operators targeting a specific value. */
+type Constraint = {
+  scope: number;
+  path: Hex;
+  operators: Hex[];
+  span?: Span;
+};
+/** A decoded value with its byte position in the source blob. */
+type Field<T> = {
+  value: T;
+  span: Span;
+};
+/** Structural representation of a decoded parameter within the descriptor. */
+type DecodedParam = {
+  index: number;
+  typeCode: number;
+  isDynamic: boolean;
+  staticSize: number;
+  path: Hex;
+  span: Span;
+};
+/** Structural representation of a decoded rule with per-field spans. */
+type DecodedRule = {
+  ruleSize: Field<number>;
+  scope: Field<number>;
+  pathDepth: Field<number>;
+  path: Field<Hex>;
+  opCode: Field<number>;
+  dataLength: Field<number>;
+  data: Field<Hex>;
+  span: Span;
+};
+/** Structural representation of a decoded group with metadata spans. */
+type DecodedGroup = {
+  ruleCount: Field<number>;
+  groupSize: Field<number>;
+  rules: DecodedRule[];
+  span: Span;
+};
+/** Structural representation of a decoded policy with full byte-level spans. */
+type DecodedPolicy = {
+  header: Field<number>;
+  selector: Field<Hex>;
+  descLength: Field<number>;
+  descriptor: {
+    raw: Hex;
+    header: Field<{
+      version: number;
+      paramCount: number;
+    }>;
+    params: DecodedParam[];
+    span: Span;
+  };
+  groupCount: Field<number>;
+  groups: DecodedGroup[];
+  span: Span;
+  version: number;
+  isSelectorless: boolean;
+};
+/** Severity of a validation issue. */
+type IssueSeverity = "info" | "warning" | "error";
+/** Category of a validation issue. */
+type IssueCategory = "typeMismatch" | "contradiction" | "redundancy" | "vacuity";
+/** A single validation issue found during policy analysis. */
+type Issue = {
+  severity: IssueSeverity;
+  category: IssueCategory;
+  groupIndex: number;
+  constraintIndex: number;
+  code: string;
+  value1: Hex;
+  value2: Hex;
+  message: string;
+};
+//#endregion
+//#region src/constraint.d.ts
+/** Accepted scalar value types for operator arguments. */
+type ScalarValue = bigint | number | boolean | string;
+/**
+ * Mutable builder that accumulates operators targeting a single path.
+ * Implements the `Constraint` interface so it can be passed directly to policy builders.
+ */
+declare class ConstraintBuilder implements Constraint {
+  readonly scope: number;
+  readonly path: Hex;
+  readonly operators: Hex[];
+  /** @internal */
+  constructor(scope: number, path: Hex);
+  /** Push a pre-encoded operator hex string and return this for chaining. */
+  private push;
+  /** Assert the value equals `value`. */
+  eq(value: ScalarValue): this;
+  /** Assert the value does not equal `value`. */
+  neq(value: ScalarValue): this;
+  /** Assert the value is greater than `bound`. */
+  gt(bound: bigint | number): this;
+  /** Assert the value is less than `bound`. */
+  lt(bound: bigint | number): this;
+  /** Assert the value is greater than or equal to `bound`. */
+  gte(bound: bigint | number): this;
+  /** Assert the value is less than or equal to `bound`. */
+  lte(bound: bigint | number): this;
+  /**
+   * Assert the value is within [min, max] inclusive.
+   * @throws {CallciumError} If min > max.
+   */
+  between(min: bigint | number, max: bigint | number): this;
+  /**
+   * Assert the value is a member of the set.
+   * Values are sorted and deduplicated before encoding.
+   * @throws {CallciumError} If the set is empty after deduplication.
+   */
+  isIn(values: readonly ScalarValue[]): this;
+  /**
+   * Assert the value is not a member of the set.
+   * @throws {CallciumError} If the set is empty after deduplication.
+   */
+  notIn(values: readonly ScalarValue[]): this;
+  /** Assert all bits in `mask` are set. */
+  bitmaskAll(mask: bigint): this;
+  /** Assert at least one bit in `mask` is set. */
+  bitmaskAny(mask: bigint): this;
+  /** Assert no bit in `mask` is set. */
+  bitmaskNone(mask: bigint): this;
+  /** Assert the runtime length equals `n`. */
+  lengthEq(n: bigint | number): this;
+  /** Assert the runtime length is greater than `n`. */
+  lengthGt(n: bigint | number): this;
+  /** Assert the runtime length is less than `n`. */
+  lengthLt(n: bigint | number): this;
+  /** Assert the runtime length is greater than or equal to `n`. */
+  lengthGte(n: bigint | number): this;
+  /** Assert the runtime length is less than or equal to `n`. */
+  lengthLte(n: bigint | number): this;
+  /**
+   * Assert the runtime length is within [min, max] inclusive.
+   * @throws {CallciumError} If min > max.
+   */
+  lengthBetween(min: bigint | number, max: bigint | number): this;
+}
+/**
+ * Target a calldata argument by path.
+ * Each argument is a big-endian uint16 step; multiple steps navigate into nested types.
+ */
+declare function arg(p0: number): ConstraintBuilder;
+declare function arg(p0: number, p1: number): ConstraintBuilder;
+declare function arg(p0: number, p1: number, p2: number): ConstraintBuilder;
+declare function arg(p0: number, p1: number, p2: number, p3: number): ConstraintBuilder;
+/** Target the `msg.sender` context property. */
+declare function msgSender(): ConstraintBuilder;
+/** Target the `msg.value` context property. */
+declare function msgValue(): ConstraintBuilder;
+/** Target the `block.timestamp` context property. */
+declare function blockTimestamp(): ConstraintBuilder;
+/** Target the `block.number` context property. */
+declare function blockNumber(): ConstraintBuilder;
+/** Target the `block.chainid` context property. */
+declare function chainId(): ConstraintBuilder;
+/** Target the `tx.origin` context property. */
+declare function txOrigin(): ConstraintBuilder;
+//#endregion
+//#region src/policy-builder.d.ts
+/** Fluent builder for constructing Callcium policies. */
+declare class PolicyBuilder {
+  private draft;
+  private constructor();
+  /**
+   * Create a builder from a function signature.
+   * @param signature - ABI function signature, e.g. `"transfer(address,uint256)"`.
+   */
+  static create(signature: string): PolicyBuilder;
+  /**
+   * Create a selectorless builder from a raw type string.
+   * @param typesCsv - Comma-separated ABI type strings, e.g. `"address,uint256"`.
+   */
+  static createRaw(typesCsv: string): PolicyBuilder;
+  /**
+   * Add a constraint to the current group.
+   * @param constraint - A `Constraint` object or a `ConstraintBuilder` instance.
+   */
+  add(constraint: Constraint | ConstraintBuilder): this;
+  /** Start a new constraint group (OR branch). */
+  or(): this;
+  /**
+   * Build the policy into an encoded binary blob.
+   * @returns The policy as a 0x-prefixed hex string.
+   * @throws {CallciumError} If any group is empty or validation finds errors.
+   */
+  build(): Hex;
+  /**
+   * Validate the policy without encoding.
+   * @returns All validation issues found.
+   */
+  validate(): Issue[];
+  /** Throw if any group is empty. */
+  private checkGroups;
+  /** Convert the draft to a PolicyData structure. */
+  private toPolicyData;
+}
+//#endregion
+//#region src/policy-coder.d.ts
+/**
+ * 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.
+ */
+declare function parsePathSteps(path: Hex): number[];
+/**
+ * Encode a PolicyData structure into the canonical binary format.
+ * @param data - The policy data to encode.
+ * @returns The encoded policy as a 0x-prefixed hex string.
+ */
+declare function encode(data: PolicyData): Hex;
+/**
+ * Decode a binary policy blob into a PolicyData structure.
+ * @param blob - Binary policy as 0x-prefixed hex string.
+ * @returns The decoded policy data with constraints grouped by scope and path.
+ * @throws {CallciumError} If the blob is structurally malformed.
+ */
+declare function decode(blob: Hex): PolicyData;
+/**
+ * Inspect a binary policy blob, returning the structural representation with full byte-level spans.
+ * @param blob - Binary policy as 0x-prefixed hex string.
+ * @returns The inspected policy with per-field spans for every structural element.
+ * @throws {CallciumError} If the blob is structurally malformed.
+ */
+declare function inspect$1(blob: Hex): DecodedPolicy;
+/** Encode, decode, and inspect policies in the canonical binary format. */
+declare const PolicyCoder: {
+  encode: typeof encode;
+  decode: typeof decode;
+  inspect: typeof inspect$1;
+};
+//#endregion
+//#region src/descriptor.d.ts
+/** Structural type information extracted from a descriptor node. */
+type TypeInfo = {
+  typeCode: number;
+  isDynamic: boolean;
+  staticSize: number;
+};
+/**
+ * Return the byte length of the node at `offset`.
+ * Elementary nodes occupy exactly one byte; composite nodes encode their
+ * length in the lower 12 bits of the 24-bit meta field.
+ */
+declare function nodeLength(desc: Uint8Array, offset: number): number;
+/**
+ * Return the byte offset of the `fieldIndex`-th field inside a tuple node.
+ * Starts at the first field and skips `fieldIndex` nodes using `nodeLength`.
+ */
+declare function tupleFieldOffset(desc: Uint8Array, tupleOffset: number, fieldIndex: number): number;
+/** Return paramCount from header byte 1. */
+declare function paramCount(desc: Uint8Array): number;
+/** Return byte offset of the N-th top-level param (0-indexed). */
+declare function paramOffset(desc: Uint8Array, index: number): number;
+/**
+ * Inspect the type node at a given byte offset.
+ * @param desc - Raw descriptor bytes.
+ * @param offset - Byte position of the node.
+ * @returns typeCode, isDynamic, and staticSize in bytes.
+ */
+declare function inspect(desc: Uint8Array, offset: number): TypeInfo;
+/**
+ * Resolve the type at a calldata path (array of step indices).
+ *
+ * The first step selects a top-level param. Each subsequent step descends
+ * into the current node: for tuples it selects a field, for arrays it
+ * advances to the element descriptor.
+ *
+ * @param desc - Raw descriptor bytes.
+ * @param steps - Path steps, length >= 1.
+ * @returns TypeInfo for the node at the resolved path.
+ * @throws {CallciumError} On empty steps, out-of-bounds param, or descent into elementary type.
+ */
+declare function typeAt(desc: Uint8Array, steps: number[]): TypeInfo;
+/**
+ * Return tuple field count at a tuple node offset.
+ * @param desc - Raw descriptor bytes.
+ * @param offset - Byte position of the tuple node.
+ */
+declare function tupleFieldCount(desc: Uint8Array, offset: number): number;
+/**
+ * Return static array length at a static array node offset.
+ * @param desc - Raw descriptor bytes.
+ * @param offset - Byte position of the static array node.
+ */
+declare function staticArrayLength(desc: Uint8Array, offset: number): number;
+/**
+ * Return the byte offset of the array element descriptor.
+ * @param offset - Byte position of the array node (static or dynamic).
+ */
+declare function arrayElementOffset(offset: number): number;
+/** Inspect and navigate raw descriptor bytes. */
+declare const Descriptor: {
+  paramCount: typeof paramCount;
+  paramOffset: typeof paramOffset;
+  inspect: typeof inspect;
+  typeAt: typeof typeAt;
+  tupleFieldOffset: typeof tupleFieldOffset;
+  tupleFieldCount: typeof tupleFieldCount;
+  staticArrayLength: typeof staticArrayLength;
+  nodeLength: typeof nodeLength;
+  arrayElementOffset: typeof arrayElementOffset;
+};
+//#endregion
+//#region src/policy-validator.d.ts
+/**
+ * True if operator `opCode` is allowed on a target with the given type info.
+ * Tolerates the NOT flag on `opCode`.
+ */
+declare function isOpAllowed(opCode: number, typeInfo: TypeInfo): boolean;
+/**
+ * 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.
+ */
+declare function validate(data: PolicyData): Issue[];
+/** Semantic validation for policies. */
+declare const PolicyValidator: {
+  validate: typeof validate;
+};
+//#endregion
+//#region src/policy-enforcer.d.ts
+/**
+ * Check a policy against ABI-encoded call data without throwing on violations.
+ * @param policy - Binary policy blob as 0x-prefixed hex string.
+ * @param callData - ABI-encoded call data as 0x-prefixed hex string.
+ * @param context - Optional execution context for context-scoped rules.
+ * @returns Pass with matched group index, or fail with one violation per failed group.
+ * @throws {CallciumError} If the policy blob is structurally malformed.
+ */
+declare function check(policy: Hex, callData: Hex, context?: Context): EnforceResult;
+/**
+ * Enforce a policy against ABI-encoded call data, throwing on violation.
+ * @param policy - Binary policy blob as 0x-prefixed hex string.
+ * @param callData - ABI-encoded call data as 0x-prefixed hex string.
+ * @param context - Optional execution context for context-scoped rules.
+ * @throws {PolicyViolationError} If the policy rejects the call data.
+ * @throws {CallciumError} If the policy blob is structurally malformed.
+ */
+declare function enforce(policy: Hex, callData: Hex, context?: Context): void;
+/** Check and enforce policies against ABI-encoded call data. */
+declare const PolicyEnforcer: {
+  check: typeof check;
+  enforce: typeof enforce;
+};
+//#endregion
+//#region src/bytes.d.ts
+/** Convert a hex string to a byte array, stripping the 0x prefix if present. */
+declare function hexToBytes(hex: string): Uint8Array;
+/** Convert a byte array to a 0x-prefixed lowercase hex string. */
+declare function bytesToHex(bytes: Uint8Array): Hex;
+/** Validate and brand a hex string as an address. Throws if the runtime length is not exactly 20 bytes. */
+declare function toAddress(hex: string): Address;
+//#endregion
+//#region src/descriptor-coder.d.ts
+/**
+ * Encode a comma-separated list of ABI type strings into a binary descriptor.
+ *
+ * @param typesCsv - Comma-separated ABI type strings, e.g. `"address,uint256,(bool,bytes32)[],string"`.
+ * @returns Binary descriptor bytes starting with the version+paramCount header.
+ * @throws {CallciumError} With code `INVALID_TYPE_STRING` for malformed input.
+ * @throws {CallciumError} With code `UNKNOWN_TYPE` for unrecognised type names.
+ */
+declare function fromTypes(typesCsv: string): Uint8Array;
+/**
+ * Reconstruct a comma-separated list of ABI type strings from a binary descriptor.
+ *
+ * Inverse of `fromTypes`: `toTypes(fromTypes(s))` returns `s` for any valid input.
+ *
+ * @param desc - Binary descriptor bytes (with version+paramCount header).
+ * @returns Comma-separated ABI type strings, e.g. `"address,uint256,(bool,bytes32)[]"`.
+ * @throws {CallciumError} If the descriptor is malformed.
+ */
+declare function toTypes(desc: Uint8Array): string;
+/** Encode and decode descriptors. */
+declare const DescriptorCoder: {
+  fromTypes: typeof fromTypes;
+  toTypes: typeof toTypes;
+};
+//#endregion
+//#region src/constants.d.ts
+/**
+ * Extract a `{ KEY: code }` map from a table with `key` and `code` fields.
+ * @internal
+ */
+type CodeMap<T extends readonly {
+  readonly key: string;
+  readonly code: number;
+}[]> = { readonly [E in T[number] as E["key"]]: E["code"] };
+/** Rule scope discriminant: context (EVM environment) vs. calldata (ABI payload). */
+declare const Scope: CodeMap<readonly [{
+  readonly key: "CONTEXT";
+  readonly code: 0;
+  readonly label: "context";
+}, {
+  readonly key: "CALLDATA";
+  readonly code: 1;
+  readonly label: "calldata";
+}]>;
+/** Display metadata for a scope code. */
+type ScopeInfo = {
+  label: string;
+};
+/**
+ * Map a scope code to its display label.
+ * @param code - Scope byte value.
+ * @returns Display metadata for the scope.
+ * @throws {CallciumError} If the code is not a recognised scope.
+ */
+declare function lookupScope(code: number): ScopeInfo;
+/** Well-known context property IDs for context-scope rules. */
+declare const ContextProperty: CodeMap<readonly [{
+  readonly key: "MSG_SENDER";
+  readonly code: 0;
+  readonly label: "msg.sender";
+  readonly typeCode: 64;
+}, {
+  readonly key: "MSG_VALUE";
+  readonly code: 1;
+  readonly label: "msg.value";
+  readonly typeCode: 31;
+}, {
+  readonly key: "BLOCK_TIMESTAMP";
+  readonly code: 2;
+  readonly label: "block.timestamp";
+  readonly typeCode: 31;
+}, {
+  readonly key: "BLOCK_NUMBER";
+  readonly code: 3;
+  readonly label: "block.number";
+  readonly typeCode: 31;
+}, {
+  readonly key: "CHAIN_ID";
+  readonly code: 4;
+  readonly label: "block.chainid";
+  readonly typeCode: 31;
+}, {
+  readonly key: "TX_ORIGIN";
+  readonly code: 5;
+  readonly label: "tx.origin";
+  readonly typeCode: 64;
+}]>;
+/** Display metadata for a context property code. */
+type ContextPropertyInfo = {
+  label: string;
+  contextKey: keyof Context;
+  typeCode: number;
+};
+/**
+ * Map a context property code to its display label and ABI type code.
+ * @param code - Context property ID.
+ * @returns Display metadata including the Solidity type code for the property value.
+ * @throws {CallciumError} If the code is not a recognised context property.
+ */
+declare function lookupContextProperty(code: number): ContextPropertyInfo;
+/** Protocol-imposed safety limits for path depth and quantifier array size. */
+declare const Limits: {
+  readonly MAX_PATH_DEPTH: 32;
+  readonly MAX_QUANTIFIED_ARRAY_LENGTH: 256;
+};
+/** Operand count category for operator data validation. */
+type Operands = "single" | "range" | "variadic";
+/** @internal */
+declare const OP_TABLE: readonly [{
+  readonly key: "EQ";
+  readonly code: 1;
+  readonly label: "==";
+  readonly operands: "single";
+}, {
+  readonly key: "GT";
+  readonly code: 2;
+  readonly label: ">";
+  readonly operands: "single";
+}, {
+  readonly key: "LT";
+  readonly code: 3;
+  readonly label: "<";
+  readonly operands: "single";
+}, {
+  readonly key: "GTE";
+  readonly code: 4;
+  readonly label: ">=";
+  readonly operands: "single";
+}, {
+  readonly key: "LTE";
+  readonly code: 5;
+  readonly label: "<=";
+  readonly operands: "single";
+}, {
+  readonly key: "BETWEEN";
+  readonly code: 6;
+  readonly label: "between";
+  readonly operands: "range";
+}, {
+  readonly key: "IN";
+  readonly code: 7;
+  readonly label: "in";
+  readonly operands: "variadic";
+}, {
+  readonly key: "BITMASK_ALL";
+  readonly code: 16;
+  readonly label: "bitmask all";
+  readonly operands: "single";
+}, {
+  readonly key: "BITMASK_ANY";
+  readonly code: 17;
+  readonly label: "bitmask any";
+  readonly operands: "single";
+}, {
+  readonly key: "BITMASK_NONE";
+  readonly code: 18;
+  readonly label: "bitmask none";
+  readonly operands: "single";
+}, {
+  readonly key: "LENGTH_EQ";
+  readonly code: 32;
+  readonly label: "length ==";
+  readonly operands: "single";
+}, {
+  readonly key: "LENGTH_GT";
+  readonly code: 33;
+  readonly label: "length >";
+  readonly operands: "single";
+}, {
+  readonly key: "LENGTH_LT";
+  readonly code: 34;
+  readonly label: "length <";
+  readonly operands: "single";
+}, {
+  readonly key: "LENGTH_GTE";
+  readonly code: 35;
+  readonly label: "length >=";
+  readonly operands: "single";
+}, {
+  readonly key: "LENGTH_LTE";
+  readonly code: 36;
+  readonly label: "length <=";
+  readonly operands: "single";
+}, {
+  readonly key: "LENGTH_BETWEEN";
+  readonly code: 37;
+  readonly label: "length between";
+  readonly operands: "range";
+}];
+/** Callcium policy operator codes. */
+declare const Op: CodeMap<typeof OP_TABLE> & {
+  readonly NOT: 0x80;
+};
+/** Display metadata for an operator code. */
+type OpInfo = {
+  label: string;
+  operands: Operands;
+};
+/**
+ * Map an operator code to its display label. Strips the NOT flag automatically.
+ * @param code - Operator byte value (may include the NOT flag).
+ * @returns Display metadata for the base operator.
+ * @throws {CallciumError} If the base code is not a recognised operator.
+ */
+declare function lookupOp(code: number): OpInfo;
+/** Reserved path step values that trigger quantified evaluation over array elements. */
+declare const Quantifier: CodeMap<readonly [{
+  readonly key: "ALL_OR_EMPTY";
+  readonly code: 65535;
+  readonly label: "all or empty";
+}, {
+  readonly key: "ALL";
+  readonly code: 65534;
+  readonly label: "all";
+}, {
+  readonly key: "ANY";
+  readonly code: 65533;
+  readonly label: "any";
+}]>;
+/** Display metadata for a quantifier step. */
+type QuantifierInfo = {
+  label: string;
+};
+/** Check whether a path step is a quantifier (ALL_OR_EMPTY, ALL, or ANY). */
+declare function isQuantifier(step: number): boolean;
+/**
+ * Map a quantifier path step to its display label.
+ * @param code - Quantifier step value.
+ * @returns Display metadata for the quantifier.
+ * @throws {CallciumError} If the code is not a recognised quantifier.
+ */
+declare function lookupQuantifier(code: number): QuantifierInfo;
+/** ABI type code ranges and sentinel values for the descriptor format. */
+declare const TypeCode: {
+  readonly UINT_MIN: 0;
+  readonly UINT_MAX: 31;
+  readonly INT_MIN: 32;
+  readonly INT_MAX: 63;
+  readonly ADDRESS: 64;
+  readonly BOOL: 65;
+  readonly FUNCTION: 66;
+  readonly FIXED_BYTES_MIN: 80;
+  readonly FIXED_BYTES_MAX: 111;
+  readonly BYTES: 112;
+  readonly STRING: 113;
+  readonly STATIC_ARRAY: 128;
+  readonly DYNAMIC_ARRAY: 129;
+  readonly TUPLE: 144;
+};
+/** Structural category for a descriptor type code. */
+type TypeClass = "elementary" | "tuple" | "staticArray" | "dynamicArray";
+/** Structural classification without label — used by the decoder hot path. */
+type TypeClassInfo = {
+  typeClass: TypeClass;
+  isDynamic: boolean;
+};
+/** Display metadata for a descriptor type code. */
+type TypeCodeInfo = TypeClassInfo & {
+  label: string;
+};
+/**
+ * Map a raw type code byte to its Solidity label, structural category, and dynamism.
+ * @param code - A single-byte descriptor type code.
+ * @returns Label, type class, and whether the type is ABI-dynamic.
+ * @throws {CallciumError} If the code is not a recognised type code.
+ */
+declare function lookupTypeCode(code: number): TypeCodeInfo;
+//#endregion
+//#region src/errors.d.ts
+/** Machine-readable error code for structural decoding and validation failures. */
+type CallciumErrorCode = "UNSUPPORTED_VERSION" | "MALFORMED_HEADER" | "UNEXPECTED_END" | "NODE_OVERFLOW" | "UNKNOWN_TYPE_CODE" | "INVALID_OPERATOR" | "INVALID_ARRAY_LENGTH" | "INVALID_TUPLE_FIELD_COUNT" | "PARAM_COUNT_MISMATCH" | "EMPTY_POLICY" | "EMPTY_GROUP" | "EMPTY_PATH" | "INVALID_CONTEXT_PATH" | "INVALID_CONTEXT_PROPERTY" | "INVALID_QUANTIFIER" | "INVALID_SCOPE" | "RULE_SIZE_MISMATCH" | "GROUP_SIZE_MISMATCH" | "GROUP_OVERFLOW" | "RULE_OVERFLOW" | "TRAILING_BYTES" | "INTERNAL_ERROR" | "INVALID_SIGNATURE" | "INVALID_TYPE_STRING" | "UNKNOWN_TYPE" | "DESCRIPTOR_TOO_LARGE" | "INVALID_PATH" | "DUPLICATE_PATH" | "INVALID_CONSTRAINT" | "INVALID_OPERATOR_DATA" | "EMPTY_SET" | "SET_TOO_LARGE" | "INVALID_RANGE" | "GROUP_COUNT_OVERFLOW" | "RULE_COUNT_OVERFLOW" | "RULE_SIZE_OVERFLOW" | "DESC_LENGTH_OVERFLOW" | "INVALID_HEX" | "VALIDATION_ERROR";
+/**
+ * Thrown when a policy or descriptor blob is structurally malformed.
+ * The optional `offset` indicates the byte position in the source blob where the error was detected.
+ */
+declare class CallciumError extends Error {
+  readonly code: CallciumErrorCode;
+  /** Byte position in the source blob where the error was detected, if applicable. */
+  readonly offset?: number;
+  constructor(code: CallciumErrorCode, message: string, offset?: number);
+}
+/**
+ * Thrown by `PolicyEnforcer.enforce` when calldata fails policy enforcement.
+ * Distinct from `CallciumError("VALIDATION_ERROR")`, which signals static
+ * issues in the policy itself.
+ * Carries the full list of violations (one per failed group).
+ */
+declare class PolicyViolationError extends Error {
+  readonly violations: Violation[];
+  constructor(violations: Violation[]);
+}
+//#endregion
+export { type Address, CallciumError, type CallciumErrorCode, type Constraint, type ConstraintBuilder, type Context, ContextProperty, type ContextPropertyInfo, type DecodedGroup, type DecodedParam, type DecodedPolicy, type DecodedRule, Descriptor, DescriptorCoder, type EnforceResult, type Field, type Hex, type Issue, type IssueCategory, type IssueSeverity, Limits, Op, type OpInfo, type Operands, PolicyBuilder, PolicyCoder, type PolicyData, PolicyEnforcer, PolicyValidator, PolicyViolationError, Quantifier, type QuantifierInfo, type ScalarValue, Scope, type ScopeInfo, type Span, type TypeClass, type TypeClassInfo, TypeCode, type TypeCodeInfo, type TypeInfo, type Violation, type ViolationCode, arg, blockNumber, blockTimestamp, bytesToHex, chainId, hexToBytes, isOpAllowed, isQuantifier, lookupContextProperty, lookupOp, lookupQuantifier, lookupScope, lookupTypeCode, msgSender, msgValue, parsePathSteps, toAddress, txOrigin };
+//# sourceMappingURL=index.d.ts.map