@rippling/rippling-sdk 0.2.0-alpha.104 → 0.2.0-alpha.106

package/resources/variable-compensation-payouts.mjs

@@ -7,9 +7,12 @@ import { path } from "../internal/utils/path.mjs";
  */
 export class VariableCompensationPayouts extends APIResource {
     /**
-     * A list of variable compensation payouts.
+     * List variable compensation payouts. Paginated with limit and cursor. Filters use
+     * the documented query parameters only (not OData filter). Always uses the company
+     * admin payout rowset; callers without admin payout visibility receive an empty
+     * list. Retrieve returns NotFound for the same rows.
      *
-     * - Requires: `API Tier 1`
+     * - Requires: `Variable Compensation Scheduled Payouts API`
      *
      * @example HTTP
      * Representative request and response shapes.

package/resources/variable-compensation-payouts.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"variable-compensation-payouts.mjs","sourceRoot":"","sources":["../src/resources/variable-compensation-payouts.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAG/C,OAAO,EAAE,aAAa,EAAe,+BAA2B;AAEhE,OAAO,EAAE,IAAI,EAAE,mCAA+B;AAE9C;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,WAAW;IAC1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,IAAI,CACF,QAAiE,EAAE,EACnE,OAAwB;QAKxB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAC5B,iCAAiC,EACjC,CAAA,aAAqD,CAAA,EACrD,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CACtB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoEG;IACH,MAAM,CACJ,IAA4C,EAC5C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,iCAAiC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,EAAU,EAAE,OAAwB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,kCAAkC,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;CACF"}
+{"version":3,"file":"variable-compensation-payouts.mjs","sourceRoot":"","sources":["../src/resources/variable-compensation-payouts.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAG/C,OAAO,EAAE,aAAa,EAAe,+BAA2B;AAEhE,OAAO,EAAE,IAAI,EAAE,mCAA+B;AAE9C;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,WAAW;IAC1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6DG;IACH,IAAI,CACF,QAAiE,EAAE,EACnE,OAAwB;QAKxB,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAC5B,iCAAiC,EACjC,CAAA,aAAqD,CAAA,EACrD,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CACtB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoEG;IACH,MAAM,CACJ,IAA4C,EAC5C,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,iCAAiC,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,EAAU,EAAE,OAAwB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,kCAAkC,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;CACF"}

package/src/client.ts

@@ -19,6 +19,14 @@ import { AbstractPage, PageCursorURLResponse } from './core/pagination';
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
+import {
+  ActivityLog,
+  ActivityLogListParams,
+  ActivityLogListResponse,
+  ActivityLogListResponsesPageCursorURL,
+  ActivityLogRetrieveParams,
+  ActivityLogRetrieveResponse,
+} from './resources/activity-log';
 import {
   AppUserListParams,
   AppUserListResponse,
@@ -483,6 +491,11 @@ import {
   PackageVersionComponentUpdateRetrieveResponse,
   PackageVersionComponentUpdates,
 } from './resources/package-version-component-updates';
+import {
+  PayrollPaymentModeChangeCreateParams,
+  PayrollPaymentModeChangeCreateResponse,
+  PayrollPaymentModeChanges,
+} from './resources/payroll-payment-mode-changes';
 import {
   PlatformCapabilities,
   PlatformCapabilityListResponse,
@@ -1682,6 +1695,10 @@ export class RipplingSDK {
    * Job related information for the company
    */
   jobPayRateExceptions: API.JobPayRateExceptions = new API.JobPayRateExceptions(this);
+  /**
+   * Visible Activity Log events recorded for the company
+   */
+  activityLog: API.ActivityLog = new API.ActivityLog(this);
   /**
    * Agents defined by the company
    */
@@ -1859,6 +1876,10 @@ export class RipplingSDK {
   packageVersionComponentUpdates: API.PackageVersionComponentUpdates = new API.PackageVersionComponentUpdates(
     this,
   );
+  /**
+   * Payroll runs for the company
+   */
+  payrollPaymentModeChanges: API.PayrollPaymentModeChanges = new API.PayrollPaymentModeChanges(this);
   /**
    * Payroll runs for the company
    */
@@ -1990,6 +2011,7 @@ RipplingSDK.BusinessPartnerGroups = BusinessPartnerGroups;
 RipplingSDK.Functions = Functions;
 RipplingSDK.JobAssignments = JobAssignments;
 RipplingSDK.JobPayRateExceptions = JobPayRateExceptions;
+RipplingSDK.ActivityLog = ActivityLog;
 RipplingSDK.Agents = Agents;
 RipplingSDK.AppUsers = AppUsers;
 RipplingSDK.BackgroundCheckCandidates = BackgroundCheckCandidates;
@@ -2036,6 +2058,7 @@ RipplingSDK.PackageUninstalls = PackageUninstalls;
 RipplingSDK.PackageUpgrades = PackageUpgrades;
 RipplingSDK.PackageVersions = PackageVersions;
 RipplingSDK.PackageVersionComponentUpdates = PackageVersionComponentUpdates;
+RipplingSDK.PayrollPaymentModeChanges = PayrollPaymentModeChanges;
 RipplingSDK.PayrollRuns = PayrollRuns;
 RipplingSDK.PlatformCapabilities = PlatformCapabilities;
 RipplingSDK.Reports = Reports;
@@ -2369,6 +2392,15 @@ export declare namespace RipplingSDK {
     type JobPayRateExceptionListChangeLogParams as JobPayRateExceptionListChangeLogParams,
   };
 
+  export {
+    ActivityLog as ActivityLog,
+    type ActivityLogListResponse as ActivityLogListResponse,
+    type ActivityLogRetrieveResponse as ActivityLogRetrieveResponse,
+    type ActivityLogListResponsesPageCursorURL as ActivityLogListResponsesPageCursorURL,
+    type ActivityLogListParams as ActivityLogListParams,
+    type ActivityLogRetrieveParams as ActivityLogRetrieveParams,
+  };
+
   export {
     Agents as Agents,
     type AgentListResponse as AgentListResponse,
@@ -2757,6 +2789,12 @@ export declare namespace RipplingSDK {
     type PackageVersionComponentUpdateCreateParams as PackageVersionComponentUpdateCreateParams,
   };
 
+  export {
+    PayrollPaymentModeChanges as PayrollPaymentModeChanges,
+    type PayrollPaymentModeChangeCreateResponse as PayrollPaymentModeChangeCreateResponse,
+    type PayrollPaymentModeChangeCreateParams as PayrollPaymentModeChangeCreateParams,
+  };
+
   export {
     PayrollRuns as PayrollRuns,
     type PayrollRunListResponse as PayrollRunListResponse,

package/src/lib/charts/README.md

@@ -0,0 +1,114 @@
+# Chart Rules
+
+Handwritten helpers for authoring the _behaviour_ of an AI-generated dashboard
+chart in a form that can be read back and edited.
+
+A dashboard chart is drawn by a visualization function the agent writes. Some of
+what that function decides — which colour a bar takes — is worked out fresh each
+render from the data. Written as ordinary code, that decision vanishes into the
+output: the chart shows _what_ colour it drew, never _why_. This library lets the
+agent state the decision as a small rule instead, so the settings panel can show
+it, explain it, and let a user change it.
+
+This is not a charting library. It does not render, own an ECharts option, fetch
+data, or touch the DOM. It produces and interprets plain data.
+
+## Scope (v1: conditional colour)
+
+v1 is deliberately narrow — the **colour channel only**: colour a series or datum
+by comparing its value against a constant.
+
+- **`value`** — this data point's plotted numeric value (a bar's height, a
+  point's y, a slice's amount). It is what the rule compares.
+- **Comparisons** — `equals`, `isNot`, `lessThan`, `greaterThan`, `lessOrEqual`, `greaterOrEqual`.
+- **`when(condition, ifTrue, ifFalse?)`** — a conditional value (channel-agnostic).
+  `ifFalse` is optional and defaults to `null` — for a colour, no override (default kept).
+- **`color(rule)`** — target the colour channel. Wrapping `when(...)` in `color(...)`
+  is what says "this rule sets the colour"; the channel is separate from the condition,
+  so more channels (opacity, label visibility) are just more wrappers later.
+- **`literal`** — bare constants (`100`, `'#E24B4A'`) are wrapped automatically.
+
+```ts
+import { color, when, lessThan, greaterThan, value } from '@rippling/rippling-sdk/lib/charts';
+
+// red when this point's value is below 100, blue otherwise
+const barColour = color(when(lessThan(value, 100), '#E24B4A', '#378ADD'));
+
+// highlight only the points over target; leave the rest their default colour
+const highlight = color(when(greaterThan(value, 1000), '#E24B4A'));
+```
+
+## Intended flow
+
+```text
+Agent writes a rule with these builders (the only consumer that imports the SDK)
+  -> color(when(lessThan(value, 100), '#E24B4A', '#378ADD'))  returns a {$rule} placeholder
+  -> the placeholder is emitted into the chart option, like the {$fn} placeholders
+     a chart already emits, and crosses to the app as plain JSON
+  -> renderer resolves {$rule} against the point's value -> a colour, drawn
+  -> settings panel reads the same {$rule} tree -> controls the user can edit
+```
+
+```json
+{
+  "channel": "color",
+  "$rule": {
+    "kind": "ifElse",
+    "cond": { "kind": "lessThan", "left": { "kind": "value" }, "right": { "kind": "literal", "value": 100 } },
+    "then": { "kind": "literal", "value": "#E24B4A" },
+    "else": { "kind": "literal", "value": "#378ADD" }
+  }
+}
+```
+
+`channel: 'color'` says what the rule targets, so a reader sees it without
+inferring from where it sits. `evaluate(rule, { value })` resolves it to a colour
+for the renderer; `describe(rule)` turns it into the controls the settings panel
+shows. Both accept the placeholder or the bare tree. A node can only ever be one
+of a fixed set of kinds, so the three faces never drift — the `chartRuleSchema`
+export describes that closed set.
+
+## How it is consumed
+
+The app never has to import this package. The rule crosses as data — a `{$rule}`
+placeholder alongside the `{$fn}` ones — and the app's own rehydrator resolves it
+at render time. Two ways, and only the first is needed:
+
+1. **Contract-only** — the app keeps its own small evaluator and validates it
+   against `chartRuleSchema` (published here) with a contract test, so the two
+   can't drift without CI noticing. No dependency on this package.
+2. **Shared** — the app imports `evaluate`/`describe` from here, so the closed
+   set is defined exactly once. A no-drift choice, not a requirement.
+
+## Where it is going
+
+The vocabulary starts small on purpose and is built to grow. Each addition is a
+new kind (or channel) — one builder, one `evaluate` case, one `describe` case,
+one `schema` entry — and it becomes editable in the panel the moment it lands,
+with no change to charts already using it. Planned next, roughly in order:
+
+- **More channels** — opacity, label visibility (`show`), and the like, added
+  alongside `channel: 'color'`.
+- **Collection refs + aggregates** — `rows`, `series`, and `count`/`sum`/`avg`/`min`/`max`,
+  so a rule can compare a point against the series (e.g. the max bar, or below average).
+- **Logic** — `and`, `or`, `not` to compose several conditions.
+- **More refs** — `index`, `name`, `field('column')`.
+- **`percentile`, arithmetic** (`plus`, `minus`, `mod`), **`between`, `isIn`**.
+- **Shaping** — `filter`, `sortBy`, `limit`, `groupSmallest` (change the data before it is drawn).
+
+## What this library does not do
+
+- It does not render or hold an ECharts option — it returns values and controls.
+- It has no I/O. A rule cannot reach the network, the DOM, or the clock, because
+  there is no node for it. Evaluating a rule reads only the context it is given.
+
+## Safety
+
+A rule is data, not code, so evaluating one is not running code. The vocabulary
+has no primitive with a side effect, so an untrusted, user-edited tree is safe
+to evaluate: the worst a malformed tree can do is throw a `ChartRuleError`, which
+the caller catches and turns into the read-only "configured in code" state. There
+are no loops or recursion, and a tree nested past `MAX_RULE_DEPTH` throws
+`RuleDepthError` (also a `ChartRuleError`) rather than overflowing the stack.
+Catch `ChartRuleError` — every failure mode is a subclass of it (`UnknownNodeError`,
+`RuleTypeError`, `RuleDepthError`).

package/src/lib/charts/builders.ts

@@ -0,0 +1,90 @@
+import { ChartRuleError } from './errors';
+import {
+  type ComparisonKind,
+  type ComparisonNode,
+  type IfElseNode,
+  type LiteralNode,
+  type RefNode,
+  type RuleNode,
+  type RulePlaceholder,
+  type Scalar,
+} from './types';
+
+/** A rule node, a nested rule (`{$rule}` placeholder), or a bare scalar. */
+export type Operand = RuleNode | RulePlaceholder | Scalar;
+
+function isRuleNode(operand: Operand): operand is RuleNode {
+  return typeof operand === 'object' && operand !== null && 'kind' in operand;
+}
+
+/** True when a value is a `{$rule}` placeholder — the marker the builders emit. */
+export function isRulePlaceholder(value: unknown): value is RulePlaceholder {
+  return typeof value === 'object' && value !== null && '$rule' in value;
+}
+
+/** Wrap a bare scalar as a literal node. */
+export function literal(value: Scalar): LiteralNode {
+  return { kind: 'literal', value };
+}
+
+function toNode(operand: Operand): RuleNode {
+  if (isRulePlaceholder(operand)) {
+    return operand.$rule; // a nested rule — unwrap it, never wrap it as a literal
+  }
+  return isRuleNode(operand) ? operand : literal(operand);
+}
+
+/**
+ * `value` — this data point's plotted numeric value: a bar's height, a point's
+ * y, a slice's amount. It is what a colour rule compares against a constant.
+ */
+export const value: RefNode = Object.freeze({ kind: 'value' });
+
+/* Comparisons — return a condition. */
+function comparison(kind: ComparisonKind): (left: Operand, right: Operand) => ComparisonNode {
+  return (left, right) => ({ kind, left: toNode(left), right: toNode(right) });
+}
+export const equals = comparison('equals');
+export const isNot = comparison('isNot');
+export const lessThan = comparison('lessThan');
+export const greaterThan = comparison('greaterThan');
+export const lessOrEqual = comparison('lessOrEqual');
+export const greaterOrEqual = comparison('greaterOrEqual');
+
+/**
+ * A conditional value: pick `ifTrue` when the condition holds, else `ifFalse`.
+ * Channel-agnostic — wrap it in a channel builder (`color`) to target something.
+ *
+ *   when(lessThan(value, 100), '#E24B4A', '#378ADD')
+ *   // → '#E24B4A' when this point's value is under 100, '#378ADD' otherwise
+ *
+ * `ifFalse` is optional and defaults to `null` — for a colour, that means no
+ * override (the chart's default is kept). Returns a plain node, not a placeholder.
+ */
+export function when(condition: RuleNode, ifTrue: Operand, ifFalse?: Operand): IfElseNode {
+  if (ifTrue === undefined) {
+    throw new ChartRuleError('when(condition, ifTrue, ifFalse?) needs a value for the true case');
+  }
+  return {
+    kind: 'ifElse',
+    cond: condition,
+    then: toNode(ifTrue),
+    else: toNode(ifFalse ?? null),
+  };
+}
+
+/**
+ * Target the colour channel — the v1 channel. Wrap a conditional value so the
+ * renderer knows it resolves to a colour, and the panel knows what it edits.
+ *
+ *   color(when(lessThan(value, 100), '#E24B4A', '#378ADD'))
+ *   // → red when this point's value is under 100, blue otherwise
+ *
+ * Takes a conditional value — a `when(...)` (`IfElseNode`) or an already-wrapped
+ * rule — not a bare `value` or comparison: those resolve to a number or a
+ * boolean, which is not a colour. `evaluate` enforces the same at runtime for a
+ * deserialized rule. Returns a `{$rule}` placeholder tagged `channel: 'color'`.
+ */
+export function color(rule: IfElseNode | RulePlaceholder): RulePlaceholder {
+  return { $rule: isRulePlaceholder(rule) ? rule.$rule : rule, channel: 'color' };
+}

package/src/lib/charts/describe.ts

@@ -0,0 +1,67 @@
+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';
+
+/**
+ * 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
+ * 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`.
+ */
+export function describe(rule: Rule): Control {
+  if (isRulePlaceholder(rule)) {
+    return visit(rule.$rule, 0);
+  }
+  return visit(rule, 0);
+}
+
+function visit(node: RuleNode, depth: number): Control {
+  if (depth > MAX_RULE_DEPTH) {
+    throw new RuleDepthError(MAX_RULE_DEPTH);
+  }
+  assertRuleNode(node);
+  const next = depth + 1;
+  switch (node.kind) {
+    case 'value':
+      return { role: 'ref', label: "this row's value" };
+    case 'literal': {
+      const scalar = literalValue(node);
+      return { role: 'literal', label: String(scalar), value: scalar };
+    }
+
+    case 'equals':
+      return comparison('is', node.left, node.right, next);
+    case 'isNot':
+      return comparison('is not', node.left, node.right, next);
+    case 'lessThan':
+      return comparison('is under', node.left, node.right, next);
+    case 'greaterThan':
+      return comparison('is over', node.left, node.right, next);
+    case 'lessOrEqual':
+      return comparison('is at most', node.left, node.right, next);
+    case 'greaterOrEqual':
+      return comparison('is at least', node.left, node.right, next);
+
+    case 'ifElse':
+      return {
+        role: 'rule',
+        label: 'when',
+        parts: [visit(node.cond, next), visit(node.then, next), visit(node.else, next)],
+      };
+
+    default:
+      return unreachable(node);
+  }
+}
+
+function comparison(label: string, left: RuleNode, right: RuleNode, depth: number): Control {
+  return { role: 'comparison', label, parts: [visit(left, depth), visit(right, depth)] };
+}
+
+function unreachable(node: never): never {
+  throw new UnknownNodeError((node as { kind?: string }).kind);
+}

package/src/lib/charts/errors.ts

@@ -0,0 +1,48 @@
+/** Base class for every error the chart-rule evaluator can throw. */
+export class ChartRuleError extends Error {}
+
+/**
+ * A node whose `kind` is not in the vocabulary. The caller catches this and
+ * shows the setting as "configured in code", read-only.
+ */
+export class UnknownNodeError extends ChartRuleError {
+  constructor(public readonly kind?: string) {
+    super(`Unknown chart-rule node: ${kind ?? '(missing kind)'}`);
+    this.name = 'UnknownNodeError';
+  }
+}
+
+/** A node evaluated to the wrong type of value (e.g. comparing non-numbers). */
+export class RuleTypeError extends ChartRuleError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RuleTypeError';
+  }
+}
+
+/**
+ * A structurally invalid node in a deserialized tree: 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
+ * `ChartRuleError`, so a caller reading an untrusted rule catches it instead of
+ * a native `TypeError` (or, worse, an `undefined` slipping through silently).
+ */
+export class MalformedRuleError extends ChartRuleError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MalformedRuleError';
+  }
+}
+
+/**
+ * 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.
+ */
+export class RuleDepthError extends ChartRuleError {
+  constructor(maxDepth: number) {
+    super(`chart rule nested deeper than ${maxDepth} levels`);
+    this.name = 'RuleDepthError';
+  }
+}

