@revturbine/cli 0.19.2 → 0.19.4

package/README.md

@@ -80,7 +80,7 @@ Commands that read a config name the version explicitly — there is no default:
 | `status` | The live Release and the open draft, side by side. |
 | `history` | The Release Version Log, newest first. |
 | `preview` | The open draft's staged changes. |
-| `evaluate` | Run a config version's placement/entitlement decisions locally for a user context. Use `--slot` with optional `--component-type`; deprecated `--surface-type` remains an alias. |
+| `evaluate` | Run a config version's placement/entitlement decisions locally for a user context. Use `--slot` with optional `--component-type`; deprecated `--surface-type` remains an alias. The ctx file carries the whole decision context — `plan_handle`, `traits`, `usage`, `trial` (or `trial_instances` + `now_iso`) — and `--usage` / `--trial-status` / `--now` override those keys, so usage-threshold and trial placements decide here exactly as they do in an app. Output reports `payload_ids`: which authored payload the resolver chose per placement, plus the SDK's `personalization_tokens`. |
 | `generate types` | Generate a TypeScript module of typed Playbook handles from any config version — `Entitlements` (namespaced by type, with the `EntitlementHandle` union for type-safe `can()`/`gate()`/`checkEntitlement()` call sites), plus `Plans`, `Segments`, `SurfaceTemplates`, and `UiPathActionTypes`. Const objects + literal-union types (erasable — no enums). `--out <path>` writes the file; the generated header records the exact command to regenerate it. `--json` for the raw handle map. |
 | `analytics catalog\|templates\|views\|view\|create\|preview\|query` | Work with the hosted Semantic Catalog and canonical analytics-view documents. Create and preview pass the document through unchanged to the same server contract used by the web editor and MCP tools; preview remains subject to the server's query limits. |
 | `ingest-keys create` (alias `mint`) | Mint a tenant-bound public ingest token for browser SDK use. Requires one or more `--origin` values; optional `--ip` restrictions. The full token is returned once. `ingest-keys list` shows ids/previews and `ingest-keys revoke <id>` invalidates one. |

package/dist/cli.js

@@ -2353,6 +2353,7 @@ var CtaActionTypeSchema = z2.enum([
   "snooze",
   "custom"
 ]).meta({ id: "CtaActionType", "x-revturbine-schema-persistence": Transient, "x-revturbine-schema-exposure": External });
