@revturbine/cli 0.19.3 → 0.19.4

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`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revturbine/cli",
-  "version": "0.19.3",
+  "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": {