@rippling/rippling-sdk 0.2.0-alpha.107 → 0.2.0-alpha.109

package/src/lib/charts/describe.ts

@@ -1,56 +1,50 @@
-import { isRulePlaceholder } from './builders';
-import { RuleDepthError, UnknownNodeError } from './errors';
-import { assertRuleNode, literalValue } from './guards';
-import { MAX_RULE_DEPTH, type Control, type Rule, type RuleNode } from './types';
+import { UnknownNodeError } from './errors';
+import { parseChartRule } from './schema';
+import { type ComparisonOperandNode, type Control, type RuleNode } from './types';
 
 /**
  * Turn a rule into the shape the settings panel renders: a label plus its
- * editable parts. Accepts a `{$rule}` placeholder or a bare tree. Walks the same
- * tree `evaluate` runs — and validates each node the same way — so a malformed or
+ * editable parts. Accepts a `{$rule}` placeholder or a bare node. Reads the same
+ * value `evaluate` runs — and validates it the same way — so a malformed or
  * unknown node throws a `ChartRuleError` here too, never a native `TypeError`.
- * The unwrap is gated on `isRulePlaceholder` (not a raw `'$rule' in rule`) so a
- * `null`/primitive rule reaches `assertRuleNode` instead of throwing on `in`.
- * A tree nested past `MAX_RULE_DEPTH` throws `RuleDepthError`.
+ * The Valibot parser rejects malformed or nested values before this flat
+ * formatter reads them.
  */