package/src/lib/charts/evaluate.ts

@@ -0,0 +1,114 @@
+import { isRulePlaceholder } from './builders';
+import { MalformedRuleError, RuleDepthError, RuleTypeError, UnknownNodeError } from './errors';
+import { assertRuleNode, literalValue } from './guards';
+import {
+  MAX_RULE_DEPTH,
+  type Rule,
+  type RuleChannel,
+  type RuleContext,
+  type RuleNode,
+  type RuleValue,
+} from './types';
+
+/**
+ * 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
+ * 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.
+ */
+export function evaluate(rule: Rule, ctx: RuleContext): RuleValue {
+  if (isRulePlaceholder(rule)) {
+    return coerceForChannel(rule.channel, visit(rule.$rule, ctx, 0));
+  }
+  return visit(rule, ctx, 0);
+}
+
+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;
+  switch (node.kind) {
+    case 'value':
+      return ctx.value;
+    case 'literal':
+      return literalValue(node);
+
+    case 'equals':
+      return visit(node.left, ctx, next) === visit(node.right, ctx, next);
+    case 'isNot':
+      return visit(node.left, ctx, next) !== visit(node.right, ctx, next);
+    case 'lessThan':
+      return num(visit(node.left, ctx, next)) < num(visit(node.right, ctx, next));
+    case 'greaterThan':
+      return num(visit(node.left, ctx, next)) > num(visit(node.right, ctx, next));
+    case 'lessOrEqual':
+      return num(visit(node.left, ctx, next)) <= num(visit(node.right, ctx, next));
+    case 'greaterOrEqual':
+      return num(visit(node.left, ctx, next)) >= num(visit(node.right, ctx, next));
+
+    case 'ifElse':
+      return bool(visit(node.cond, ctx, next)) ? visit(node.then, ctx, next) : visit(node.else, ctx, next);
+
+    default:
+      return unreachable(node);
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* 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 bool(value: RuleValue): boolean {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  throw new RuleTypeError(`expected a boolean, got ${typeName(value)}`);
+}
+
+/** A colour channel must resolve to a colour string, or null for "no override". */
+function asColor(value: RuleValue): RuleValue {
+  if (value === null || typeof value === 'string') {
+    return value;
+  }
+  throw new RuleTypeError(`a colour rule must resolve to a colour string or null, got ${typeName(value)}`);
+}
+
+/**
+ * Coerce a resolved value to what its channel can use. A colour rule must
+ * resolve to a colour; a future channel would add its own case here. A
+ * placeholder whose `channel` is missing or unrecognised (only possible from
+ * untrusted, deserialized input — the type and schema both pin it to `'color'`)
+ * is malformed rather than silently unchecked.
+ */
+function coerceForChannel(channel: RuleChannel, value: RuleValue): RuleValue {
+  switch (channel) {
+    case 'color':
+      return asColor(value);
+    default:
+      throw new MalformedRuleError(`a rule placeholder has an unsupported channel: ${String(channel)}`);
+  }
+}
+
+function typeName(value: RuleValue): string {
+  return value === null ? 'null' : typeof value;
+}
+
+function unreachable(node: never): never {
+  throw new UnknownNodeError((node as { kind?: string }).kind);
+}

package/src/lib/charts/guards.ts

@@ -0,0 +1,42 @@
+import { MalformedRuleError } from './errors';
+import { type RuleNode, type Scalar } from './types';
+
+/**
+ * Runtime validation for one node of a deserialized, untrusted rule tree, shared
+ * by `evaluate` and `describe`. A rule can arrive from JSON that TypeScript never
+ * checked, so `null`, a non-object, or a node without a string `kind` would throw
+ * a native `TypeError` on the first field read — skipping the `ChartRuleError`
+ * escape hatch a caller relies on. Validate before reading fields.
+ */
+
+const SCALAR_TYPES: ReadonlySet<string> = new Set(['number', 'string', 'boolean']);
+
+/**
+ * Assert `node` is shaped like a rule node — an object carrying a string `kind`.
+ * An unrecognised `kind` is *not* rejected here; that is the caller's `switch`
+ * default (`UnknownNodeError`), the deliberate "configured in code" signal.
+ */
+export function assertRuleNode(node: unknown): asserts node is RuleNode {
+  if (
+    node === null ||
+    typeof node !== 'object' ||
+    Array.isArray(node) ||
+    typeof (node as { kind?: unknown }).kind !== 'string'
+  ) {
+    throw new MalformedRuleError('a rule node must be an object with a string "kind"');
+  }
+}
+
+/**
+ * Read a `literal` node's `value`, rejecting a missing or non-scalar one. Without
+ * this, `{ kind: 'literal' }` resolves to `undefined` and slips past the caller.
+ */
+export function literalValue(node: { value?: unknown }): Scalar {
+  const { value } = node;
+  if (value === null || SCALAR_TYPES.has(typeof value)) {
+    return value as Scalar;
+  }
+  throw new MalformedRuleError(
+    `a literal must carry a scalar value, got ${value === undefined ? 'undefined' : typeof value}`,
+  );
+}

package/src/lib/charts/schema.ts

@@ -0,0 +1,72 @@
+import { CHART_RULE_CONTRACT_VERSION } from './types';
+
+/** Stable identifier for the published contract, versioned by the tag. */
+export const CHART_RULE_SCHEMA_ID = `https://rippling.com/schemas/${CHART_RULE_CONTRACT_VERSION}.json`;
+
+/**
+ * JSON Schema (2020-12) for the `{$rule}` placeholder and its closed node set.
+ *
+ * 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.
+ */
+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;