+var ObjectiveField = HandleField.optional();
 var SchemaContext = {
   Playbook: "playbook",
   Branding: "branding",
@@ -2998,6 +2999,12 @@ var EntitlementRuleSchema = IdField.merge(TimestampFields).merge(TenantIdField).
   // "match all users" (replaces the legacy 'all' sentinel).
   segment_ids: z6.array(z6.string()).default([]).meta(Unrestricted3),
   visibility: RuleVisibilitySchema.default("public").meta(Unrestricted3),
+  // Business objective this rule monetizes for — the analytics `objective`
+  // slice, which resolves `rule_handle → objective` through a configuration
+  // snapshot (BL-0065 / worksheet G4). Config-only, and deliberately NOT part
+  // of the minted identity below: an objective relabel is a behaviour-only
+  // edit that coalesces onto the same rule, not a new rule scope.
+  objective: ObjectiveField.meta(Unrestricted3),
   // Usage-Limit "measured over" window, rule-level (plan #55). Rate Limit
   // keeps its entitlement-level `period_scope`; this is the per-rule one.
   period_scope: UsagePeriodScopeSchema.optional().meta(Unrestricted3),
@@ -3351,6 +3358,13 @@ var PlacementSchema = IdField.merge(TimestampFields).merge(TenantIdField).merge(
   handle: HandleField.meta(Unrestricted4),
   description: DescriptionField.meta(Unrestricted4),
   category: PlacementCategorySchema.meta(Unrestricted4),
+  // Business objective this placement monetizes for — the analytics
+  // `objective` slice, which resolves `placement_id → objective` through a
+  // configuration snapshot (BL-0065 / worksheet G4). Config-only: nothing in
+  // the runtime decision reads it, so it is absent from the portable
+  // RevTurbineConfig projection and the compiled payload. Free handle; see
+  // `ObjectiveField` for why the value set is not enumerated here.
+  objective: ObjectiveField.meta(Unrestricted4),
   drag_order_in_category: z7.number().int().default(0).meta(Unrestricted4),
   // Trigger config (populated based on category)
   surface_slot_id: z7.string().optional().meta(Unrestricted4),
@@ -5526,7 +5540,29 @@ var placementLifecycleBase = {
   surface_slot_id: nstr(),
   payload_id: nstr(),
   decision_id: nstr(),
-  decision_source: nstr()
+  decision_source: nstr(),
+  /**
+   * The `unique_handle` of the entitlement rule / placement rule whose verdict
+   * this event records; `null` when no rule matched (BL-0062, worksheet gap
+   * G3). On the placement lane this is the winning placement entry's handle —
+   * `PlacementOutput.rule_id`, already selected by the local resolver and
+   * discarded at emit until now.
+   *
+   * Optional AND nullable, unlike the required-but-nullable siblings around
+   * it. Every SDK already in the field emits these payloads without the key,
+   * and `quarantineVerdict` (revturbine-web `src/lib/events/ingest-validation.ts`)
+   * holds platform event names to this contract at the ingest boundary — a
+   * required field would quarantine live telemetry from every deployed SDK.
+   * So: absent = a pre-BL-0062 producer, `null` = no rule matched, string =
+   * the winning rule.
+   *
+   * Why it rides the whole lifecycle base rather than `placement_resolved`
+   * alone: attribution reads the exposure and outcome facts and stamps the
+   * winning touch's keys onto the movement — "through it rule `usage_70pct`"
+   * in the metric-primitives worked example (§3), anchored `touch_time` per
+   * its R8. An exposure without the rule key cannot carry that.
+   */
+  rule_handle: onstr()
 };
 var PlacementLifecyclePayload = z18.looseObject({ ...placementLifecycleBase });
 var PlacementExposedPayload = z18.looseObject({
@@ -5551,7 +5587,29 @@ var PlacementInteractionPayload = z18.looseObject({
   // explicit null when the caller supplied no timestamp (plan 228 TASK-4 —
   // the typed emit surface surfaced the mismatch; the wire is the truth).
   interaction_at: onstr(),
-  remind_after_seconds: z18.number().optional().meta(Unrestricted15)
+  remind_after_seconds: z18.number().optional().meta(Unrestricted15),
+  /**
+   * The `unique_handle` of the placement rule whose treatment the user acted
+   * on — `PlacementOutput.rule_id`, the same value the lifecycle lane stamps
+   * (BL-0182, follow-up to BL-0062 / #389).
+   *
+   * `placement_interaction` does not share `placementLifecycleBase` — its
+   * placement keys are all optional, because a bare `trackInteraction` caller
+   * may supply none of them — so #389's single edit to that base reached the
+   * four lifecycle, five slot and three gate events and left the interaction
+   * lane without a rule key. The effect was a funnel sliceable by rule at
+   * exposure and at outcome but NOT at the click in between, which is the
+   * step the CTR and click-through primitives are computed over.
+   *
+   * Same contract as #389 and for the same reason: optional AND nullable.
+   * revturbine-web's `quarantineVerdict`
+   * (`src/lib/events/ingest-validation.ts`) holds platform event names to
+   * these contracts at the ingest boundary, so a required field would
+   * quarantine live interaction telemetry from every SDK already deployed.
+   * Absent = a pre-BL-0182 producer or an interaction with no decision in
+   * scope, `null` = no rule matched, string = the winning rule.
+   */
+  rule_handle: onstr()
 });
 var GateEvaluatedPayloadSchema = z18.looseObject({
   entitlement_handle: str(),
@@ -5560,13 +5618,38 @@ var GateEvaluatedPayloadSchema = z18.looseObject({
   reason: nstr(),
   limit: nnum(),
   used: nnum(),
-  remaining: nnum()
+  remaining: nnum(),
+  /**
+   * The `unique_handle` of the entitlement rule whose verdict this event
+   * records; `null` when no rule matched (BL-0062, worksheet gap G3).
+   *
+   * This is the rule the §2.6.5 most-permissive selection picked — the one
+   * whose `limit` / `enabled` / `allowance_value` produced the `outcome`
+   * beside it. Without it the event says WHAT was decided and never WHICH
+   * configured rule decided it, which is the rule slice, and the
+   * `rule_handle → objective` hop the objective slice needs (BL-0065).
+   *
+   * Optional as well as nullable — see `placementLifecycleBase.rule_handle`
+   * for why a required field would quarantine every deployed SDK's gate
+   * telemetry at the ingest boundary.
+   */
+  rule_handle: onstr()
 }).meta(meta4("GateEvaluatedPayload"));
 var GateAttemptedPayload = z18.looseObject({ entitlement_handle: str() });
-var GateAllowedPayload = z18.looseObject({ entitlement_handle: str() });
+var GateAllowedPayload = z18.looseObject({
+  entitlement_handle: str(),
+  /** The rule that granted. See `GateEvaluatedPayloadSchema.rule_handle`. */
+  rule_handle: onstr()
+});
 var GateDeniedPayload = z18.looseObject({
   entitlement_handle: str(),
-  reason: onstr()
+  reason: onstr(),
+  /**
+   * The rule that denied — `null` on the two identity-shaped denials
+   * (`no_plan_identity`, `no_matching_entitlement_rule`), where no rule
+   * matched at all. See `GateEvaluatedPayloadSchema.rule_handle`.
+   */
+  rule_handle: onstr()
 });
 var slotContextBase = {
   surface_slot_id: nstr(),
@@ -5577,7 +5660,18 @@ var slotContextBase = {
   category: nstr(),
   decision_source: nstr(),
   reason_codes: z18.array(z18.string()).meta(Unrestricted15),
-  decision_id: nstr()
+  decision_id: nstr(),
+  /**
+   * The placement rule that won this slot — `PlacementOutput.rule_id`, in
+   * scope in `slotContext()` and dropped there until now (BL-0062, gap G3).
+   *
+   * Slot events are a verdict lane, not merely a render log: `slot_filled`
+   * says a rule won, `slot_suppressed` / `slot_empty` say none did. Carrying
+   * the handle is what lets "which rule keeps losing its slot" be asked at
+   * all — `reason_codes` beside it names WHY, never WHOSE. `null` on the
+   * terminal-empty events, absent on a pre-BL-0062 producer.
+   */
+  rule_handle: onstr()
 };
 var SlotLifecyclePayload = z18.looseObject({ ...slotContextBase });
 var SlotErrorPayload = z18.looseObject({
@@ -6473,6 +6567,30 @@ var TreatmentInteractionInputSchema = z24.object({
   message_block_id: z24.string().min(1).optional().meta(Unrestricted20),
   experiment_id: z24.string().min(1).optional().meta(Unrestricted20),
   variant_key: z24.string().min(1).optional().meta(Unrestricted20),
+  /**
+   * The `unique_handle` of the rule whose treatment was presented (BL-0200).
+   *
+   * #391 put `rule_handle` on the clickstream `placement_interaction` EVENT
+   * and deliberately kept it off this wire, so the BASE
+   * `placement_exposure_attribution` row this contract writes had no rule and
+   * `treatment-interaction-rows.ts` hard-coded `rule_handle: null`. Only an
+   * exposure that an attributed conversion later enriched carried one, which
+   * is why the attribution plane's rule cut could serve conversion-grain
+   * metrics and had to refuse presentation-grain ones BY NAME: computed over
+   * the attributed subset, `presented_accounts` would report the accounts
+   * that converted and `conversion.rate` ~100%.
+   *
+   * Carrying it here makes the rule a property of the EXPOSURE, known at
+   * presentation time by the only party that holds the resolved
+   * `PlacementOutput`, so those cuts become honestly servable.
+   *
+   * Optional AND nullable, the same contract #389/#391 chose and for the same
+   * reason: a required field would reject every already-deployed SDK's
+   * interactions at the ingest boundary. Absent = a pre-BL-0200 producer or
+   * an interaction with no decision in scope, `null` = no rule matched, a
+   * string = the winning rule.
+   */
+  rule_handle: z24.string().min(1).nullable().optional().meta(Unrestricted20),
   /**
    * Caller-declared test traffic (plan 164) — mirrors `TrackEvent.test` so
    * the presentation/interaction feed (the dashboard denominators) carries
@@ -9925,6 +10043,14 @@ var EntitlementCheckResultSchema = z34.object({
   used: z34.number().optional().meta(Unrestricted28),
   /** `max(0, limit - used)`. */
   remaining: z34.number().optional().meta(Unrestricted28),
+  /**
+   * The `unique_handle` of the entitlement rule this verdict came from —
+   * the winner of the §2.6.5 most-permissive selection (BL-0062, gap G3).
+   * Absent when no rule produced the verdict (unknown handle, no plan
+   * identity, default policy). This is the value an SDK stamps as the
+   * gate event's `rule_handle`, grounding the analytics rule slice.
+   */
+  rule_handle: z34.string().optional().meta(Unrestricted28),
   /** Upsell placement to render when entitlement is denied. */
   placement: PlacementDecisionOutputSchema.optional().meta(Unrestricted28)
 }).meta({ id: "EntitlementCheckResult", "x-revturbine-schema-persistence": Transient27, "x-revturbine-schema-exposure": External13 });
@@ -10799,11 +10925,72 @@ var CATALOG = {
   // both means every user on every plan — legal and occasionally intended,
   // but indistinguishable from an unfinished rule after authoring. Reverse
   // trial rules can't hit this (premium_plan_id is required).
+  // ── Dangling handle references (BL-0124) ─────────────────────────────────
+  // Four references nothing checked: each fails silently at runtime (the
+  // trigger never arms, the trial grants nothing, the rule targets nobody, the
+  // chip lowers to a literal no user carries), so a Playbook with a typo
+  // validated clean and shipped dead config. `error_launch` per spec §2 — "a
+  // reference whose target is created in a later step" is legitimate mid-draft
+  // and must never reach launch.
+  "VAL-PLC-08": {
+    id: "VAL-PLC-08",
+    severity: "error_launch",
+    message: "This placement triggers on an entitlement that does not exist.",
+    specRef: "config-validation.md \xA75.2 (BL-0124)"
+  },
+  "VAL-PLC-09": {
+    id: "VAL-PLC-09",
+    severity: "error_launch",
+    message: "This payload targets a segment chip that matches no segment or plan.",
+    specRef: "config-validation.md \xA75.2 (BL-0124)"
+  },
+  "VAL-PLN-08": {
+    id: "VAL-PLN-08",
+    severity: "error_launch",
+    message: "This entitlement rule targets a plan, add-on, or variation that does not exist.",
+    specRef: "config-validation.md \xA75.3 (BL-0124)"
+  },
+  "VAL-TRL-05": {
+    id: "VAL-TRL-05",
+    severity: "error_launch",
+    message: "This trial rule references a plan that does not exist.",
+    specRef: "config-validation.md \xA75.5 (BL-0124)"
+  },
   "VAL-TRL-04": {
     id: "VAL-TRL-04",
     severity: "warning",
     message: "Trial rule '{rule}' targets every user on every plan (no plan, no segment). Confirm the widest possible audience is intended.",
     specRef: "config-validation.md \xA75.8 (promoted \u2014 plan 174 TASK-7)"
+  },
+  // entitlement rule → entitlement (BL-0164): same dangling-reference family as
+  // the four above, just the one reference §5.9's original sweep missed.
+  "VAL-ENT-01": {
+    id: "VAL-ENT-01",
+    severity: "error_launch",
+    message: "This entitlement rule links an entitlement that does not exist.",
+    specRef: "config-validation.md \xA75.3 (BL-0164)"
+  },
+  // BL-0168: VAL-PLC-07's `plansKnown` precondition (every plan row carries a
+  // non-empty `unique_handle`) fails silently for a DB-shape plan row that
+  // spells the identifier `handle` — the whole check goes dark for the
+  // Playbook with nothing recording that it did not run. `warning`, never
+  // blocking: it is a meta-finding about check coverage, not a config defect.
+  "VAL-PLC-07-SKIPPED": {
+    id: "VAL-PLC-07-SKIPPED",
+    severity: "warning",
+    message: "VAL-PLC-07 ('targets no configured plan') could not run: the plan catalog carries a row with no usable unique_handle.",
+    specRef: "config-validation.md \xA75.2 (BL-0168)"
+  },
+  // BL-0168: the payload→placement parent lookup (`placementPayloads`) matches
+  // a standalone `placement_payloads` row on `row.id === payload.placement_id`
+  // only. A miss leaves `category` undefined, `categoryBucket` falls through to
+  // 99, and VAL-PLC-06's Access-Gate/Fixed cap check silently never runs for
+  // that payload. `warning`, never blocking, same rationale as above.
+  "VAL-PLC-06-SKIPPED": {
+    id: "VAL-PLC-06-SKIPPED",
+    severity: "warning",
+    message: "VAL-PLC-06 (ignored cap/cooldown settings) could not run: this payload's placement_id matches no configured placement.",
+    specRef: "config-validation.md \xA75.2 (BL-0168)"
   }
 };
 function getCatalogEntry(id) {
@@ -10832,28 +11019,285 @@ function runSemanticRules(graph, opts = {}) {
     ...checkPlacementAuthoring(graph),
     ...checkTrialRuleWidestAudience(graph),
     ...checkSegmentExperimentRefs(graph),
-    ...checkExperimentMetricRefs(graph, opts.knownMetricIds)
+    ...checkExperimentMetricRefs(graph, opts.knownMetricIds),
+    ...checkDanglingReferences(graph)
+  ];
+}
+function referenceNamespace(graph, table2, handleField) {
+  const rows = graph[table2];
+  if (!rows) return void 0;
+  const known = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    const handle = row[handleField];
+    if (typeof handle !== "string" || !handle) return void 0;
+    known.add(handle);
+  }
+  return known;
+}
+function knownHandlesHint(known, label) {
+  if (known.size === 0) return "";
+  const sorted = [...known].sort();
+  const shown = sorted.slice(0, 8);
+  const rest = sorted.length > shown.length ? `, \u2026 (${sorted.length} total)` : "";
+  return ` Declared ${label}: ${shown.map((h) => `'${h}'`).join(", ")}${rest}.`;
+}
+function firstStringField(row, fields) {
+  for (const field of fields) {
+    const value = row[field];
+    if (typeof value === "string" && value.length > 0) return { field, value };
+  }
+  return void 0;
+}
+function checkDanglingReferences(graph) {
+  return [
+    ...checkTriggerEntitlementRefs(graph),
+    ...checkTrialPlanRefs(graph),
+    ...checkEntitlementRuleTargetRefs(graph),
+    ...checkEntitlementRuleEntitlementRefs(graph),
+    ...checkPayloadSegmentChipRefs(graph)
   ];
 }
+function checkTriggerEntitlementRefs(graph) {
+  const known = referenceNamespace(graph, "entitlements", "unique_handle");
+  if (!known) return [];
+  const findings = [];
+  for (const [index, placement] of (graph.placements ?? []).entries()) {
+    if (!isRecord2(placement.trigger)) continue;
+    const ref = firstStringField(placement.trigger, ["entitlement_handle", "entitlement_id"]);
+    if (!ref || known.has(ref.value)) continue;
+    const id = String(placement.handle ?? placement.id ?? "");
+    findings.push(
+      finding(
+        "VAL-PLC-08",
+        {
+          object_type: "placement",
+          object_id: id,
+          field: `trigger.${ref.field}`,
+          path: ["placements", index, "trigger", ref.field],
+          studio: "placements"
+        },
+        {
+          message: `Placement '${id}' triggers on entitlement '${ref.value}', which no entitlement declares.`,
+          detail: "A trigger's entitlement reference must be an entitlement's unique_handle, not its config id. A reference that matches nothing never arms the trigger, so the placement looks configured and can never show." + knownHandlesHint(known, "entitlement handles")
+        }
+      )
+    );
+  }
+  return findings;
+}
+var TRIAL_PLAN_FIELDS = ["plan_id", "convert_to_plan_id", "fallback_plan_id", "premium_plan_id"];
+function checkTrialPlanRefs(graph) {
+  const known = referenceNamespace(graph, "plans", "unique_handle");
+  if (!known) return [];
+  const findings = [];
+  for (const table2 of ["free_trial_rules", "reverse_trial_rules"]) {
+    const objectType = table2 === "free_trial_rules" ? "free_trial_rule" : "reverse_trial_rule";
+    for (const [index, rule] of (graph[table2] ?? []).entries()) {
+      const id = String(rule.handle ?? rule.id ?? "");
+      for (const field of TRIAL_PLAN_FIELDS) {
+        const value = rule[field];
+        if (typeof value !== "string" || value.length === 0 || known.has(value)) continue;
+        findings.push(
+          finding(
+            "VAL-TRL-05",
+            {
+              object_type: objectType,
+              object_id: id,
+              field,
+              path: [table2, index, field],
+              studio: "trials"
+            },
+            {
+              message: `Trial rule '${id || "unnamed"}' references plan '${value}' in ${field}, which no plan declares.`,
+              detail: "Trial plan references must be a plan's unique_handle, not its config id. A reference that matches nothing makes the rule grant or convert nothing, and the trial silently never runs." + knownHandlesHint(known, "plan handles")
+            }
+          )
+        );
+      }
+    }
+  }
+  return findings;
+}
+var TARGET_KIND_TABLES = {
+  plan: { table: "plans", handleField: "unique_handle", label: "plan" },
+  addon: { table: "addons", handleField: "unique_handle", label: "add-on" },
+  plan_variation: { table: "plan_variations", handleField: "handle", label: "plan variation" },
+  addon_variation: { table: "addon_variations", handleField: "handle", label: "add-on variation" }
+};
+function checkEntitlementRuleTargetRefs(graph) {
+  const namespaces = /* @__PURE__ */ new Map();
+  const namespaceFor = (kind) => {
+    const spec = TARGET_KIND_TABLES[kind];
+    if (!spec) return void 0;
+    if (!namespaces.has(kind)) namespaces.set(kind, referenceNamespace(graph, spec.table, spec.handleField));
+    return namespaces.get(kind);
+  };
+  const findings = [];
+  for (const [index, rule] of (graph.entitlement_rules ?? []).entries()) {
+    const id = String(rule.handle ?? rule.id ?? "");
+    const refs = [];
+    if (Array.isArray(rule.targets)) {
+      for (const [targetIndex, target] of rule.targets.entries()) {
+        if (!isRecord2(target) || typeof target.id !== "string" || target.id.length === 0) continue;
+        const kind = typeof target.kind === "string" ? target.kind : "plan";
+        refs.push({
+          kind,
+          value: target.id,
+          field: `targets.${targetIndex}.id`,
+          path: ["entitlement_rules", index, "targets", targetIndex, "id"]
+        });
+      }
+    } else if (Array.isArray(rule.plan_ids)) {
+      for (const [planIndex, planRef] of rule.plan_ids.entries()) {
+        if (typeof planRef !== "string" || planRef.length === 0) continue;
+        refs.push({
+          kind: "plan",
+          value: planRef,
+          field: `plan_ids.${planIndex}`,
+          path: ["entitlement_rules", index, "plan_ids", planIndex]
+        });
+      }
+    } else if (typeof rule.plan_id === "string" && rule.plan_id.length > 0) {
+      refs.push({
+        kind: "plan",
+        value: rule.plan_id,
+        field: "plan_id",
+        path: ["entitlement_rules", index, "plan_id"]
+      });
+    }
+    for (const ref of refs) {
+      const known = namespaceFor(ref.kind);
+      if (!known || known.has(ref.value)) continue;
+      const label = TARGET_KIND_TABLES[ref.kind]?.label ?? ref.kind;
+      findings.push(
+        finding(
+          "VAL-PLN-08",
+          {
+            object_type: "entitlement_rule",
+            object_id: id,
+            field: ref.field,
+            path: ref.path,
+            studio: "plans-entitlements"
+          },
+          {
+            message: `Entitlement rule '${id || "unnamed"}' targets ${label} '${ref.value}', which no ${label} declares.`,
+            detail: "Rule targets must be the target's unique_handle, not its config id. A target that matches nothing makes the rule apply to no one, so the entitlement it grants is silently absent for every user." + knownHandlesHint(known, `${label} handles`)
+          }
+        )
+      );
+    }
+  }
+  return findings;
+}
+function checkEntitlementRuleEntitlementRefs(graph) {
+  const known = referenceNamespace(graph, "entitlements", "unique_handle");
+  if (!known) return [];
+  const findings = [];
+  for (const [index, rule] of (graph.entitlement_rules ?? []).entries()) {
+    const value = rule.entitlement_id;
+    if (typeof value !== "string" || value.length === 0 || known.has(value)) continue;
+    const id = String(rule.handle ?? rule.id ?? "");
+    findings.push(
+      finding(
+        "VAL-ENT-01",
+        {
+          object_type: "entitlement_rule",
+          object_id: id,
+          field: "entitlement_id",
+          path: ["entitlement_rules", index, "entitlement_id"],
+          studio: "plans-entitlements"
+        },
+        {
+          message: `Entitlement rule '${id || "unnamed"}' links entitlement '${value}', which no entitlement declares.`,
+          detail: "A rule's entitlement reference must be an entitlement's unique_handle, not its config id. A reference that matches nothing means the entitlement it grants or limits is silently absent for every user." + knownHandlesHint(known, "entitlement handles")
+        }
+      )
+    );
+  }
+  return findings;
+}
+function payloadSegmentChips(payload, path3) {
+  const target = isRecord2(payload.target) ? payload.target : void 0;
+  if (target && Array.isArray(target.segment_chips)) {
+    return { fields: ["target", "segment_chips"], path: [...path3, "target", "segment_chips"], chips: target.segment_chips };
+  }
+  if (Array.isArray(payload.target_segment_chips)) {
+    return { fields: ["target_segment_chips"], path: [...path3, "target_segment_chips"], chips: payload.target_segment_chips };
+  }
+  return void 0;
+}
+function checkPayloadSegmentChipRefs(graph) {
+  const segments = referenceNamespace(graph, "segments", "handle");
+  const plans = referenceNamespace(graph, "plans", "unique_handle");
+  if (!segments || !plans) return [];
+  const findings = [];
+  for (const { payload, path: path3 } of placementPayloads(graph)) {
+    const chips = payloadSegmentChips(payload, path3);
+    if (!chips) continue;
+    const id = String(payload.payload_id ?? payload.id ?? "");
+    for (const [chipIndex, raw] of chips.chips.entries()) {
+      if (typeof raw !== "string") continue;
+      const value = raw.trim();
+      if (!value || segments.has(value) || plans.has(value)) continue;
+      findings.push(
+        finding(
+          "VAL-PLC-09",
+          {
+            object_type: "placement_payload",
+            object_id: id,
+            field: `${chips.fields.join(".")}.${chipIndex}`,
+            path: [...chips.path, chipIndex],
+            studio: "placements"
+          },
+          {
+            message: `Payload '${id}' targets segment chip '${value}', which matches no segment or plan.`,
+            detail: "A chip resolves against segment handles first, then plan handles \u2014 never a config id or a display name. An unresolved chip compiles to a literal no user carries, so the payload can never be shown." + knownHandlesHint(segments, "segment handles")
+          }
+        )
+      );
+    }
+  }
+  return findings;
+}
 function* placementPayloads(graph) {
   const placements = graph.placements ?? [];
   for (const [index, placement] of placements.entries()) {
     if (!Array.isArray(placement.payloads)) continue;
     for (const [payloadIndex, payload] of placement.payloads.entries()) {
-      if (isRecord2(payload)) yield { payload, category: placement.category, path: ["placements", index, "payloads", payloadIndex] };
+      if (isRecord2(payload)) yield { payload, category: placement.category, path: ["placements", index, "payloads", payloadIndex], parentFound: true };
     }
   }
   for (const [index, payload] of (graph.placement_payloads ?? []).entries()) {
     const placement = placements.find((row) => typeof row.id === "string" && row.id === payload.placement_id);
-    yield { payload, category: placement?.category, path: ["placement_payloads", index] };
+    yield { payload, category: placement?.category, path: ["placement_payloads", index], parentFound: placement !== void 0 };
   }
 }
 function checkPlacementAuthoring(graph) {
   const findings = [];
-  const plansKnown = Array.isArray(graph.plans) && graph.plans.every((plan) => typeof plan.unique_handle === "string" && plan.unique_handle.length > 0);
-  const planHandles = new Set((graph.plans ?? []).map((plan) => plan.unique_handle));
-  for (const { payload, category, path: path3 } of placementPayloads(graph)) {
+  const plans = graph.plans;
+  const plansKnown = Array.isArray(plans) && plans.every((plan) => typeof plan.unique_handle === "string" && plan.unique_handle.length > 0);
+  const planHandles = new Set((plans ?? []).map((plan) => plan.unique_handle));
+  if (Array.isArray(plans) && plans.length > 0 && !plansKnown) {
+    findings.push(finding("VAL-PLC-07-SKIPPED", {
+      object_type: "plan",
+      studio: "placements"
+    }, {
+      detail: "Every plan row needs a non-empty unique_handle for VAL-PLC-07 to run against this Playbook. A DB-shape row that spells the identifier `handle` does not satisfy it."
+    }));
+  }
+  for (const { payload, category, path: path3, parentFound } of placementPayloads(graph)) {
     const id = String(payload.payload_id ?? payload.id ?? "");
+    if (!parentFound) {
+      findings.push(finding("VAL-PLC-06-SKIPPED", {
+        object_type: "placement_payload",
+        object_id: id,
+        field: "placement_id",
+        studio: "placements"
+      }, {
+        message: `Payload '${id}' names a placement_id that matches no configured placement, so VAL-PLC-06's cap/cooldown check could not run for it.`,
+        detail: "Fix placement_id (or add the placement it should reference) to restore the cap check for Access Gate and Fixed placements."
+      }));
+    }
     const bucket = typeof category === "string" ? categoryBucket(category) : 99;
     if (bucket === 0 || bucket === 1) {
       const caps = isRecord2(payload.caps) ? payload.caps : {};
@@ -11506,6 +11950,7 @@ var CtaActionTypeSchema2 = z39.enum([
   "snooze",
   "custom"
 ]).meta({ id: "CtaActionType", "x-revturbine-schema-persistence": Transient30, "x-revturbine-schema-exposure": External14 });
+var ObjectiveField2 = HandleField2.optional();
 var IdentityKind2 = {
   /** Author-given, human-meaningful handle (plans, entitlements, segments, …). */
   Named: "named",
@@ -11711,6 +12156,12 @@ var EntitlementRuleSchema2 = IdField2.merge(TimestampFields2).merge(TenantIdFiel
   // "match all users" (replaces the legacy 'all' sentinel).
   segment_ids: z62.array(z62.string()).default([]).meta(Unrestricted210),
   visibility: RuleVisibilitySchema2.default("public").meta(Unrestricted210),
+  // Business objective this rule monetizes for — the analytics `objective`
+  // slice, which resolves `rule_handle → objective` through a configuration
+  // snapshot (BL-0065 / worksheet G4). Config-only, and deliberately NOT part
+  // of the minted identity below: an objective relabel is a behaviour-only
+  // edit that coalesces onto the same rule, not a new rule scope.
+  objective: ObjectiveField2.meta(Unrestricted210),
   // Usage-Limit "measured over" window, rule-level (plan #55). Rate Limit
   // keeps its entitlement-level `period_scope`; this is the per-rule one.
   period_scope: UsagePeriodScopeSchema2.optional().meta(Unrestricted210),
@@ -13934,7 +14385,7 @@ function repairDeprecatedFields(config, schema = PlaybookObjectSchema2) {
 }
 
 // src/schema/version.ts
-var SCHEMA_VERSION = "0.1.325";
+var SCHEMA_VERSION = "0.1.343";
 
 // src/lib/credentials.ts
 import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
@@ -14283,7 +14734,13 @@ function hasBlockingFindings(findings, force = false) {
 }
 function formatFindings(findings) {
   if (findings.length === 0) return "No validation findings.";
-  return findings.map((f) => `${isBlockingFinding(f) ? "\u2717" : "\u2022"} [${f.severity}] ${f.code}: ${f.message}`).join("\n");
+  return findings.map((f) => {
+    const blocking = isBlockingFinding(f);
+    const head = `${blocking ? "\u2717" : "\u2022"} [${f.severity}] ${f.code}: ${f.message}`;
+    const detail = f.detail?.trim();
+    return blocking && detail ? `${head}
+    ${detail}` : head;
+  }).join("\n");
 }
 async function fetchValidation(baseUrl, playbookVersionId, headers, fetchImpl = fetch) {
   const res = await fetchImpl(`${baseUrl}/api/config/validate`, {
@@ -14390,28 +14847,181 @@ function formatAuthentication(hasToken, tokenValid) {
   return "authentication: verification unavailable \u2014 credentials present; retry when the instance is reachable";
 }
 
+// src/lib/evaluate-context.ts
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var DEFAULT_USAGE_UNIT = "unit";
+function normalizeUsageEntry(handle, value, errors) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      errors.push(`usage.${handle} must be a finite number \u2265 0`);
+      return void 0;
+    }
+    return { entitlement_handle: handle, unit: DEFAULT_USAGE_UNIT, amount: value };
+  }
+  if (!isRecord4(value)) {
+    errors.push(`usage.${handle} must be a number or an object with "amount"`);
+    return void 0;
+  }
+  const amount = value.amount;
+  if (typeof amount !== "number" || !Number.isFinite(amount) || amount < 0) {
+    errors.push(`usage.${handle}.amount must be a finite number \u2265 0`);
+    return void 0;
+  }
+  const entry = {
+    entitlement_handle: typeof value.entitlement_handle === "string" ? value.entitlement_handle : handle,
+    unit: typeof value.unit === "string" && value.unit.length > 0 ? value.unit : DEFAULT_USAGE_UNIT,
+    amount
+  };
+  if (value.limit !== void 0) {
+    if (typeof value.limit !== "number" || !Number.isFinite(value.limit) || value.limit < 0) {
+      errors.push(`usage.${handle}.limit must be a finite number \u2265 0`);
+    } else {
+      entry.limit = value.limit;
+    }
+  }
+  if (value.reset_date !== void 0) {
+    if (typeof value.reset_date !== "string") {
+      errors.push(`usage.${handle}.reset_date must be a string`);
+    } else {
+      entry.reset_date = value.reset_date;
+    }
+  }
+  return entry;
+}
+function normalizeUsage(value, errors) {
+  if (value === void 0 || value === null) return void 0;
+  if (!isRecord4(value)) {
+    errors.push("usage must be an object keyed by entitlement handle");
+    return void 0;
+  }
+  const out = {};
+  for (const [handle, raw] of Object.entries(value)) {
+    const entry = normalizeUsageEntry(handle, raw, errors);
+    if (entry) out[handle] = entry;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function normalizeTrialStatus(value, errors) {
+  if (value === void 0 || value === null) return void 0;
+  if (!isRecord4(value)) {
+    errors.push("trial status must be an object (the SDK's UserTrialStatus)");
+    return void 0;
+  }
+  if (typeof value.in_trial !== "boolean") {
+    errors.push('trial status must carry a boolean "in_trial"');
+    return void 0;
+  }
+  return value;
+}
+function normalizeTrialInstances(value, errors) {
+  if (value === void 0 || value === null) return void 0;
+  if (!Array.isArray(value) || value.some((item) => !isRecord4(item))) {
+    errors.push("trial_instances must be an array of TrialInstance objects");
+    return void 0;
+  }
+  return value.length > 0 ? value : void 0;
+}
+function normalizeNowIso(value, source, errors) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "string" || Number.isNaN(Date.parse(value))) {
+    errors.push(`${source} must be an ISO-8601 timestamp (e.g. 2026-09-21T00:00:00Z)`);
+    return void 0;
+  }
+  return new Date(value).toISOString();
+}
+function parseJsonFlag(raw, flag, errors) {
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    errors.push(`${flag} must be valid JSON: ${err.message}`);
+    return void 0;
+  }
+}
+function parseDecisionContext(input) {
+  const errors = [];
+  const usageSource = input.usage !== void 0 ? parseJsonFlag(input.usage, "--usage", errors) : input.ctx.usage;
+  const usage = normalizeUsage(usageSource, errors);
+  const trialSource = input.trialStatus !== void 0 ? parseJsonFlag(input.trialStatus, "--trial-status", errors) : input.ctx.trial;
+  const trialStatus = normalizeTrialStatus(trialSource, errors);
+  const trialInstances = normalizeTrialInstances(input.ctx.trial_instances, errors);
+  const nowIso = input.now !== void 0 ? normalizeNowIso(input.now, "--now", errors) : normalizeNowIso(input.ctx.now_iso, "now_iso", errors);
+  if (errors.length > 0) return { ok: false, errors };
+  return {
+    ok: true,
+    context: {
+      ...usage ? { usage } : {},
+      ...trialStatus ? { trialStatus } : {},
+      ...trialInstances ? { trialInstances } : {},
+      ...nowIso ? { nowIso } : {}
+    }
+  };
+}
+
 // src/lib/evaluate-local.ts
 import { initRevTurbine } from "@revturbine/sdk/headless";
 function resolvePlacementComponentType(input) {
   return input.componentType ?? input.surfaceType;
 }
+function payloadIdOf(decision) {
+  if (typeof decision !== "object" || decision === null) return null;
+  const output = decision.output;
+  if (typeof output !== "object" || output === null) return null;
+  const id = output.output_id;
+  return typeof id === "string" ? id : null;
+}
+async function completeUsageLimits(session, usage) {
+  let completed = false;
+  const filled = {};
+  for (const [handle, entry] of Object.entries(usage)) {
+    if (entry.limit !== void 0) {
+      filled[handle] = entry;
+      continue;
+    }
+    const result = await session.checkEntitlement(entry.entitlement_handle);
+    if (typeof result?.limit === "number" && Number.isFinite(result.limit)) {
+      filled[handle] = { ...entry, limit: result.limit };
+      completed = true;
+    } else {
+      filled[handle] = entry;
+    }
+  }
+  if (completed) session.setUserContext({ usage: filled });
+}
 async function evaluateLocal(config, input) {
   const user = { id: input.userId };
   if (input.planHandle) user.plan_handle = input.planHandle;
   if (input.traits && Object.keys(input.traits).length > 0) user.custom = input.traits;
+  if (input.usage) user.usage = input.usage;
   const session = await initRevTurbine({
     user,
-    localRuntime: { playbook: config }
+    localRuntime: {
+      playbook: config,
+      ...input.trialStatus ? { initialData: { trialStatus: input.trialStatus } } : {}
+    }
   });
+  if (input.trialInstances) {
+    await session.sdk.setTrialInstances(
+      input.trialInstances,
+      input.nowIso ? { nowIso: input.nowIso } : void 0
+    );
+  }
+  const trialAsked = Boolean(input.trialInstances || input.trialStatus);
+  const trialStatus = trialAsked ? await session.getTrialStatus() : void 0;
+  if (input.usage) await completeUsageLimits(session, input.usage);
   const entitlements = {};
   for (const handle of input.entitlementHandles ?? []) {
     entitlements[handle] = await session.checkEntitlement(handle);
   }
   const decisions = [];
+  const payloadIds = {};
   for (const placementId of input.placementIds ?? []) {
     const controller = session.placement({ placement: { name: placementId } });
     await controller.load();
-    decisions.push(controller.state.decision);
+    const decision = controller.state.decision;
+    decisions.push(decision);
+    payloadIds[placementId] = payloadIdOf(decision);
   }
   const componentType = input.slot ? resolvePlacementComponentType(input.slot) : void 0;
   const placement = input.slot && (input.slot.slotId || componentType) ? await session.getPlacement({
@@ -14419,7 +15029,14 @@ async function evaluateLocal(config, input) {
     ...componentType ? { componentType } : {},
     ...input.planHandle ? { planHandle: input.planHandle } : {}
   }) : null;
-  return { decisions, entitlements, placement };
+  return {
+    decisions,
+    payloadIds,
+    entitlements,
+    placement,
+    personalizationTokens: session.sdk.getPersonalizationTokens(),
+    ...trialStatus !== void 0 ? { trialStatus } : {}
+  };
 }
 
 // src/lib/ingest-keys.ts
@@ -14665,14 +15282,14 @@ function schemaForConfig(raw) {
 var repairDeprecatedFields2 = repairDeprecatedFields;
 var LEGACY_HEADER_ALIASES = /* @__PURE__ */ new Set(["version", "change_set_id"]);
 var UNKNOWN_FIELD_CODE = "cli/unknown-field";
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function unknownTopLevelKeys(raw) {
-  if (!isRecord4(raw)) return [];
+  if (!isRecord5(raw)) return [];
   const { schema } = schemaForConfig(raw);
   const parsed = schema.safeParse(raw);
-  if (!parsed.success || !isRecord4(parsed.data)) return [];
+  if (!parsed.success || !isRecord5(parsed.data)) return [];
   const recognized = new Set(Object.keys(parsed.data));
   return Object.keys(raw).filter((key2) => !recognized.has(key2) && !LEGACY_HEADER_ALIASES.has(key2));
 }
@@ -14916,17 +15533,17 @@ function finalOutputLines(params) {
 
 // src/lib/handles-codegen.ts
 var UNTYPED_GROUP = "untyped";
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function nonEmptyString(value) {
   return typeof value === "string" && value.length > 0 ? value : null;
 }
 function extractEntitlementHandles(config) {
-  if (!isRecord5(config) || !Array.isArray(config.entitlements)) return {};
+  if (!isRecord6(config) || !Array.isArray(config.entitlements)) return {};
   const groups = /* @__PURE__ */ new Map();
   for (const entry of config.entitlements) {
-    if (!isRecord5(entry)) continue;
+    if (!isRecord6(entry)) continue;
     const handle = nonEmptyString(entry.unique_handle) ?? nonEmptyString(entry.handle);
     if (!handle) continue;
     const type = nonEmptyString(entry.type) ?? UNTYPED_GROUP;
@@ -14996,36 +15613,36 @@ function collectStrings(values) {
   return [...out].sort();
 }
 function extractPlanHandles(config) {
-  if (!isRecord5(config) || !Array.isArray(config.plans)) return [];
+  if (!isRecord6(config) || !Array.isArray(config.plans)) return [];
   return collectStrings(
     config.plans.map(
-      (p) => isRecord5(p) ? nonEmptyString(p.unique_handle) ?? nonEmptyString(p.handle) ?? p.id : null
+      (p) => isRecord6(p) ? nonEmptyString(p.unique_handle) ?? nonEmptyString(p.handle) ?? p.id : null
     )
   );
 }
 function extractSegmentHandles(config) {
-  if (!isRecord5(config) || !Array.isArray(config.segments)) return [];
+  if (!isRecord6(config) || !Array.isArray(config.segments)) return [];
   return collectStrings(
-    config.segments.map((s) => isRecord5(s) ? nonEmptyString(s.handle) ?? s.id : null)
+    config.segments.map((s) => isRecord6(s) ? nonEmptyString(s.handle) ?? s.id : null)
   );
 }
 function extractSurfaceTemplateIds(config) {
-  if (!isRecord5(config)) return [];
+  if (!isRecord6(config)) return [];
   const ids = [];
   if (Array.isArray(config.surface_templates)) {
     for (const t of config.surface_templates) {
-      if (isRecord5(t)) ids.push(t.id ?? t.template_id);
+      if (isRecord6(t)) ids.push(t.id ?? t.template_id);
     }
   }
   const surfacesOf = (payload) => {
-    if (!isRecord5(payload) || !Array.isArray(payload.surfaces)) return;
+    if (!isRecord6(payload) || !Array.isArray(payload.surfaces)) return;
     for (const surface of payload.surfaces) {
-      if (isRecord5(surface)) ids.push(surface.template_id);
+      if (isRecord6(surface)) ids.push(surface.template_id);
     }
   };
   if (Array.isArray(config.placements)) {
     for (const placement of config.placements) {
-      if (!isRecord5(placement) || !Array.isArray(placement.payloads)) continue;
+      if (!isRecord6(placement) || !Array.isArray(placement.payloads)) continue;
       for (const payload of placement.payloads) surfacesOf(payload);
     }
   }
@@ -15035,9 +15652,9 @@ function extractSurfaceTemplateIds(config) {
   return collectStrings(ids);
 }
 function extractUiPathActionTypes(config) {
-  if (!isRecord5(config) || !Array.isArray(config.content_ui_paths)) return [];
+  if (!isRecord6(config) || !Array.isArray(config.content_ui_paths)) return [];
   return collectStrings(
-    config.content_ui_paths.map((p) => isRecord5(p) ? p.action_type : null)
+    config.content_ui_paths.map((p) => isRecord6(p) ? p.action_type : null)
   );
 }
 function renderFlatFamily(lines, opts) {
@@ -15139,19 +15756,19 @@ function fail(cls, message) {
 }
 
 // src/lib/pin-drift.ts
-function isRecord6(value) {
+function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function pinOf(pkg, name) {
   for (const field of ["devDependencies", "dependencies"]) {
     const deps = pkg[field];
-    if (isRecord6(deps) && typeof deps[name] === "string") return deps[name];
+    if (isRecord7(deps) && typeof deps[name] === "string") return deps[name];
   }
   return void 0;
 }
 var EXACT = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
 function checkPinDrift(pkg) {
-  if (!isRecord6(pkg)) return [];
+  if (!isRecord7(pkg)) return [];
   const warnings = [];
   const cliPin = pinOf(pkg, "@revturbine/cli");
   if (cliPin !== void 0 && !EXACT.test(cliPin)) {
@@ -16223,8 +16840,8 @@ program.command("preview").description("The open draft's Runtime Impact summary
   emit(data, Boolean(opts.json), text);
 });
 program.command("evaluate").description(
-  "Run placement/entitlement decisions for a user context against a config version \u2014 evaluated LOCALLY: the CLI fetches the version's Playbook and runs the SDK engine in-process (plan 192; clean-room, no suppression/cap history). Requires --live, --draft, or --release <id>."
-).option("--live", "Evaluate the live (deployed) configuration").option("--draft", "Evaluate the tenant's open draft").option("--release <id>", "Evaluate a past release (from its frozen snapshot)").option("--entitlement <handle>", "Check one entitlement (the checkEntitlement result)").option("--slot <id>", "Evaluate one surface slot (the getPlacement decision for that slot)").option("--component-type <type>", "Disambiguate a slot that can render more than one component, or resolve by component type alone").option("--surface-type <type>", "Deprecated alias for --component-type").option("--plan-handle <handle>", "Evaluate as if the user were on this plan (overrides the ctx file)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).requiredOption("--user <file>", "JSON file: { user_id, customer_id?, plan_handle?, traits?, now_iso? }").option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(
+  "Run placement/entitlement decisions for a user context against a config version \u2014 evaluated LOCALLY: the CLI fetches the version's Playbook and runs the SDK engine in-process (plan 192; clean-room, no suppression/cap history). The ctx file carries the full decision context \u2014 plan, traits, usage, trial state and a clock pin \u2014 so usage-threshold and trial placements decide here as they do in an app. Requires --live, --draft, or --release <id>."
+).option("--live", "Evaluate the live (deployed) configuration").option("--draft", "Evaluate the tenant's open draft").option("--release <id>", "Evaluate a past release (from its frozen snapshot)").option("--entitlement <handle>", "Check one entitlement (the checkEntitlement result)").option("--slot <id>", "Evaluate one surface slot (the getPlacement decision for that slot)").option("--component-type <type>", "Disambiguate a slot that can render more than one component, or resolve by component type alone").option("--surface-type <type>", "Deprecated alias for --component-type").option("--plan-handle <handle>", "Evaluate as if the user were on this plan (overrides the ctx file)").option("--usage <json>", `Usage entries keyed by entitlement handle, e.g. '{"api_calls":{"amount":95}}' (overrides the ctx file) \u2014 required to decide usage/credit-threshold placements`).option("--trial-status <json>", `Trial status, e.g. '{"in_trial":true,"trial_limit_type":"time","days_remaining":3}' (overrides the ctx file) \u2014 required to decide trial placements`).option("--now <iso>", "Pin the clock (ISO-8601) for trial derivation from the ctx file's trial_instances (overrides ctx now_iso)").option("-u, --url <url>", "RevTurbine instance URL", DEFAULT_URL).requiredOption("--user <file>", "JSON file: { user_id, plan_handle?, traits?, usage?, trial?, trial_instances?, now_iso? }").option("-t, --tenant-id <id>", "x-tenant-id (defaults to the stored token tenant)").action(
   async (opts) => {
     const [sel] = requireSelectors(opts, [], { count: 1, allowed: ["draft", "live", "release"], command: "evaluate" });
     const conn = connect(opts.url, opts.tenantId);
@@ -16242,8 +16859,18 @@ program.command("evaluate").description(
     }
     const userId = typeof ctx.user_id === "string" && ctx.user_id.length > 0 ? ctx.user_id : void 0;
     if (!userId) fail(EXIT.VALIDATION, `user file must carry a non-empty string "user_id" (${opts.user})`);
-    if (typeof ctx.now_iso === "string") {
-      diag("WARNING: now_iso is ignored \u2014 local evaluation uses the real clock.");
+    const parsed = parseDecisionContext({
+      ctx,
+      usage: opts.usage,
+      trialStatus: opts.trialStatus,
+      now: opts.now
+    });
+    if (!parsed.ok) fail(EXIT.VALIDATION, `invalid decision context in ${opts.user}: ${parsed.errors.join("; ")}`);
+    const decisionContext = parsed.context;
+    if (decisionContext.nowIso && !decisionContext.trialInstances) {
+      diag(
+        'NOTE: the pinned clock only moves trial derivation from trial_instances; an explicit "trial" status is already fixed in time.'
+      );
     }
     if (typeof ctx.customer_id === "string") {
       diag(
@@ -16262,6 +16889,7 @@ program.command("evaluate").description(
       userId,
       planHandle,
       traits,
+      ...decisionContext,
       entitlementHandles: opts.entitlement ? [opts.entitlement] : bulk ? asStringArray2(ctx.entitlement_handles) : [],
       placementIds: bulk ? asStringArray2(ctx.placement_ids) : [],
       slot: wantsSlot ? { slotId: opts.slot, componentType } : void 0
@@ -16271,10 +16899,18 @@ program.command("evaluate").description(
         tenant_id: conn.tenantId,
         user_id: userId,
         ...playbookVersionId ? { playbook_version_id: playbookVersionId } : {},
-        evaluated_at: (/* @__PURE__ */ new Date()).toISOString(),
+        // The pinned clock when one was given, so the stamp matches the
+        // instant the decisions were made against.
+        evaluated_at: decisionContext.nowIso ?? (/* @__PURE__ */ new Date()).toISOString(),
         // Provenance: decided in-process by the SDK engine, not by a server.
         evaluation: "local",
-        ...result
+        decisions: result.decisions,
+        // Which authored payload the resolver chose, per requested placement.
+        payload_ids: result.payloadIds,
+        entitlements: result.entitlements,
+        placement: result.placement,
+        personalization_tokens: result.personalizationTokens,
+        ...result.trialStatus !== void 0 ? { trial_status: result.trialStatus } : {}
       },
       true
     );
@@ -16546,10 +17182,23 @@ var COMMAND_EXAMPLES = {
   ].join("\n"),
   evaluate: [
     "",
-    "Example:",
+    "Examples:",
     "  revturbine evaluate --live --user ./ctx.json --entitlement seats",
     "  revturbine evaluate --draft --user ./ctx.json --slot upgrade_banner --component-type banner --plan-handle pro",
-    '    ctx.json: { "user_id": "u1", "plan_handle": "pro", "entitlement_handles": ["seats"] }'
+    `  revturbine evaluate --live --user ./ctx.json --usage '{"api_calls":{"amount":95}}'`,
+    `  revturbine evaluate --live --user ./ctx.json --trial-status '{"in_trial":true,"trial_limit_type":"time","days_remaining":3}'`,
+    "  revturbine evaluate --live --user ./ctx.json --now 2026-09-21T00:00:00Z",
+    "",
+    "ctx.json \u2014 the whole decision context:",
+    '    { "user_id": "u1", "plan_handle": "pro", "traits": { "tier": "smb" },',
+    '      "usage": { "api_calls": { "amount": 95, "limit": 100 } },',
+    '      "trial": { "in_trial": true, "trial_limit_type": "time", "days_remaining": 3 },',
+    '      "trial_instances": [ ... ], "now_iso": "2026-09-21T00:00:00Z",',
+    '      "entitlement_handles": ["seats"], "placement_ids": ["pl_usage_warn"] }',
+    "",
+    `  usage \u2014 omit "limit" and it is taken from the Playbook's entitlement rule.`,
+    "  trial \u2014 an explicit status; trial_instances + now_iso derive one at that clock.",
+    "  Output carries payload_ids: which authored payload won, per placement."
   ].join("\n")
 };
 for (const [name, text] of Object.entries(COMMAND_EXAMPLES)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/cli",
-  "version": "0.19.2",
+  "version": "0.19.4",
   "description": "revturbine — validate RevTurbine Playbooks and ship them to a RevTurbine instance through the playbook-version lifecycle (draft → Release).",
   "license": "MIT",
   "repository": {
@@ -30,7 +30,7 @@
     "verify": "npm run typecheck && npm run lint && npm run check:schema && npm run test"
   },
   "dependencies": {
-    "@revturbine/sdk": "^0.7.4",
+    "@revturbine/sdk": ">=0.10.9 <1",
     "commander": "^15.0.0",
     "semver": "^7.8.5",
     "zod": "4.4.3"