-export function describe(rule: Rule): Control {
-  if (isRulePlaceholder(rule)) {
-    return visit(rule.$rule, 0);
+export function describe(rule: unknown): Control {
+  const parsedRule = parseChartRule(rule);
+  if ('$rule' in parsedRule) {
+    return visit(parsedRule.$rule);
   }
-  return visit(rule, 0);
+  return visit(parsedRule);
 }
 
-function visit(node: RuleNode, depth: number): Control {
-  if (depth > MAX_RULE_DEPTH) {
-    throw new RuleDepthError(MAX_RULE_DEPTH);
-  }
-  assertRuleNode(node);
-  const next = depth + 1;
+function visit(node: RuleNode): Control {
   switch (node.kind) {
     case 'value':
       return { role: 'ref', label: "this row's value" };
     case 'literal': {
-      const scalar = literalValue(node);
+      const scalar = node.value;
       return { role: 'literal', label: String(scalar), value: scalar };
     }
 
     case 'equals':
-      return comparison('is', node.left, node.right, next);
+      return comparison('is', node.left, node.right);
     case 'isNot':
-      return comparison('is not', node.left, node.right, next);
+      return comparison('is not', node.left, node.right);
     case 'lessThan':
-      return comparison('is under', node.left, node.right, next);
+      return comparison('is under', node.left, node.right);
     case 'greaterThan':
-      return comparison('is over', node.left, node.right, next);
+      return comparison('is over', node.left, node.right);
     case 'lessOrEqual':
-      return comparison('is at most', node.left, node.right, next);
+      return comparison('is at most', node.left, node.right);
     case 'greaterOrEqual':
-      return comparison('is at least', node.left, node.right, next);
+      return comparison('is at least', node.left, node.right);
 
     case 'ifElse':
       return {
         role: 'rule',
         label: 'when',
-        parts: [visit(node.cond, next), visit(node.then, next), visit(node.else, next)],
+        parts: [visit(node.cond), literalControl(node.then.value), literalControl(node.else.value)],
       };
 
     default:
@@ -58,8 +52,16 @@ function visit(node: RuleNode, depth: number): Control {
   }
 }
 
-function comparison(label: string, left: RuleNode, right: RuleNode, depth: number): Control {
-  return { role: 'comparison', label, parts: [visit(left, depth), visit(right, depth)] };
+function comparison(label: string, left: ComparisonOperandNode, right: ComparisonOperandNode): Control {
+  return { role: 'comparison', label, parts: [operandControl(left), operandControl(right)] };
+}
+
+function operandControl(node: ComparisonOperandNode): Control {
+  return node.kind === 'value' ? { role: 'ref', label: "this row's value" } : literalControl(node.value);
+}
+
+function literalControl(value: string | number | boolean | null): Control {
+  return { role: 'literal', label: String(value), value };
 }
 
 function unreachable(node: never): never {

package/src/lib/charts/errors.ts

@@ -21,7 +21,7 @@ export class RuleTypeError extends ChartRuleError {
 }
 
 /**
- * A structurally invalid node in a deserialized tree: not an object, no string
+ * A structurally invalid node in a deserialized value: not an object, no string
  * `kind`, or a `literal` without a scalar `value`. Distinct from
  * `UnknownNodeError` (a well-formed node whose `kind` is simply not in the
  * vocabulary — the intentional escape hatch). Like the others it is a
@@ -35,11 +35,7 @@ export class MalformedRuleError extends ChartRuleError {
   }
 }
 
-/**
- * A rule nested deeper than the evaluator will walk. Guards against a
- * stack-overflowing tree from untrusted, deserialized input; like the others it
- * is a `ChartRuleError`, so the caller's escape hatch catches it.
- */
+/** @deprecated v1 is non-recursive. Retained for source compatibility. */
 export class RuleDepthError extends ChartRuleError {
   constructor(maxDepth: number) {
     super(`chart rule nested deeper than ${maxDepth} levels`);

package/src/lib/charts/evaluate.ts

@@ -1,9 +1,8 @@
-import { isRulePlaceholder } from './builders';
-import { MalformedRuleError, RuleDepthError, RuleTypeError, UnknownNodeError } from './errors';
-import { assertRuleNode, literalValue } from './guards';
+import { MalformedRuleError, RuleTypeError, UnknownNodeError } from './errors';
+import { parseChartRule } from './schema';
 import {
-  MAX_RULE_DEPTH,
-  type Rule,
+  type ComparisonOperandNode,
+  type NumericOperandNode,
   type RuleChannel,
   type RuleContext,
   type RuleNode,
@@ -12,51 +11,45 @@ import {
 
 /**
  * Resolve a rule to a value against `ctx`. Accepts a `{$rule}` placeholder or a
- * bare tree. A malformed or unknown node throws a `ChartRuleError` (never a
+ * bare node. A malformed or unknown node throws a `ChartRuleError` (never a
  * native `TypeError`), so a caller reading an untrusted, deserialized rule can
  * catch every failure with one type. When the rule is a colour placeholder, the
  * result is checked to be a colour (`string | null`) — a rule that resolves to a
  * number or boolean is a `RuleTypeError`, not something the renderer paints.
  *
- * Pure: the only inputs are the node and the context. No clock, no randomness,
- * no I/O — which is what makes it safe to run on an untrusted, user-edited tree
- * and identical across the renderer, the panel readout, and a test. A tree
- * nested past `MAX_RULE_DEPTH` throws `RuleDepthError` rather than overflowing.
+ * Pure and non-recursive: the only inputs are the validated flat rule and the
+ * context. No clock, randomness, callbacks, or I/O.
  */
-export function evaluate(rule: Rule, ctx: RuleContext): RuleValue {
-  if (isRulePlaceholder(rule)) {
-    return coerceForChannel(rule.channel, visit(rule.$rule, ctx, 0));
+export function evaluate(rule: unknown, ctx: RuleContext): RuleValue {
+  const parsedRule = parseChartRule(rule);
+  if ('$rule' in parsedRule) {
+    return coerceForChannel(parsedRule.channel, visit(parsedRule.$rule, ctx));
   }
-  return visit(rule, ctx, 0);
+  return visit(parsedRule, ctx);
 }
 
-function visit(node: RuleNode, ctx: RuleContext, depth: number): RuleValue {
-  if (depth > MAX_RULE_DEPTH) {
-    throw new RuleDepthError(MAX_RULE_DEPTH);
-  }
-  assertRuleNode(node);
-  const next = depth + 1;
+function visit(node: RuleNode, ctx: RuleContext): RuleValue {
   switch (node.kind) {
     case 'value':
       return ctx.value;
     case 'literal':
-      return literalValue(node);
+      return node.value;
 
     case 'equals':
-      return visit(node.left, ctx, next) === visit(node.right, ctx, next);
+      return operand(node.left, ctx) === operand(node.right, ctx);
     case 'isNot':
-      return visit(node.left, ctx, next) !== visit(node.right, ctx, next);
+      return operand(node.left, ctx) !== operand(node.right, ctx);
     case 'lessThan':
-      return num(visit(node.left, ctx, next)) < num(visit(node.right, ctx, next));
+      return numericOperand(node.left, ctx) < numericOperand(node.right, ctx);
     case 'greaterThan':
-      return num(visit(node.left, ctx, next)) > num(visit(node.right, ctx, next));
+      return numericOperand(node.left, ctx) > numericOperand(node.right, ctx);
     case 'lessOrEqual':
-      return num(visit(node.left, ctx, next)) <= num(visit(node.right, ctx, next));
+      return numericOperand(node.left, ctx) <= numericOperand(node.right, ctx);
     case 'greaterOrEqual':
-      return num(visit(node.left, ctx, next)) >= num(visit(node.right, ctx, next));
+      return numericOperand(node.left, ctx) >= numericOperand(node.right, ctx);
 
     case 'ifElse':
-      return bool(visit(node.cond, ctx, next)) ? visit(node.then, ctx, next) : visit(node.else, ctx, next);
+      return visit(node.cond, ctx) ? node.then.value : node.else.value;
 
     default:
       return unreachable(node);
@@ -67,18 +60,12 @@ function visit(node: RuleNode, ctx: RuleContext, depth: number): RuleValue {
 /* Coercions — narrow a RuleValue, or throw a typed error.                      */
 /* -------------------------------------------------------------------------- */
 
-function num(value: RuleValue): number {
-  if (typeof value === 'number') {
-    return value;
-  }
-  throw new RuleTypeError(`expected a number, got ${typeName(value)}`);
+function operand(node: ComparisonOperandNode, ctx: RuleContext): RuleValue {
+  return node.kind === 'value' ? ctx.value : node.value;
 }
 
-function bool(value: RuleValue): boolean {
-  if (typeof value === 'boolean') {
-    return value;
-  }
-  throw new RuleTypeError(`expected a boolean, got ${typeName(value)}`);
+function numericOperand(node: NumericOperandNode, ctx: RuleContext): number {
+  return node.kind === 'value' ? ctx.value : node.value;
 }
 
 /** A colour channel must resolve to a colour string, or null for "no override". */

package/src/lib/charts/schema.ts

@@ -1,72 +1,238 @@
-import { CHART_RULE_CONTRACT_VERSION } from './types';
+import {
+  type BaseIssue,
+  boolean,
+  type GenericSchema,
+  finite,
+  literal,
+  null_,
+  number,
+  picklist,
+  pipe,
+  safeParse,
+  strictObject,
+  string,
+  summarize,
+  union,
+  variant,
+} from 'valibot';
 
-/** Stable identifier for the published contract, versioned by the tag. */
+import { MalformedRuleError, UnknownNodeError } from './errors';
+import { CHART_RULE_CONTRACT_VERSION, type ParsedRule, type Rule, type RuleNode, type Scalar } from './types';
+import {
+  EQUALITY_COMPARISON_KINDS,
+  NUMERIC_COMPARISON_KINDS,
+  RULE_CHANNELS,
+  RULE_NODE_KINDS,
+} from './vocabulary';
+
+const ruleNodeKinds: ReadonlySet<string> = new Set(RULE_NODE_KINDS);
+const placeholderKeys: ReadonlySet<string> = new Set(['$rule', 'channel']);
+const ruleFieldKeys = ['$rule', 'channel', 'kind', 'value', 'left', 'right', 'cond', 'then', 'else'] as const;
+const scalarSchema: GenericSchema<unknown, Scalar> = union([
+  pipe(number(), finite()),
+  string(),
+  boolean(),
+  null_(),
+]);
+
+const parsedRules = new WeakSet<object>();
+
+/** @deprecated Use `CHART_RULE_CONTRACT_VERSION` to identify the executable contract. */
 export const CHART_RULE_SCHEMA_ID = `https://rippling.com/schemas/${CHART_RULE_CONTRACT_VERSION}.json`;
 
+function hasOwn(value: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+const refNodeSchema = strictObject({ kind: literal('value') });
+const literalNodeSchema = strictObject({ kind: literal('literal'), value: scalarSchema });
+const numericLiteralNodeSchema = strictObject({
+  kind: literal('literal'),
+  value: pipe(number(), finite()),
+});
+const requiredColorLiteralNodeSchema = strictObject({
+  kind: literal('literal'),
+  value: string(),
+});
+const optionalColorLiteralNodeSchema = strictObject({
+  kind: literal('literal'),
+  value: union([string(), null_()]),
+});
+const comparisonOperandSchema = variant('kind', [refNodeSchema, literalNodeSchema]);
+const numericOperandSchema = variant('kind', [refNodeSchema, numericLiteralNodeSchema]);
+
+const equalityComparisonNodeSchema = strictObject({
+  kind: picklist(EQUALITY_COMPARISON_KINDS),
+  left: comparisonOperandSchema,
+  right: comparisonOperandSchema,
+});
+
+const numericComparisonNodeSchema = strictObject({
+  kind: picklist(NUMERIC_COMPARISON_KINDS),
+  left: numericOperandSchema,
+  right: numericOperandSchema,
+});
+
+const comparisonNodeSchema = variant('kind', [equalityComparisonNodeSchema, numericComparisonNodeSchema]);
+
+const ifElseNodeSchema = strictObject({
+  kind: literal('ifElse'),
+  cond: comparisonNodeSchema,
+  then: requiredColorLiteralNodeSchema,
+  else: optionalColorLiteralNodeSchema,
+});
+
 /**
- * JSON Schema (2020-12) for the `{$rule}` placeholder and its closed node set.
+ * Executable runtime schema for a chart-rule node.
  *
- * This is the contract. A consumer that keeps its own rule evaluator (rather
- * than importing `evaluate`) can validate against this so the two never drift —
- * every kind and operand shape the builders can emit is described here.
+ * v1 is intentionally non-recursive. A comparison contains only `value` or
+ * literal operands, and a conditional contains one comparison plus two colour
+ * literals. Contract tests prove that every public builder output parses.
+ */
+const ruleNodeSchema: GenericSchema<unknown, RuleNode, BaseIssue<unknown>> = variant('kind', [
+  refNodeSchema,
+  literalNodeSchema,
+  equalityComparisonNodeSchema,
+  numericComparisonNodeSchema,
+  ifElseNodeSchema,
+]);
+
+/** Runtime schema for the `{$rule, channel}` value embedded in a chart option. */
+const rulePlaceholderSchema = strictObject({
+  $rule: ifElseNodeSchema,
+  channel: picklist(RULE_CHANNELS),
+});
+
+/**
+ * Runtime schema for either a bare rule node or a chart-option placeholder.
+ * Persisted and agent-authored JSON crosses this boundary as `unknown`.
+ */
+export const chartRuleSchema: GenericSchema<unknown, Rule, BaseIssue<unknown>> = union([
+  rulePlaceholderSchema,
+  ruleNodeSchema,
+]);
+
+/** Parse untrusted chart-rule JSON and return an immutable validated clone. */
+export function parseChartRule(input: unknown): ParsedRule {
+  if (isParsedRule(input)) {
+    return input;
+  }
+  preflight(input);
+  const result = safeParse(chartRuleSchema, input);
+  if (result.success) {
+    return markParsedRule(result.output);
+  }
+  throw new MalformedRuleError(summarize(result.issues));
+}
+
+/**
+ * Valibot's object schemas use `key in input`, which also reads inherited
+ * properties. Reject inherited rule fields before parsing so prototype data
+ * cannot supply required operands or bypass the flat v1 contract.
  */
-export const chartRuleSchema = {
-  $schema: 'https://json-schema.org/draft/2020-12/schema',
-  $id: CHART_RULE_SCHEMA_ID,
-  title: 'Chart rule placeholder',
-  description: 'A rule tree the chart agent emits into a chart option, marked with $rule.',
-  type: 'object',
-  required: ['$rule', 'channel'],
-  additionalProperties: false,
-  properties: {
-    // A colour rule's top-level tree is the conditional-value form (`when(...)`),
-    // matching what `color()` builds and accepts. A bare ref/comparison/literal
-    // resolves to a number/boolean/constant, not a colour decision.
-    $rule: { $ref: '#/$defs/ifElse' },
-    channel: { const: 'color' },
-  },
-  $defs: {
-    scalar: { type: ['number', 'string', 'boolean', 'null'] },
-    node: {
-      oneOf: [
-        { $ref: '#/$defs/ref' },
-        { $ref: '#/$defs/literal' },
-        { $ref: '#/$defs/comparison' },
-        { $ref: '#/$defs/ifElse' },
-      ],
-    },
-    ref: {
-      type: 'object',
-      required: ['kind'],
-      additionalProperties: false,
-      properties: { kind: { const: 'value' } },
-    },
-    literal: {
-      type: 'object',
-      required: ['kind', 'value'],
-      additionalProperties: false,
-      properties: { kind: { const: 'literal' }, value: { $ref: '#/$defs/scalar' } },
-    },
-    comparison: {
-      type: 'object',
-      required: ['kind', 'left', 'right'],
-      additionalProperties: false,
-      properties: {
-        kind: { enum: ['equals', 'isNot', 'lessThan', 'greaterThan', 'lessOrEqual', 'greaterOrEqual'] },
-        left: { $ref: '#/$defs/node' },
-        right: { $ref: '#/$defs/node' },
-      },
-    },
-    ifElse: {
-      type: 'object',
-      required: ['kind', 'cond', 'then', 'else'],
-      additionalProperties: false,
-      properties: {
-        kind: { const: 'ifElse' },
-        cond: { $ref: '#/$defs/node' },
-        then: { $ref: '#/$defs/node' },
-        else: { $ref: '#/$defs/node' },
-      },
-    },
-  },
-} as const;
+function preflight(input: unknown): void {
+  assertNoInheritedRuleFields(input);
+  const root = unwrapPlaceholder(input);
+  assertNoInheritedRuleFields(root);
+  assertKnownNode(root);
+
+  if (!isRecord(root) || !hasOwn(root, 'kind')) {
+    return;
+  }
+  if (root['kind'] === 'ifElse') {
+    inspectChildren(root, ['cond', 'then', 'else']);
+    const condition = root['cond'];
+    inspectComparison(condition);
+  } else if (typeof root['kind'] === 'string' && isComparisonKind(root['kind'])) {
+    inspectComparison(root);
+  }
+}
+
+function inspectComparison(value: unknown): void {
+  assertNoInheritedRuleFields(value);
+  assertKnownNode(value);
+  if (isRecord(value)) {
+    inspectChildren(value, ['left', 'right']);
+  }
+}
+
+function inspectChildren(parent: Record<string, unknown>, keys: readonly string[]): void {
+  for (const key of keys) {
+    if (hasOwn(parent, key)) {
+      const child = parent[key];
+      assertNoInheritedRuleFields(child);
+      assertKnownNode(child);
+    }
+  }
+}
+
+function assertNoInheritedRuleFields(value: unknown): void {
+  if (!isRecord(value)) {
+    return;
+  }
+  for (const key of ruleFieldKeys) {
+    if (key in value && !hasOwn(value, key)) {
+      throw new MalformedRuleError(`a chart rule must not inherit the ${key} property`);
+    }
+  }
+}
+
+function assertKnownNode(value: unknown): void {
+  if (
+    isRecord(value) &&
+    hasOwn(value, 'kind') &&
+    typeof value['kind'] === 'string' &&
+    !ruleNodeKinds.has(value['kind'])
+  ) {
+    throw new UnknownNodeError(value['kind']);
+  }
+}
+
+function isComparisonKind(kind: string): boolean {
+  return kind !== 'literal' && kind !== 'value' && kind !== 'ifElse' && ruleNodeKinds.has(kind);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function unwrapPlaceholder(input: unknown): unknown {
+  if (input === null || typeof input !== 'object' || Array.isArray(input) || !hasOwn(input, '$rule')) {
+    return input;
+  }
+  const unexpectedKey = Object.keys(input).find((key) => !placeholderKeys.has(key));
+  if (unexpectedKey !== undefined) {
+    throw new MalformedRuleError(`a rule placeholder has an unexpected property: ${unexpectedKey}`);
+  }
+  return (input as { $rule?: unknown }).$rule;
+}
+
+function isParsedRule(input: unknown): input is ParsedRule {
+  return input !== null && typeof input === 'object' && !Array.isArray(input) && parsedRules.has(input);
+}
+
+/**
+ * Mark the validated clone so `evaluate(parseChartRule(input), ctx)` does not
+ * reparse the full value for every datum. Freezing prevents a caller from
+ * mutating a trusted value after validation.
+ */
+function markParsedRule(rule: Rule): ParsedRule {
+  const stack: object[] = [rule];
+  const seen = new WeakSet<object>();
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current || seen.has(current)) {
+      continue;
+    }
+    seen.add(current);
+    for (const value of Object.values(current)) {
+      if (value !== null && typeof value === 'object') {
+        stack.push(value);
+      }
+    }
+    Object.freeze(current);
+  }
+
+  parsedRules.add(rule);
+  return rule as ParsedRule;
+}

package/src/lib/charts/types.ts

@@ -1,18 +1,22 @@
 /**
  * Chart rule vocabulary — shared types.
  *
- * A rule is a small, serializable tree of nodes discriminated by `kind`. The
+ * A rule is a small, serializable value discriminated by `kind`. The
  * agent builds it with the helpers in `builders.ts`, which emit it wrapped in a
  * `{$rule}` placeholder — the same idea as the `{$fn}` placeholders a chart
  * already emits. The renderer resolves it with `evaluate`; the settings panel
  * reads it with `describe`. All three agree because a node can only ever be one
- * of the kinds defined here — the closed set the `chartRuleSchema` describes.
+ * of the kinds defined here — the closed set the executable `chartRuleSchema`
+ * validates at runtime.
  *
- * v1 is scoped to conditional formatting: compare this datum's `value` against a
- * constant, and (optionally) pick between two values. Richer pieces — aggregates,
- * logic, more refs — are the documented roadmap in the README.
+ * v1 is deliberately non-recursive: compare this datum's `value` or a literal
+ * against another literal, then choose between two colour literals. Rules may
+ * not appear inside operands or branches. Richer expressions require a future
+ * contract version.
  */
 
+import { COMPARISON_KINDS, RULE_CHANNELS } from './vocabulary';
+
 export const CHART_RULE_CONTRACT_VERSION = 'chart_rule.v1' as const;
 export type ChartRuleContractVersion = typeof CHART_RULE_CONTRACT_VERSION;
 
@@ -26,33 +30,39 @@ export type Scalar = number | string | boolean | null;
 /** Reads a value out of the evaluation context — this datum's plotted value. */
 export type RefNode = { kind: 'value' };
 
-export interface LiteralNode {
+export interface LiteralNode<TValue extends Scalar = Scalar> {
   kind: 'literal';
-  value: Scalar;
+  value: TValue;
 }
 
-export type ComparisonKind =
-  | 'equals'
-  | 'isNot'
-  | 'lessThan'
-  | 'greaterThan'
-  | 'lessOrEqual'
-  | 'greaterOrEqual';
-export interface ComparisonNode {
-  kind: ComparisonKind;
-  left: RuleNode;
-  right: RuleNode;
+export type ComparisonOperandNode = RefNode | LiteralNode;
+export type NumericOperandNode = RefNode | LiteralNode<number>;
+
+export type ComparisonKind = (typeof COMPARISON_KINDS)[number];
+export interface EqualityComparisonNode {
+  kind: 'equals' | 'isNot';
+  left: ComparisonOperandNode;
+  right: ComparisonOperandNode;
 }
+export interface NumericComparisonNode {
+  kind: Exclude<ComparisonKind, EqualityComparisonNode['kind']>;
+  left: NumericOperandNode;
+  right: NumericOperandNode;
+}
+export type ComparisonNode = EqualityComparisonNode | NumericComparisonNode;
+
+/** A node whose evaluated result is valid as a `when(...)` condition in v1. */
+export type ConditionNode = ComparisonNode;
 
 /** The conditional-value form produced by `when(cond, then, else)`. */
 export interface IfElseNode {
   kind: 'ifElse';
-  cond: RuleNode;
-  then: RuleNode;
-  else: RuleNode;
+  cond: ConditionNode;
+  then: LiteralNode<string>;
+  else: LiteralNode<string | null>;
 }
 
-/** Any node of a rule tree. */
+/** Any top-level node accepted by the v1 runtime boundary. */
 export type RuleNode = RefNode | LiteralNode | ComparisonNode | IfElseNode;
 
 /* -------------------------------------------------------------------------- */
@@ -64,21 +74,26 @@ export type RuleNode = RefNode | LiteralNode | ComparisonNode | IfElseNode;
  * colour of a series/datum. Other channels (opacity, label visibility, …) are
  * the documented roadmap and would be added here.
  */
-export type RuleChannel = 'color';
+export type RuleChannel = (typeof RULE_CHANNELS)[number];
 
 /**
- * What a builder returns: a rule tree, marked so the renderer can find it, and
+ * What a builder returns: a flat rule value, marked so the renderer can find it, and
  * tagged with the channel it targets. `channel: 'color'` says this resolves to a
  * colour — so a reader sees the target without inferring it from where it sits.
  */
 export interface RulePlaceholder {
-  $rule: RuleNode;
+  $rule: IfElseNode;
   channel: RuleChannel;
 }
 
-/** A placeholder, or the bare tree — what `evaluate` and `describe` accept. */
+/** A placeholder, or a bare node — what `evaluate` and `describe` accept. */
 export type Rule = RulePlaceholder | RuleNode;
 
+type DeepReadonly<T> = T extends object ? { readonly [Key in keyof T]: DeepReadonly<T[Key]> } : T;
+
+/** The deeply frozen value returned by `parseChartRule`. */
+export type ParsedRule = DeepReadonly<Rule>;
+
 /* -------------------------------------------------------------------------- */
 /* Evaluation                                                                   */
 /* -------------------------------------------------------------------------- */
@@ -91,11 +106,7 @@ export interface RuleContext {
 /** The result of evaluating a node. */
 export type RuleValue = Scalar;
 
-/**
- * The deepest a rule may nest before `evaluate`/`describe` refuse it. Real rules
- * are a handful of levels; this only stops a pathological deserialized tree from
- * overflowing the stack. Far below the JS call-stack limit.
- */
+/** @deprecated v1 is non-recursive. Retained for source compatibility. */
 export const MAX_RULE_DEPTH = 256;
 
 /* -------------------------------------------------------------------------- */