@revturbine/cli 0.19.3 → 0.19.5

package/dist/cli.js

@@ -2353,6 +2353,8 @@ var CtaActionTypeSchema = z2.enum([
   "snooze",
   "custom"
 ]).meta({ id: "CtaActionType", "x-revturbine-schema-persistence": Transient, "x-revturbine-schema-exposure": External });
+var ObjectiveField = HandleField.optional();
+var NullableObjectiveField = z2.string().min(1).max(100).nullable().optional();
 var SchemaContext = {
   Playbook: "playbook",
   Branding: "branding",
@@ -2998,6 +3000,16 @@ 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). A reference by handle to an
+  // `objectives[]` entity (D-15; VAL-OBJ-01). 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.
+  // Nullable on the persisted entity so an editor can CLEAR the reference
+  // (a PATCH merges, so omission keeps the old value); the portable
+  // projection stays optional-only and omits it when unset.
+  objective: NullableObjectiveField.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 +3363,17 @@ 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). A reference by handle to
+  // an `objectives[]` entity (D-15; VAL-OBJ-01). Config-only: nothing in the
+  // runtime decision reads it, so it round-trips through the portable
+  // Playbook projection but never lowers into the compiled IR. See
+  // `ObjectiveField`.
+  // Nullable on the persisted entity so an editor can CLEAR the reference
+  // (a PATCH merges, so omission keeps the old value); the portable
+  // projection stays optional-only and omits it when unset.
+  objective: NullableObjectiveField.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),
@@ -3830,6 +3853,34 @@ var UserPlanContextSchema = z9.object({
 }).meta(
   { id: "UserPlanContext", "x-revturbine-schema-persistence": Transient6, "x-revturbine-schema-exposure": External5 }
 );
+var BuiltinActivityLevelSchema = z9.enum(["new", "high", "medium", "low", "inactive"]);
+var BuiltinSubscriptionStateSchema = z9.enum(["none", "trial", "paid", "cancelled"]);
+var BuiltinTrialTypeSchema = z9.enum(["none", "free_trial", "reverse_trial"]);
+var BuiltinBuyerRoleSchema = z9.enum(["buyer", "non_buyer"]);
+var BuiltinEmailTypeSchema = z9.enum(["business", "personal", "unknown"]);
+var BuiltinBillingHealthSchema = z9.enum([
+  "no_billing",
+  "good_standing",
+  "trial_payment_method_attached",
+  "payment_method_missing",
+  "payment_failed",
+  "payment_overdue",
+  "cancelled"
+]);
+var BuiltinRegionSchema = z9.enum(["us_canada", "europe", "rest_of_world"]);
+var BuiltinDeviceTypeSchema = z9.enum(["desktop", "mobile", "tablet", "unknown"]);
+var BuiltinSeatTypeSchema = z9.string().regex(/^[a-z0-9._]{1,87}$/);
+var UserBuiltinDimensionsSchema = z9.object({
+  activity_level: BuiltinActivityLevelSchema.optional().meta(Unrestricted6),
+  subscription_state: BuiltinSubscriptionStateSchema.optional().meta(Unrestricted6),
+  trial_type: BuiltinTrialTypeSchema.optional().meta(Unrestricted6),
+  seat_type: BuiltinSeatTypeSchema.optional().meta(Unrestricted6),
+  buyer_role: BuiltinBuyerRoleSchema.optional().meta(Unrestricted6),
+  email_type: BuiltinEmailTypeSchema.optional().meta(Unrestricted6),
+  billing_health: BuiltinBillingHealthSchema.optional().meta(Unrestricted6),
+  region: BuiltinRegionSchema.optional().meta(Unrestricted6),
+  device_type: BuiltinDeviceTypeSchema.optional().meta(Unrestricted6)
+});
 var UserInstanceContextSchema = z9.object({
   product_instance_id: z9.string().min(1).meta(Unrestricted6),
   user_id: z9.string().min(1).meta(Pii2),
@@ -3892,13 +3943,27 @@ var UserContextSchema = IdField.merge(TenantIdField).merge(TimestampFields).exte
   /** Customer-defined fields: role, app-level permissions, display prefs. */
   custom: z9.record(z9.string(), z9.union([z9.string(), z9.number(), z9.boolean(), z9.null()])).default({}).meta(Pii2),
   /**
-   * Transient personalization token map.
+   * Personalization token map.
    *
    * Holds SDK-derived tokens (plan_name, usage_current, etc.) merged with
-   * app-provided tokens.  Not persisted to the backend — rebuilt on each
-   * SDK session from context + exported config.
+   * app-provided tokens; the SDK rebuilds it on each session from context +
+   * exported config.
+   *
+   * Deliberately NOT marked field-level Transient: the `user_contexts` table
+   * carries a `personalization` jsonb column (web `drizzle/0000_*.sql`) and
+   * the generic user-context write persists it (web
+   * `src/lib/user-context/sanitize-write.ts` redacts it first). The drizzle
+   * generator emits no column for a field-level Transient (plan 279
+   * TASK-3), so the label has to match the table.
    */
-  personalization: z9.record(z9.string(), z9.union([z9.string(), z9.number()])).default({}).meta({ ...Unrestricted6, "x-revturbine-schema-persistence": Transient6 }),
+  personalization: z9.record(z9.string(), z9.union([z9.string(), z9.number()])).default({}).meta(Unrestricted6),
+  /**
+   * Built-in segment dimension values (plan 279 PD-3) — see
+   * {@link UserBuiltinDimensionsSchema}. Field-level Transient: no DB
+   * column; assembled at retrieval, or set by the app in `local_only` mode
+   * and on the server ports.
+   */
+  builtin_dimensions: UserBuiltinDimensionsSchema.optional().meta({ ...Unrestricted6, "x-revturbine-schema-persistence": Transient6 }),
   // ── Derived-entitlement cache (plan 74 REQ-12/REQ-13) ──────────────
   // `entitlements` above is the rule-evaluated projection — a CACHE, not
   // source of truth. These stamps record what it was computed against so a
@@ -3984,6 +4049,18 @@ var ClientContextPlanSchema = z9.object({
 }).meta(
   { id: "ClientContextPlan", "x-revturbine-schema-persistence": Transient6, "x-revturbine-schema-exposure": Internal5 }
 );
+var ClientContextBuiltinDimensionsSchema = z9.object({
+  activity_level: BuiltinActivityLevelSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
+  subscription_state: BuiltinSubscriptionStateSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
+  trial_type: BuiltinTrialTypeSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
+  seat_type: BuiltinSeatTypeSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
+  buyer_role: BuiltinBuyerRoleSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
+  email_type: BuiltinEmailTypeSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
+  region: BuiltinRegionSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
+  device_type: BuiltinDeviceTypeSchema.optional().meta({ ...Unrestricted6, ...ClientSafe })
+}).meta(
+  { id: "ClientContextBuiltinDimensions", "x-revturbine-schema-persistence": Transient6, "x-revturbine-schema-exposure": Internal5 }
+);
 var ClientContextSchema = z9.object({
   /** The end-user subject the client token was minted for (carried by the token, not the request). */
   subject: z9.string().min(1).meta({ ...Unrestricted6, ...ClientSafe }),
@@ -3992,7 +4069,9 @@ var ClientContextSchema = z9.object({
   trial: ClientContextTrialSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
   billing: ClientContextBillingSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
   plan: ClientContextPlanSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
-  capabilities: ClientContextCapabilitiesSchema.optional().meta({ ...Unrestricted6, ...ClientSafe })
+  capabilities: ClientContextCapabilitiesSchema.optional().meta({ ...Unrestricted6, ...ClientSafe }),
+  /** Server-evaluated built-in segment dimensions (plan 279 PD-3). */
+  builtin_dimensions: ClientContextBuiltinDimensionsSchema.optional().meta({ ...Unrestricted6, ...ClientSafe })
 }).meta(
   { id: "ClientContext", "x-revturbine-schema-persistence": Transient6, "x-revturbine-schema-exposure": Internal5 }
 );
@@ -4864,6 +4943,91 @@ var AnalyticsMetricLayerSchema = z14.enum(["primitive", "derived"]).meta(meta("A
 var AnalyticsCatalogStatusSchema = z14.enum(["declared", "bound", "validated", "tested", "unavailable"]).meta(meta("AnalyticsCatalogStatus"));
 var AnalyticsFactKindSchema = z14.enum(["transaction", "periodic_snapshot", "accumulating_snapshot"]).meta(meta("AnalyticsFactKind"));
 var AnalyticsConceptProducerSchema = z14.enum(["platform", "customer_authored", "simulation"]).meta(meta("AnalyticsConceptProducer"));
+var AnalyticsRecordDedupSchema = z14.enum(["deduplicated_on_record_id", "summed_on_sorting_key", "append_only", "upsert_on_primary_key", "recomputed_at_query", "unknown"]).meta(meta("AnalyticsRecordDedup"));
+var AnalyticsRecordRevisionSchema = z14.enum(["immutable", "re_emit_higher_version", "in_place_update", "recomputed_from_source", "unknown"]).meta(meta("AnalyticsRecordRevision"));
+var AnalyticsRecordLateArrivalSchema = z14.enum(["accepted", "accepted_within_retention", "rejected", "unknown"]).meta(meta("AnalyticsRecordLateArrival"));
+var AnalyticsRecordContractSchema = z14.object({
+  /** The columns whose tuple is the stable record id. Identity resolution is never part of it (R2). */
+  record_id: z14.array(z14.string().min(1).max(120)).min(1).max(8).meta(Unrestricted11),
+  /** Where the rows come from: `stripe`, `sdk_clickstream`, `revturbine_control_plane`. */
+  source_namespace: z14.string().min(1).max(120).meta(Unrestricted11),
+  /** Occurred (effective) time. */
+  occurred_time_field: z14.string().min(1).max(120).meta(Unrestricted11),
+  /** Received (observation) time; absent when the source records none. */
+  received_time_field: z14.string().min(1).max(120).optional().meta(Unrestricted11),
+  dedup: AnalyticsRecordDedupSchema.meta(Unrestricted11),
+  revision: AnalyticsRecordRevisionSchema.meta(Unrestricted11),
+  late_arrival: AnalyticsRecordLateArrivalSchema.meta(Unrestricted11),
+  correlation_keys: z14.array(z14.string().min(1).max(120)).max(12).optional().meta(Unrestricted11),
+  /**
+   * The field carrying Stripe live/test mode. R2 requires it on every
+   * billing fact; a billing concept that declares `livemode_qualified: true`
+   * must name it, and one that cannot is `livemode_qualified: false` with
+   * the gap stated in `note`.
+   */
+  livemode_field: z14.string().min(1).max(120).optional().meta(Unrestricted11),
+  /** Stamped policy-version fields (R2/R9). Empty or absent = none stamped. */
+  policy_version_fields: z14.array(z14.string().min(1).max(120)).max(8).optional().meta(Unrestricted11),
+  note: z14.string().max(400).optional().meta(Unrestricted11)
+}).meta(meta("AnalyticsRecordContract"));
+var AnalyticsKeyResolutionSchema = z14.enum(["source", "enriched", "absent"]).meta(meta("AnalyticsKeyResolution"));
+var AnalyticsConceptKeySchema = z14.object({
+  key: z14.string().regex(/^[a-z][a-z0-9_]{0,49}$/).meta(Unrestricted11),
+  /** `column:<name>`, `payload:<field>`, `envelope:<field>` - or `-` when absent. */
+  path: z14.string().min(1).max(200).meta(Unrestricted11),
+  resolution: AnalyticsKeyResolutionSchema.meta(Unrestricted11),
+  note: z14.string().max(400).optional().meta(Unrestricted11)
+}).meta(meta("AnalyticsConceptKey"));
+var AnalyticsMeasureUnitSchema = z14.enum(["currency_minor", "count", "seconds", "ratio", "timestamp", "usage_unit", "polymorphic"]).meta(meta("AnalyticsMeasureUnit"));
+var AnalyticsMeasureTemporalSchema = z14.enum(["stock", "flow", "gauge"]).meta(meta("AnalyticsMeasureTemporal"));
+var AnalyticsMeasureSignSchema = z14.enum(["signed", "positive_magnitude", "unsigned"]).meta(meta("AnalyticsMeasureSign"));
+var AnalyticsConceptMeasureSchema = z14.object({
+  name: z14.string().regex(/^[a-z][a-z0-9_]{0,63}$/).meta(Unrestricted11),
+  /** `column:<name>` or `row_count` - a transaction fact whose measure IS its row count. */
+  source: z14.string().min(1).max(200).meta(Unrestricted11),
+  unit: AnalyticsMeasureUnitSchema.meta(Unrestricted11),
+  temporal: AnalyticsMeasureTemporalSchema.meta(Unrestricted11),
+  sign: AnalyticsMeasureSignSchema.meta(Unrestricted11),
+  aggregation_semantics: AnalyticsMetricAggregationSemanticsSchema.meta(Unrestricted11),
+  note: z14.string().max(400).optional().meta(Unrestricted11)
+}).meta(meta("AnalyticsConceptMeasure"));
+var AnalyticsConceptEventAttributeSchema = z14.object({
+  name: z14.string().regex(/^[a-z][a-z0-9_]{0,63}$/).meta(Unrestricted11),
+  /** `column:<name>`, `payload:<field>` or `envelope:<field>`. */
+  path: z14.string().min(1).max(200).meta(Unrestricted11),
+  note: z14.string().max(400).optional().meta(Unrestricted11)
+}).meta(meta("AnalyticsConceptEventAttribute"));
+var AnalyticsConceptSourceKindSchema = z14.enum(["ingested_event", "datasource", "control_plane_table", "build", "unavailable"]).meta(meta("AnalyticsConceptSourceKind"));
+var AnalyticsConceptSourceSchema = z14.object({
+  kind: AnalyticsConceptSourceKindSchema.meta(Unrestricted11),
+  ref: z14.string().min(1).max(200).meta(Unrestricted11),
+  /** Required when `kind` is `unavailable`: what has to ship before rows exist. */
+  blocker: z14.string().max(400).optional().meta(Unrestricted11),
+  note: z14.string().max(400).optional().meta(Unrestricted11)
+}).meta(meta("AnalyticsConceptSource"));
+var AnalyticsConceptBuildSchema = z14.object({
+  kind: z14.enum(["pipe", "materialized_view", "worker", "query_time", "unavailable"]).meta(Unrestricted11),
+  ref: z14.string().min(1).max(200).meta(Unrestricted11),
+  inputs: z14.array(z14.string().min(1).max(200)).min(1).max(12).meta(Unrestricted11),
+  blocker: z14.string().max(400).optional().meta(Unrestricted11)
+}).meta(meta("AnalyticsConceptBuild"));
+var AnalyticsConceptMaturitySchema = z14.object({
+  status: z14.enum(["declared", "unavailable"]).meta(Unrestricted11),
+  horizon_field: z14.string().min(1).max(120).optional().meta(Unrestricted11),
+  observed_through_field: z14.string().min(1).max(120).optional().meta(Unrestricted11),
+  blocker: z14.string().max(400).optional().meta(Unrestricted11)
+}).meta(meta("AnalyticsConceptMaturity"));
+var AnalyticsOracleFamilySchema = z14.enum(["gate", "presentation", "revenue", "attribution", "event_count", "cohort", "funnel", "read_through", "none"]).meta(meta("AnalyticsOracleFamily"));
+var AnalyticsConceptOracleFamilySchema = z14.object({
+  family: AnalyticsOracleFamilySchema.meta(Unrestricted11),
+  blocker: z14.string().max(400).optional().meta(Unrestricted11)
+}).meta(meta("AnalyticsConceptOracleFamily"));
+var AnalyticsPolicyKindSchema = z14.enum(["mrr", "attribution", "lifecycle", "engagement"]).meta(meta("AnalyticsPolicyKind"));
+var AnalyticsConceptPolicyDependencySchema = z14.object({
+  kind: AnalyticsPolicyKindSchema.meta(Unrestricted11),
+  stamped: z14.boolean().meta(Unrestricted11),
+  blocker: z14.string().max(400).optional().meta(Unrestricted11)
+}).meta(meta("AnalyticsConceptPolicyDependency"));
 var AnalyticsGroundingAnchorSchema = z14.enum([
   "fact_time",
   "period_opening",
@@ -5064,13 +5228,20 @@ var AnalyticsCatalogConceptSchema = z14.object({
    * exposure, not per placement-day — a daily rollup is a pipe's physical
    * choice, not a second grain).
    *
-   * These fields are optional while the concepts migrate onto them. They
-   * are NOT decorative: a concept that declares `fact_kind` is asserting it
-   * has been mapped, and the structural rules tighten around it from there.
-   * Populating them for the existing concepts, and splitting `revenue.movement`
-   * into `revenue.stock` / `.movement` / `.ledger`, rides with the fact-table
-   * builds that produce the rows (later plan 252 tasks and plan 230) rather
-   * than being invented here.
+   * These fields stay optional on the canonical schema so a partial fixture
+   * still parses, but they are NOT decorative: a concept that declares
+   * `fact_kind` is asserting it has been mapped, and
+   * `AnalyticsCatalogConceptValidatedSchema` then REQUIRES the whole set —
+   * the same split as the metric schema. Every shipped concept declares them
+   * (BL-0246, TASK-58's second half).
+   *
+   * `revenue.movement` is still NOT split into `revenue.stock` /
+   * `.movement` / `.ledger`: today's definitions do not distinguish them
+   * (the only served measure is the invoice-paid cash proxy), so the split
+   * stays registered as the `catalog_status: 'unavailable'` blocker on
+   * `revenue.mrr` / `revenue.net_new_mrr` and rides with the normalized
+   * recurring stock and movement oracle (plan 252 TASK-29/34/36/45) that
+   * produce the rows. Declaring three empty concepts here would invent them.
    */
   fact_kind: AnalyticsFactKindSchema.optional().meta(Unrestricted11),
   family: z14.enum(["billing", "behavioral"]).optional().meta(Unrestricted11),
@@ -5084,8 +5255,286 @@ var AnalyticsCatalogConceptSchema = z14.object({
   }).optional().meta(Unrestricted11),
   /** Billing facts carry Stripe live/test mode; without it live and test revenue are indistinguishable. */
   livemode_qualified: z14.boolean().optional().meta(Unrestricted11),
+  /** The record contract the rows obey (R2). */
+  record_contract: AnalyticsRecordContractSchema.optional().meta(Unrestricted11),
+  /** Every entity key the fact carries, and the path it resolves through (R1). */
+  keys: z14.array(AnalyticsConceptKeySchema).max(24).optional().meta(Unrestricted11),
+  /**
+   * The stored measures. May be EMPTY for a concept every one of whose
+   * metrics is `catalog_status: 'unavailable'` — there is no measure to
+   * declare until the fact exists. The in-memory integrity check enforces
+   * that pairing, so an empty list cannot hide a served metric.
+   */
+  measures: z14.array(AnalyticsConceptMeasureSchema).max(32).optional().meta(Unrestricted11),
+  /** Non-key attributes carried on the row (R7). */
+  event_attributes: z14.array(AnalyticsConceptEventAttributeSchema).max(32).optional().meta(Unrestricted11),
+  /** Where the rows come from (R1/R5). */
+  sources: z14.array(AnalyticsConceptSourceSchema).min(1).max(12).optional().meta(Unrestricted11),
+  /** How snapshot rows are built (R5); required for both snapshot kinds. */
+  build: AnalyticsConceptBuildSchema.optional().meta(Unrestricted11),
+  /** Horizon / `observed_through` right-censoring (R5); required for accumulating snapshots. */
+  maturity: AnalyticsConceptMaturitySchema.optional().meta(Unrestricted11),
+  /** The pure oracle family that derives this concept's metrics (R6). */
+  oracle_family: AnalyticsConceptOracleFamilySchema.optional().meta(Unrestricted11),
+  /** The versioned policy kinds the rows depend on, and whether the version is stamped (R9). */
+  policy_dependencies: z14.array(AnalyticsConceptPolicyDependencySchema).max(8).optional().meta(Unrestricted11),
   deprecation: CatalogDeprecation.optional().meta(Unrestricted11)
 }).meta(meta("AnalyticsCatalogConcept"));
+var AnalyticsCatalogConceptValidatedSchema = AnalyticsCatalogConceptSchema.superRefine(
+  (concept, ctx) => {
+    const problem = (path3, code, message) => {
+      ctx.addIssue({ code: "custom", path: path3, params: { code }, message });
+    };
+    const duplicates = (names) => {
+      const seen = /* @__PURE__ */ new Set();
+      const dupes = /* @__PURE__ */ new Set();
+      for (const name of names) {
+        if (seen.has(name)) dupes.add(name);
+        seen.add(name);
+      }
+      return [...dupes].sort();
+    };
+    if (concept.fact_kind === void 0) {
+      for (const field of [
+        "family",
+        "primary_key",
+        "producer",
+        "materialization",
+        "livemode_qualified",
+        "record_contract",
+        "keys",
+        "measures",
+        "event_attributes",
+        "build",
+        "maturity"
+      ]) {
+        if (concept[field] !== void 0) {
+          problem(
+            [field],
+            "fact_table_field_without_fact_kind",
+            `${field} describes a fact table's rows, so the concept must declare fact_kind`
+          );
+        }
+      }
+      for (const [index, source] of (concept.sources ?? []).entries()) {
+        if (source.kind !== "unavailable") {
+          problem(
+            ["sources", index, "kind"],
+            "real_source_without_fact_kind",
+            "a concept naming a real row source must declare fact_kind (D-9: the concept IS the fact table)"
+          );
+        }
+      }
+    } else {
+      const required = [
+        "family",
+        "primary_key",
+        "producer",
+        "materialization",
+        "livemode_qualified",
+        "record_contract",
+        "keys",
+        "measures",
+        "event_attributes",
+        "sources",
+        "oracle_family",
+        "policy_dependencies"
+      ];
+      for (const field of required) {
+        if (concept[field] === void 0) {
+          problem(
+            [field],
+            "mapped_concept_missing_fact_table_field",
+            `a concept declaring fact_kind must declare ${field} (D-9: the concept IS the fact table)`
+          );
+        }
+      }
+      if (concept.keys !== void 0 && concept.keys.length === 0) {
+        problem(["keys"], "mapped_concept_without_keys", "a fact carries at least one entity key (R1)");
+      }
+      for (const [dimensionId, grounding] of Object.entries(concept.dimension_groundings ?? {})) {
+        if (grounding.anchor === void 0) {
+          problem(
+            ["dimension_groundings", dimensionId, "anchor"],
+            "grounding_without_anchor",
+            `grounding for ${dimensionId} must declare an anchor once the concept declares fact_kind (R8)`
+          );
+        }
+      }
+      if (concept.fact_kind === "accumulating_snapshot" && concept.maturity === void 0) {
+        problem(
+          ["maturity"],
+          "accumulating_snapshot_without_maturity",
+          "an accumulating snapshot must declare maturity \u2014 status 'unavailable' with a blocker when right-censoring is not implemented (R5)"
+        );
+      }
+      if (concept.fact_kind !== "transaction" && concept.build === void 0) {
+        problem(["build"], "snapshot_without_build", "a snapshot fact must declare the build that produces its rows (R5)");
+      }
+      if (concept.fact_kind === "transaction" && concept.maturity !== void 0) {
+        problem(["maturity"], "transaction_with_maturity", "maturity is a snapshot property; a transaction fact has no horizon (R5)");
+      }
+    }
+    for (const [dimensionId, grounding] of Object.entries(concept.dimension_groundings ?? {})) {
+      if (grounding.catalog_status === "unavailable" && !grounding.blocker?.trim()) {
+        problem(
+          ["dimension_groundings", dimensionId, "blocker"],
+          "unavailable_grounding_without_blocker",
+          `grounding for ${dimensionId} is catalog_status 'unavailable' and must name the blocker (R11/G13)`
+        );
+      }
+      if (grounding.catalog_status !== "unavailable" && grounding.blocker !== void 0) {
+        problem(
+          ["dimension_groundings", dimensionId, "blocker"],
+          "grounding_blocker_without_unavailable",
+          `grounding for ${dimensionId} carries a blocker, so its catalog_status must be 'unavailable' (R11/G13)`
+        );
+      }
+      if (grounding.kind !== "config_join" && grounding.kind !== "membership_join") continue;
+      if (grounding.catalog_status === "unavailable") continue;
+      const joined = (concept.sources ?? []).some(
+        (source) => source.ref === grounding.source && source.kind !== "unavailable"
+      );
+      if (!joined) {
+        problem(
+          ["dimension_groundings", dimensionId, "source"],
+          "join_grounding_without_execution_path",
+          `grounding for ${dimensionId} is a ${grounding.kind} against '${grounding.source}', which the concept does not declare among its sources \u2014 nothing performs that join, so the grounding must declare catalog_status 'unavailable' with its blocker (R11/G13)`
+        );
+      }
+    }
+    if (concept.materialization?.mode === "rollup" && concept.materialization.rollup_grain === void 0) {
+      problem(["materialization", "rollup_grain"], "rollup_without_grain", "materialization mode 'rollup' must name its rollup_grain");
+    }
+    if (concept.materialization && concept.materialization.mode !== "rollup" && concept.materialization.rollup_grain !== void 0) {
+      problem(["materialization", "rollup_grain"], "rollup_grain_without_rollup", "rollup_grain is only meaningful when mode is 'rollup'");
+    }
+    if (concept.family === "billing" && concept.livemode_qualified === void 0) {
+      problem(["livemode_qualified"], "billing_concept_without_livemode", "a billing fact must state whether it is live/test qualified (R2)");
+    }
+    if (concept.livemode_qualified === true && concept.record_contract?.livemode_field === void 0) {
+      problem(
+        ["record_contract", "livemode_field"],
+        "livemode_qualified_without_field",
+        "livemode_qualified: true must name the field carrying Stripe live/test mode (R2)"
+      );
+    }
+    for (const [index, key2] of (concept.keys ?? []).entries()) {
+      if (key2.resolution === "absent" && !key2.note?.trim()) {
+        problem(["keys", index, "note"], "absent_key_without_note", "resolution 'absent' must state why the key is not carried (R1)");
+      }
+      if (key2.resolution === "absent" && key2.path !== "-") {
+        problem(["keys", index, "path"], "absent_key_with_path", "resolution 'absent' must carry path '-' \u2014 there is no path to read");
+      }
+      if (key2.resolution !== "absent" && key2.path === "-") {
+        problem(["keys", index, "path"], "resolved_key_without_path", "a source or enriched key must name the path it resolves through");
+      }
+    }
+    for (const duplicate of duplicates((concept.keys ?? []).map((key2) => key2.key))) {
+      problem(["keys"], "duplicate_key", `duplicate entity key: ${duplicate}`);
+    }
+    for (const [index, measure] of (concept.measures ?? []).entries()) {
+      if (measure.temporal === "stock" && measure.aggregation_semantics !== "semi_additive") {
+        problem(
+          ["measures", index, "aggregation_semantics"],
+          "stock_measure_not_semi_additive",
+          "a stock measure is semi_additive by construction \u2014 it is summed at one date, never across dates (R3)"
+        );
+      }
+      if (measure.unit === "polymorphic") {
+        if (!measure.note?.trim()) {
+          problem(
+            ["measures", index, "note"],
+            "polymorphic_measure_without_note",
+            "unit 'polymorphic' must name the column that decides the unit"
+          );
+        }
+        if (measure.aggregation_semantics !== "non_additive") {
+          problem(
+            ["measures", index, "aggregation_semantics"],
+            "polymorphic_measure_summed",
+            "unit 'polymorphic' is non_additive \u2014 rows of different units cannot be summed"
+          );
+        }
+      }
+      if (measure.unit === "count" && measure.sign === "signed") {
+        problem(["measures", index, "sign"], "signed_count_measure", "a count is unsigned; a signed change is a currency or usage delta (R3)");
+      }
+    }
+    for (const duplicate of duplicates((concept.measures ?? []).map((measure) => measure.name))) {
+      problem(["measures"], "duplicate_measure", `duplicate measure name: ${duplicate}`);
+    }
+    for (const duplicate of duplicates((concept.event_attributes ?? []).map((attribute) => attribute.name))) {
+      problem(["event_attributes"], "duplicate_event_attribute", `duplicate event attribute: ${duplicate}`);
+    }
+    for (const [index, source] of (concept.sources ?? []).entries()) {
+      if (source.kind === "unavailable" && !source.blocker?.trim()) {
+        problem(["sources", index, "blocker"], "unavailable_source_without_blocker", "source kind 'unavailable' must name the blocker");
+      }
+      if (source.kind !== "unavailable" && source.blocker !== void 0) {
+        problem(["sources", index, "blocker"], "available_source_with_blocker", "a real source carries no blocker \u2014 use note");
+      }
+    }
+    const sourceKinds = new Set((concept.sources ?? []).map((source) => source.kind));
+    if (sourceKinds.has("unavailable") && sourceKinds.size > 1) {
+      problem(["sources"], "mixed_unavailable_sources", "a concept with an 'unavailable' source declares no other source");
+    }
+    if (sourceKinds.has("unavailable") && (concept.measures?.length ?? 0) > 0) {
+      problem(["measures"], "unavailable_source_with_measures", "a concept with no fact declares no measures");
+    }
+    if (concept.build?.kind === "unavailable" && !concept.build.blocker?.trim()) {
+      problem(["build", "blocker"], "unavailable_build_without_blocker", "build kind 'unavailable' must name the blocker");
+    }
+    if (concept.build && concept.build.kind !== "unavailable" && concept.build.blocker !== void 0) {
+      problem(["build", "blocker"], "available_build_with_blocker", "a real build carries no blocker");
+    }
+    if (concept.maturity) {
+      if (concept.maturity.status === "declared") {
+        for (const field of ["horizon_field", "observed_through_field"]) {
+          if (concept.maturity[field] === void 0) {
+            problem(["maturity", field], "declared_maturity_missing_field", `maturity status 'declared' must name ${field} (R5)`);
+          }
+        }
+        if (concept.maturity.blocker !== void 0) {
+          problem(["maturity", "blocker"], "declared_maturity_with_blocker", "maturity status 'declared' carries no blocker");
+        }
+      } else if (!concept.maturity.blocker?.trim()) {
+        problem(["maturity", "blocker"], "unavailable_maturity_without_blocker", "maturity status 'unavailable' must name the blocker");
+      }
+    }
+    if (concept.oracle_family) {
+      if (concept.oracle_family.family === "none" && !concept.oracle_family.blocker?.trim()) {
+        problem(["oracle_family", "blocker"], "no_oracle_without_blocker", "oracle_family 'none' must name why no oracle covers this concept (R6)");
+      }
+      if (concept.oracle_family.family !== "none" && concept.oracle_family.blocker !== void 0) {
+        problem(["oracle_family", "blocker"], "oracle_family_with_blocker", "a concept with an oracle family carries no blocker");
+      }
+    }
+    for (const [index, dependency] of (concept.policy_dependencies ?? []).entries()) {
+      if (!dependency.stamped && !dependency.blocker?.trim()) {
+        problem(
+          ["policy_dependencies", index, "blocker"],
+          "unstamped_policy_without_blocker",
+          `policy dependency '${dependency.kind}' is not stamped on the row, so it must name the blocker (R9)`
+        );
+      }
+      if (dependency.stamped && dependency.blocker !== void 0) {
+        problem(["policy_dependencies", index, "blocker"], "stamped_policy_with_blocker", "a stamped policy dependency carries no blocker");
+      }
+    }
+    for (const duplicate of duplicates((concept.policy_dependencies ?? []).map((dependency) => dependency.kind))) {
+      problem(["policy_dependencies"], "duplicate_policy_dependency", `duplicate policy dependency: ${duplicate}`);
+    }
+    const stampedPolicies = (concept.policy_dependencies ?? []).filter((dependency) => dependency.stamped);
+    if (stampedPolicies.length > 0 && (concept.record_contract?.policy_version_fields?.length ?? 0) === 0) {
+      problem(
+        ["record_contract", "policy_version_fields"],
+        "stamped_policy_without_version_field",
+        "a stamped policy dependency requires the record contract to name the policy-version field it is stamped in (R2)"
+      );
+    }
+  }
+).meta(meta("AnalyticsCatalogConceptValidated"));
 var OrderBy = z14.strictObject({
   field: SemanticIdField.meta(Unrestricted11),
   direction: z14.enum(["asc", "desc"]).meta(Unrestricted11)
@@ -5526,7 +5975,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 +6022,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 +6053,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 +6095,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({
@@ -5638,6 +6167,51 @@ var MilestonePayload = z18.looseObject({});
 var AcquisitionMilestonePayload = z18.looseObject({
   acquisition_source: z18.string().optional().meta(Unrestricted15)
 });
+var LifecycleEvidence = z18.looseObject({
+  kind: z18.enum(["provider_fact", "app_fact", "usage_exhaustion"]).meta(Unrestricted15),
+  /** The producer-scoped reference to the proving fact (a Stripe event id, an
+   * app write id, a metering observation id). Opaque to RevTurbine. */
+  ref: str()
+});
+var AccountCreatedPayload = z18.looseObject({
+  acquisition_source: z18.string().optional().meta(Unrestricted15),
+  /** The account grain (plan 276 R-2) — never a user id. */
+  account_id: onstr(),
+  /** When the account came into existence, per the producer. */
+  created_at: onstr(),
+  /** What kind of act created it (e.g. `self_serve_signup`, `invite_accepted`,
+   * `provisioned`, `import`). A USER signup is not account creation (R-2). */
+  source: onstr(),
+  evidence: LifecycleEvidence.nullable().optional()
+});
+var TrialRevisionPayload = z18.looseObject({
+  /** Stable id for the episode this revision belongs to. Conversion links only
+   * its OWN episode (plan 276 AC-4), so this is half the identity key. */
+  trial_episode_id: str(),
+  /** The account the episode is materialized against (R-2). */
+  account_id: str(),
+  /** `user` retains a user-subject episode WITHOUT making it an account-wide
+   * grant (R-2); `account` is an account-wide grant. */
+  subject_scope: z18.enum(["account", "user"]).meta(Unrestricted15),
+  /** The Playbook trial rule's `unique_handle`, when the episode came from one. */
+  rule_handle: onstr(),
+  /** The trialed plan's handle, when the episode grants one plan. */
+  plan_handle: onstr(),
+  /** `free_trial` / `reverse_trial` / anything the tenant runs. Vocabulary only. */
+  trial_type: onstr(),
+  revision: z18.enum(["started", "extended", "converted", "reverted", "expired", "revoked"]).meta(Unrestricted15),
+  /** When the revision took effect, per the proving fact — never the write clock. */
+  effective_at: str(),
+  /** The declared end. Its passing proves only that the time passed (R-1(c)). */
+  scheduled_end_at: onstr(),
+  /** The EVIDENCED end. Null until a fact closes the episode. */
+  actual_end_at: onstr(),
+  evidence: LifecycleEvidence,
+  /** The biller's reference when a provider fact is involved (e.g. a Stripe
+   * subscription id), so an app fact and a provider derivative about the same
+   * episode can be reconciled. */
+  provider_ref: onstr()
+});
 var UsageRecordedPayload = z18.looseObject({
   metered_units: z18.number().nonnegative().meta(Unrestricted15),
   included_allowance: z18.number().nonnegative().meta(Unrestricted15),
@@ -5775,7 +6349,7 @@ var EVENT_PAYLOAD_CONTRACTS = {
   user_context_observed: { schema: UserContextObservedPayload, identity: envelopeIdentity },
   clickstream_page_view: { schema: PageViewPayload, identity: envelopeIdentity },
   // SDK client — customer-product lifecycle milestones (promoted, R-1)
-  account_created: { schema: AcquisitionMilestonePayload, identity: envelopeIdentity },
+  account_created: { schema: AccountCreatedPayload, identity: envelopeIdentity },
   user_signed_up: { schema: AcquisitionMilestonePayload, identity: envelopeIdentity },
   onboarding_completed: { schema: MilestonePayload, identity: envelopeIdentity },
   account_activated: { schema: MilestonePayload, identity: envelopeIdentity },
@@ -5785,6 +6359,10 @@ var EVENT_PAYLOAD_CONTRACTS = {
   plan_viewed: { schema: PlanViewedPayload, identity: envelopeIdentity },
   promotion_applied: { schema: PromotionAppliedPayload, identity: envelopeIdentity },
   promotion_converted: { schema: PromotionConvertedPayload, identity: envelopeIdentity },
+  // App-owned trial episode (plan 276 R-1(b)) — identity is the episode plus
+  // the revision, so a retry of the same app fact collapses while a later
+  // revision of the same episode stays a distinct occurrence.
+  trial_revision: { schema: TrialRevisionPayload, identity: ["trial_episode_id", "revision"] },
   // SDK server — derived observations
   growth_signal_observed: { schema: GrowthSignalObservedPayload, identity: envelopeIdentity },
   // SDK meta lane
@@ -5904,7 +6482,15 @@ var SDK_CLIENT_EVENT_NAMES = [
   "usage_recorded",
   "plan_viewed",
   "promotion_applied",
-  "promotion_converted"
+  "promotion_converted",
+  // App-owned trial-episode revision (plan 276 R-1(b), TASK-12/TASK-13; ruling
+  // D-21). The authoritative fact for an APP-RUN trial: the tenant's product
+  // owns trial execution, so only the tenant's product can state that an
+  // episode started, was extended, converted, reverted, expired or was
+  // revoked. Distinct from the `trial_*` billing band, which is the provider
+  // derivative (R-1(a)) and cannot establish enrolment. The clock is never an
+  // authority (R-1(c)): an elapsed scheduled end emits nothing at all.
+  "trial_revision"
 ];
 var SDK_SERVER_EVENT_NAMES = [
   "growth_signal_observed"
@@ -5985,7 +6571,7 @@ var EVENT_METADATA = {
   sdk_validation_warning: { purpose: "The SDK found a config or usage problem worth surfacing.", stability: "internal" },
   resolution_failure: { purpose: "A decision produced nothing; allow-listed handles and closed reason codes only.", stability: "internal" },
   // Customer-product lifecycle milestones (plan 228 TASK-2, promoted under R-1)
-  account_created: { purpose: "A customer account came into existence in the tenant product; acquisition_source rides on the payload.", stability: "stable" },
+  account_created: { purpose: "A customer account came into existence in the tenant product; acquisition_source rides on the payload, and the plan-276 REQ-3 account-creation evidence (account_id, created_at, source, evidence) rides on it when the producer holds it.", stability: "stable" },
   user_signed_up: { purpose: "A user completed signup in the tenant product.", stability: "stable" },
   onboarding_completed: { purpose: "A user finished the tenant product onboarding flow.", stability: "stable" },
   account_activated: { purpose: "An account reached the tenant-defined activation milestone.", stability: "stable" },
@@ -5995,6 +6581,7 @@ var EVENT_METADATA = {
   plan_viewed: { purpose: "A user viewed plan or pricing content; plan_handle and entry_tier ride on the payload.", stability: "stable" },
   promotion_applied: { purpose: "A promotion was applied to an account; promotion_handle rides on the payload.", stability: "stable" },
   promotion_converted: { purpose: "An account with a promotion converted; full_price marks conversions where the discount lapsed first.", stability: "stable" },
+  trial_revision: { purpose: "The app-owned authoritative fact about one trial episode (plan 276 R-1(b)): which revision occurred (started/extended/converted/reverted/expired/revoked), when it took effect, and the evidence that proves it. Trial execution and ownership stay with the customer app.", stability: "stable" },
   // Server-derived observations (plan 228 TASK-2)
   growth_signal_observed: { purpose: "A pre-computed windowed metric observation written by a server-side producer; readers should prefer read-time derivation where a platform source exists.", stability: "internal" },
   // Billing lifecycle (plan 228 R-2) — dual-source: Stripe webhook processor OR typed SDK emit.
@@ -6373,7 +6960,29 @@ var EventEnvelopeSchema = IdField.extend({
   event_type: z24.string().min(1).meta(Unrestricted20),
   source: EventSourceSchema.default("sdk").meta(Unrestricted20),
   tenant_id: z24.string().min(1).optional().meta(Unrestricted20),
-  user_id: z24.string().min(1).optional().meta(Pii4),
+  /**
+   * Identity keys are `Unrestricted` on EVERY lane (BL-0131, Kent's **D-19**,
+   * 2026-09-25): *"Not treated as PII, but a PII leak still detectable. We
+   * want our customers to use UUIDs, but if they pass an email, we need to
+   * hash it consistently."*
+   *
+   * A `user_id` / `account_id` is the TENANT'S OWN primary key, not personal
+   * data. Before BL-0131 the three ingest lanes disagreed — `TrackEvent.user_id`
+   * and `TreatmentInteractionInput.account_id` were `Pii` while
+   * `TrackEvent.account_id` was `Unrestricted` — so the same logical key
+   * carried two classifications depending on which route it arrived through.
+   *
+   * The leak is handled at the BOUNDARY, not by the classification:
+   * `classifyIdentityValue` / `normalizeIdentityValue` in `@revt-eng/core`
+   * detect a PII-shaped value, consistently hash an email-shaped one
+   * (`eml_<sha256-16>`, unsalted so every writer and reader agrees), and
+   * report `identity_pii_detected` so the tenant learns to send UUIDs.
+   *
+   * Dropping `pii` does NOT widen browser exposure: the plan-157
+   * client-context filter is an allowlist keyed on field-level `external`
+   * exposure, which these fields do not carry, so they stay `server_only`.
+   */
+  user_id: z24.string().min(1).optional().meta(Unrestricted20),
   session_id: z24.string().min(1).optional().meta(Pii4),
   occurred_at: z24.string().datetime().meta(Unrestricted20),
   request_id: z24.string().min(1).meta(Unrestricted20),
@@ -6401,7 +7010,9 @@ var EventIngestBatchSchema = z24.array(
     event_type: z24.string().min(1).meta(Unrestricted20),
     occurred_at: z24.string().datetime().optional().meta(Unrestricted20),
     tenant_id: z24.string().min(1).optional().meta(Unrestricted20),
-    user_id: z24.string().min(1).optional().meta(Pii4),
+    // Identity key — `Unrestricted` on every lane (BL-0131, D-19); see
+    // `EventEnvelopeSchema.user_id`.
+    user_id: z24.string().min(1).optional().meta(Unrestricted20),
     session_id: z24.string().min(1).optional().meta(Pii4),
     attributes: z24.record(z24.string(), z24.unknown()).optional().meta(Unrestricted20),
     payload: z24.record(z24.string(), z24.unknown()).optional().meta(Unrestricted20),
@@ -6431,7 +7042,9 @@ var TreatmentInteractionTypeSchema = z24.enum([
   }
 );
 var TreatmentInteractionInputSchema = z24.object({
-  user_id: z24.string().min(1).meta(Pii4),
+  // Identity key — `Unrestricted` on every lane (BL-0131, D-19); see
+  // `EventEnvelopeSchema.user_id` for the full rationale.
+  user_id: z24.string().min(1).meta(Unrestricted20),
   /**
    * The account / organization the user acted on behalf of (plan 232 REQ-4).
    *
@@ -6446,8 +7059,13 @@ var TreatmentInteractionInputSchema = z24.object({
    * Optional, and the route keeps the `user_id` fallback when it is absent,
    * so pre-232 SDKs behave exactly as before rather than writing an empty
    * key that the `account_id != ''` predicates would silently drop.
+   *
+   * BL-0131 (D-19) aligned this to `Unrestricted`, matching the clickstream
+   * half (`TrackEvent.account_id`): an account id is a join key, not
+   * personal data, and a PII-shaped value is detected and consistently
+   * hashed at the ingest boundary instead of being re-labelled here.
    */
-  account_id: z24.string().min(1).optional().meta(Pii4),
+  account_id: z24.string().min(1).optional().meta(Unrestricted20),
   placement_id: z24.string().min(1).meta(Unrestricted20),
   treatment_id: z24.string().min(1).optional().meta(Unrestricted20),
   // Presentation context (plan 114) — carried so a treatment interaction can
@@ -6473,6 +7091,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
@@ -6673,7 +7315,9 @@ var EventOriginSchema = z24.enum(["explicit", "automatic", "derived", "raw"]).me
 );
 var TrackEventSchema = z24.object({
   environment_id: z24.string().min(1).meta(Unrestricted20),
-  user_id: z24.string().min(1).meta(Pii4),
+  // Identity key — `Unrestricted` on every lane (BL-0131, D-19); see
+  // `EventEnvelopeSchema.user_id` for the full rationale.
+  user_id: z24.string().min(1).meta(Unrestricted20),
   /**
    * The account / organization the user acted on behalf of (BL-0117).
    *
@@ -7388,6 +8032,39 @@ var TrialInstanceSchema = IdField.merge(TimestampFields).merge(TenantIdField).ex
   usage_limit_value: z27.number().int().min(1).optional().meta(Unrestricted21),
   converted_at: NullableDatetimeField.meta(Unrestricted21),
   cancelled_at: NullableDatetimeField.meta(Unrestricted21),
+  /**
+   * Stable identity of the trial EPISODE this row represents
+   * (BL-0247 / plan 276 TASK-12). A customer can run more than one
+   * trial, and a subscription can re-enter `trialing`, so the
+   * (customer, subscription) pair does not name an occurrence. The
+   * billing lane already discriminates an episode by the Stripe
+   * subscription id plus its `trial_start`; this column persists
+   * that same discriminator so a fact about one episode can be
+   * written to exactly that episode's row.
+   *
+   * Nullable: rows created before the column existed, and rows
+   * created by paths that have no Stripe evidence to mint an id
+   * from, carry NULL. NULL means "this episode has no first-class
+   * identity", never "episode zero" — and Postgres treats NULLs as
+   * distinct, so the composite UNIQUE below does not collapse them.
+   */
+  trial_episode_id: z27.string().min(1).nullable().optional().meta(Unrestricted21),
+  /**
+   * The Stripe subscription this episode belongs to — the binding
+   * that lets a Stripe fact resolve one episode without guessing
+   * (BL-0245 carried this in `metadata.stripe_subscription_id`).
+   * Nullable because a trial need not originate from Stripe at all.
+   */
+  stripe_subscription_id: z27.string().min(1).nullable().optional().meta(Unrestricted21),
+  /**
+   * The EVIDENCED end of the episode: the moment a provider fact
+   * said the trial actually stopped. Distinct from `expires_at`,
+   * which is the SCHEDULED end and must stay distinguishable
+   * (plan 276 R-1 — no clock authority; an elapsed `expires_at`
+   * with no fact behind it is not an end). Null until a fact
+   * proves one.
+   */
+  actual_end_at: NullableDatetimeField.meta(Unrestricted21),
   metadata: MetadataField.meta(Unrestricted21)
 }).meta(
   { id: "TrialInstance", "x-revturbine-schema-persistence": Persisted13, "x-revturbine-schema-exposure": Internal17 }
@@ -7590,7 +8267,12 @@ var trialPaths = {
       summary: "List trial instances",
       tags: ["trials"],
       responses: { "200": { description: "Trial instance list", content: { "application/json": { schema: ListEnvelope(TrialInstanceSchema) } } } },
-      "x-revturbine-operation": { exposure: "internal", resource: "trial-instances", persistence: { table: "trialInstances", mode: "list" } }
+      // One row per trial EPISODE (BL-0247 / plan 276 TASK-12). This is the
+      // ON CONFLICT target the Stripe binding writer upserts against, so a
+      // re-delivered `customer.subscription.*` event updates the episode it
+      // already created instead of minting a duplicate. NULL episode ids are
+      // distinct in Postgres, so pre-existing and non-Stripe rows are unaffected.
+      "x-revturbine-operation": { exposure: "internal", resource: "trial-instances", persistence: { table: "trialInstances", mode: "list", uniqueBy: ["tenant_id", "customer_id", "trial_episode_id"] } }
     })
   },
   "/api/trials/instances/{instanceId}": {
@@ -8597,6 +9279,16 @@ var PersonalizationTokenSchema = IdField.merge(TimestampFields).merge(TenantIdFi
   { id: "PersonalizationToken", "x-revturbine-schema-persistence": Persisted16, "x-revturbine-schema-exposure": Internal20, ...PENDING_PLAYBOOK_FACETS4, ...namedIdentity() }
 );
 var PersonalizationTokenAnchorSchema = makeAnchor("PersonalizationTokenAnchor");
+var ObjectiveSchema = IdField.merge(TimestampFields).merge(TenantIdField).merge(AnchorFields).merge(VersionFields).extend({
+  anchor_id: z30.string().min(1).meta({ ...Unrestricted24, readOnly: true }),
+  handle: HandleField.meta(Unrestricted24),
+  name: NameField.meta(Unrestricted24),
+  description: DescriptionField.meta(Unrestricted24),
+  metadata: MetadataField.meta(Unrestricted24)
+}).meta(
+  { id: "Objective", "x-revturbine-schema-persistence": Persisted16, "x-revturbine-schema-exposure": Internal20, ...PLAYBOOK_AUTHORING_FACETS2, ...namedIdentity() }
+);
+var ObjectiveAnchorSchema = makeAnchor("ObjectiveAnchor");
 var OnboardingStateSchema = z30.enum(["not_started", "started", "details_submitted", "charges_enabled", "activated", "deauthorized"]).meta({ id: "OnboardingState", "x-revturbine-schema-persistence": Transient24, "x-revturbine-schema-exposure": Internal20 });
 var StripeIntegrationConfigSchema = IdField.merge(TimestampFields).merge(TenantIdField).merge(AnchorFields).merge(VersionFields).extend({
   handle: HandleField.meta({ ...Unrestricted24, readOnly: true }),
@@ -8914,7 +9606,9 @@ var RevTurbineConfigEntitlementRulesItemSchema = z30.object({
   }).shape,
   current_usage: z30.number().default(0).meta(Unrestricted24),
   /** How usage is partitioned across the identity hierarchy. */
-  allocation: UsageAllocationSchema.optional().meta(Unrestricted24)
+  allocation: UsageAllocationSchema.optional().meta(Unrestricted24),
+  /** Optional business objective, by `objectives[].handle` (VAL-OBJ-01). Config-only. */
+  objective: ObjectiveField.meta(Unrestricted24)
 }).meta(
   { id: "RevTurbineConfigEntitlementRulesItem", "x-revturbine-schema-persistence": Transient24, "x-revturbine-schema-exposure": External12, ...PLAYBOOK_SDK_FACETS8 }
 );
@@ -9010,6 +9704,13 @@ var RevTurbineConfigPersonalizationTokensItemSchema = z30.object({
 }).meta(
   { id: "RevTurbineConfigPersonalizationTokensItem", "x-revturbine-schema-persistence": Transient24, "x-revturbine-schema-exposure": External12, ...PLAYBOOK_SDK_FACETS8 }
 );
+var RevTurbineConfigObjectivesItemSchema = z30.object({
+  handle: HandleField.meta(Unrestricted24),
+  name: NameField.meta(Unrestricted24),
+  description: DescriptionField.meta(Unrestricted24)
+}).meta(
+  { id: "RevTurbineConfigObjectivesItem", "x-revturbine-schema-persistence": Transient24, "x-revturbine-schema-exposure": External12, ...PLAYBOOK_AUTHORING_FACETS2 }
+);
 var MessageBlockContentSchema = z30.object({
   header: z30.string().optional().meta(Unrestricted24),
   body: z30.string().optional().meta(Unrestricted24),
@@ -9113,7 +9814,9 @@ var RevTurbineConfigPlacementItemSchema = z30.object({
   category: RevTurbineConfigPlacementCategorySchema.meta(Unrestricted24),
   trigger: RevTurbineConfigPlacementTriggerSchema.meta(Unrestricted24),
   payloads: z30.array(RevTurbineConfigStudioPayloadSchema).meta(Unrestricted24),
-  order: z30.number().int().min(0).meta(Unrestricted24)
+  order: z30.number().int().min(0).meta(Unrestricted24),
+  /** Optional business objective, by `objectives[].handle` (VAL-OBJ-01). Config-only. */
+  objective: ObjectiveField.meta(Unrestricted24)
 }).meta(
   { id: "RevTurbineConfigPlacementItem", "x-revturbine-schema-persistence": Transient24, "x-revturbine-schema-exposure": External12, ...PLAYBOOK_SDK_FACETS8 }
 );
@@ -9207,6 +9910,14 @@ var PlaybookBodySchema = z30.object({
    */
   free_trial_rules: z30.array(RevTurbineConfigFreeTrialRuleItemSchema).optional().meta({ ...Unrestricted24, ...PLAYBOOK_AUTHORING_FACETS2 }),
   reverse_trial_rules: z30.array(RevTurbineConfigReverseTrialRuleItemSchema).optional().meta({ ...Unrestricted24, ...PLAYBOOK_AUTHORING_FACETS2 }),
+  /**
+   * Business objectives (BL-0176 / BL-0178, ruling D-15). Optional so every
+   * Playbook authored before objectives existed still parses. Placements and
+   * entitlement rules reference an entry by `handle` through their optional
+   * `objective` field. Authoring-only: no runtime decision reads it, so it is
+   * not an SDK input and never lowers into the IR.
+   */
+  objectives: z30.array(RevTurbineConfigObjectivesItemSchema).optional().meta({ ...Unrestricted24, ...PLAYBOOK_AUTHORING_FACETS2 }),
   // Plan / add-on variation prices carried by handle (plan 118 TASK-16). These
   // live on the legacy schema (not just the canonical Playbook body) so that a
   // legacy `version`-shaped config — the shape the demo-data configs and the
@@ -9473,6 +10184,56 @@ var configPaths = {
       "x-revturbine-operation": { exposure: "internal", resource: "personalization-tokens", persistence: { table: "personalizationTokenVersions", mode: "delete" } }
     })
   },
+  "/api/objective-anchors": {
+    get: operation({
+      operationId: "listObjectiveAnchors",
+      requestParams: { query: ListQueryParamsSchema },
+      summary: "List objective anchors (identity registry)",
+      tags: ["config"],
+      responses: {
+        "200": { description: "Objective anchor list", content: { "application/json": { schema: ListEnvelope(ObjectiveAnchorSchema) } } },
+        default: { description: "Error response", content: { "application/json": { schema: ErrorEnvelope } } }
+      },
+      "x-revturbine-operation": { exposure: "internal", resource: "objective-anchors", persistence: { table: "objectives", mode: "list" } }
+    })
+  },
+  "/api/config/objectives": {
+    get: operation({
+      operationId: "listObjectives",
+      requestParams: { query: ListQueryParamsSchema },
+      summary: "List objectives",
+      tags: ["config"],
+      responses: { "200": { description: "Objective list", content: { "application/json": { schema: ListEnvelope(ObjectiveSchema) } } } },
+      "x-revturbine-operation": { exposure: "internal", resource: "objectives", persistence: { table: "objectiveVersions", mode: "list" } }
+    }),
+    post: operation({
+      operationId: "createObjective",
+      summary: "Create objective",
+      tags: ["config"],
+      requestBody: { required: true, content: { "application/json": { schema: toCreateSchema(ObjectiveSchema) } } },
+      responses: { "201": { description: "Created", content: { "application/json": { schema: ObjectiveSchema } } } },
+      "x-revturbine-operation": { exposure: "internal", resource: "objectives", persistence: { table: "objectiveVersions", mode: "create" } }
+    })
+  },
+  "/api/config/objectives/{id}": {
+    patch: operation({
+      operationId: "updateObjective",
+      requestParams: { path: z30.object({ id: z30.string() }) },
+      summary: "Update objective",
+      tags: ["config"],
+      requestBody: { required: true, content: { "application/json": { schema: ObjectiveSchema.partial() } } },
+      responses: { "200": { description: "Updated", content: { "application/json": { schema: ObjectiveSchema } } } },
+      "x-revturbine-operation": { exposure: "internal", resource: "objectives", persistence: { table: "objectiveVersions", mode: "update" } }
+    }),
+    delete: operation({
+      operationId: "deleteObjective",
+      requestParams: { path: z30.object({ id: z30.string() }) },
+      summary: "Delete objective",
+      tags: ["config"],
+      responses: { "204": { description: "Deleted" } },
+      "x-revturbine-operation": { exposure: "internal", resource: "objectives", persistence: { table: "objectiveVersions", mode: "delete" } }
+    })
+  },
   "/api/config/stripe": {
     get: operation({
       operationId: "getStripeIntegrationConfig",
@@ -9925,6 +10686,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 });
@@ -10750,6 +11519,19 @@ var CATALOG = {
     message: "This limit rule sets no enforcement \u2014 at the cap it blocks by default. Set enforcement explicitly (hard_block, block_with_upsell, degrade, allow_overage) if that isn't the intent.",
     specRef: "config-validation.md \xA75.8 (promoted \u2014 plan 179 Q-6)"
   },
+  // handle uniqueness (BL-0325; spec §5.1 VAL-UNI-01). A handle duplicates
+  // another object's handle within the same handle-bearing collection — the
+  // structural counterpart to the DB's partial unique indexes (migration
+  // 0050) and Compile+Activate's own handle collapse. `error_draft`: per §2
+  // this is a malformed/structurally-invalid value ("a duplicate handle"),
+  // so it must never enter the draft at all, on any surface — including an
+  // external config at ingestion.
+  "VAL-UNI-01": {
+    id: "VAL-UNI-01",
+    severity: "error_draft",
+    message: "This handle is already in use.",
+    specRef: "config-validation.md \xA75.1 (VAL-UNI-01)"
+  },
   // segment → experiment reference (plan 183). Handle, not id.
   "VAL-SEG-01": {
     id: "VAL-SEG-01",
@@ -10757,6 +11539,15 @@ var CATALOG = {
     message: "This segment enrols users into an experiment that does not exist.",
     specRef: "config-validation.md \xA75.3 (plan 183)"
   },
+  // reserved built-in segment handle prefix (plan 279 TASK-2). Built-in
+  // `rt.<dimension>.<value>` definitions are generated at export; an authored
+  // one collides with or impersonates a built-in.
+  "VAL-SEG-02": {
+    id: "VAL-SEG-02",
+    severity: "error_launch",
+    message: "This segment's handle starts with 'rt.', which is reserved for built-in segments.",
+    specRef: "config-validation.md \xA75.4; targeting-studio-ui.md \xA74.1 (plan 279)"
+  },
   // experiment metric → Semantic Catalog reference (plan 199). The identifier
   // is structurally valid, but the active catalog does not declare it.
   "VAL-EXP-01": {
@@ -10799,11 +11590,81 @@ 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)"
+  },
+  // placement / entitlement rule → objective (BL-0176, ruling D-15): the
+  // optional `objective` field references an `objectives[]` entity by handle.
+  // Same §5.9 dangling-reference family and severity.
+  "VAL-OBJ-01": {
+    id: "VAL-OBJ-01",
+    severity: "error_launch",
+    message: "This placement or entitlement rule names an objective that does not exist.",
+    specRef: "config-validation.md \xA75.9 (BL-0176)"
+  },
+  // 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) {
@@ -10823,6 +11684,168 @@ function categoryBucket(category) {
   if (normalized.includes("retention") || normalized.includes("winback") || normalized.includes("churn")) return 4;
   return 99;
 }
+var HANDLE_PATTERN2 = /^[a-z0-9._]{1,100}$/;
+var BUILTIN_SEGMENT_HANDLE_PREFIX = "rt.";
+var BUILTIN_TRAIT_KEY_PREFIX = "rt_";
+var MAX_HANDLE_LENGTH = 100;
+function dimension(key2, name, legacyAbbr, values, opts = {}) {
+  const legacyPrefix = `seg:${legacyAbbr}:`;
+  return {
+    key: key2,
+    name,
+    traitKey: `${BUILTIN_TRAIT_KEY_PREFIX}${key2}`,
+    dimensionId: `${BUILTIN_SEGMENT_HANDLE_PREFIX}${key2}`,
+    vocabulary: opts.vocabulary ?? "closed",
+    values: values.map(([value, valueName, legacyValue]) => ({
+      value,
+      name: valueName,
+      legacyPickerId: `${legacyPrefix}${legacyValue ?? value}`
+    })),
+    ...opts.fallback !== void 0 ? { fallback: opts.fallback } : {},
+    legacyPrefix
+  };
+}
+var BUILTIN_DIMENSIONS = [
+  dimension("registration_state", "Registration State", "reg", [
+    ["unregistered", "Unregistered"],
+    ["registered", "Registered"]
+  ]),
+  dimension(
+    "activity_level",
+    "Activity State",
+    "act",
+    [
+      ["new", "New"],
+      ["high", "High Activity"],
+      ["medium", "Medium Activity"],
+      ["low", "Low Activity"],
+      ["inactive", "Inactive"]
+    ],
+    { fallback: "new" }
+  ),
+  dimension(
+    "subscription_state",
+    "Subscription State",
+    "sub",
+    [
+      ["none", "None"],
+      ["trial", "Trial"],
+      ["paid", "Paid"],
+      ["cancelled", "Cancelled"]
+    ],
+    { fallback: "none" }
+  ),
+  dimension(
+    "trial_type",
+    "Trial Type",
+    "trial",
+    [
+      ["none", "Not in trial"],
+      ["free_trial", "Free trial", "free"],
+      ["reverse_trial", "Reverse trial", "reverse"]
+    ],
+    { fallback: "none" }
+  ),
+  dimension("seat_type", "Seat Type", "seat", [], { vocabulary: "seat_type" }),
+  dimension("buyer_role", "Buyer Role", "role", [
+    ["buyer", "Buyer"],
+    ["non_buyer", "Non-buyer"]
+  ]),
+  dimension(
+    "email_type",
+    "Email Type",
+    "email",
+    [
+      ["business", "Business email"],
+      ["personal", "Personal email"],
+      ["unknown", "Unknown"]
+    ],
+    { fallback: "unknown" }
+  ),
+  dimension(
+    "billing_health",
+    "Billing Health",
+    "bill",
+    [
+      ["no_billing", "No billing", "none"],
+      ["good_standing", "Good standing", "good"],
+      ["trial_payment_method_attached", "Trial \u2014 payment method attached", "trial_pm"],
+      ["payment_method_missing", "Payment method missing", "pm_missing"],
+      ["payment_failed", "Payment failed", "failed"],
+      ["payment_overdue", "Payment overdue", "overdue"],
+      ["cancelled", "Cancelled"]
+    ],
+    { fallback: "no_billing" }
+  ),
+  dimension("region", "Country / Region", "geo", [
+    ["us_canada", "US / Canada"],
+    ["europe", "Europe"],
+    ["rest_of_world", "Rest of World", "row"]
+  ]),
+  dimension(
+    "device_type",
+    "Device Type",
+    "dev",
+    [
+      ["desktop", "Desktop"],
+      ["mobile", "Mobile"],
+      ["tablet", "Tablet"],
+      ["unknown", "Unknown"]
+    ],
+    { fallback: "unknown" }
+  )
+];
+var BY_KEY = new Map(
+  BUILTIN_DIMENSIONS.map((d) => [d.key, d])
+);
+function isBuiltinDimensionKey(key2) {
+  return BY_KEY.has(key2);
+}
+function getBuiltinDimension(key2) {
+  const found = BY_KEY.get(key2);
+  if (!found) throw new Error(`Unknown built-in dimension '${key2}'`);
+  return found;
+}
+function builtinSegmentHandle(key2, value) {
+  return `${BUILTIN_SEGMENT_HANDLE_PREFIX}${key2}.${value}`;
+}
+function isReservedSegmentHandle(handle) {
+  return handle.startsWith(BUILTIN_SEGMENT_HANDLE_PREFIX);
+}
+function isBuiltinDimensionValue(key2, value) {
+  const dim = getBuiltinDimension(key2);
+  if (dim.vocabulary === "closed") return dim.values.some((v) => v.value === value);
+  return HANDLE_PATTERN2.test(value) && builtinSegmentHandle(key2, value).length <= MAX_HANDLE_LENGTH;
+}
+function parseBuiltinSegmentHandle(handle) {
+  if (!isReservedSegmentHandle(handle)) return void 0;
+  const rest = handle.slice(BUILTIN_SEGMENT_HANDLE_PREFIX.length);
+  const dot = rest.indexOf(".");
+  if (dot <= 0) return void 0;
+  const key2 = rest.slice(0, dot);
+  const value = rest.slice(dot + 1);
+  if (!isBuiltinDimensionKey(key2) || !isBuiltinDimensionValue(key2, value)) return void 0;
+  return { key: key2, value };
+}
+function isGeneratedBuiltinSegment(segment) {
+  if (typeof segment.handle !== "string") return false;
+  const parsed = parseBuiltinSegmentHandle(segment.handle);
+  if (!parsed) return false;
+  const dim = getBuiltinDimension(parsed.key);
+  if (segment.dimension_id !== dim.dimensionId) return false;
+  if (segment.experiment_handle !== void 0 && segment.experiment_handle !== null) return false;
+  const predicates = segment.predicates;
+  if (!Array.isArray(predicates) || predicates.length !== 1) return false;
+  const [p] = predicates;
+  if (!p || typeof p !== "object") return false;
+  const { field, operator, value } = p;
+  return field === dim.traitKey && operator === "eq" && value === parsed.value;
+}
+var LEGACY_BY_ID = new Map(
+  BUILTIN_DIMENSIONS.flatMap(
+    (d) => d.values.map((v) => [v.legacyPickerId, builtinSegmentHandle(d.key, v.value)])
+  )
+);
 function runSemanticRules(graph, opts = {}) {
   return [
     ...checkRuleOverlaps(graph),
@@ -10832,28 +11855,321 @@ function runSemanticRules(graph, opts = {}) {
     ...checkPlacementAuthoring(graph),
     ...checkTrialRuleWidestAudience(graph),
     ...checkSegmentExperimentRefs(graph),
-    ...checkExperimentMetricRefs(graph, opts.knownMetricIds)
+    ...checkReservedSegmentHandles(graph),
+    ...checkHandleUniqueness(graph),
+    ...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),
+    ...checkObjectiveRefs(graph)
   ];
 }
+var OBJECTIVE_REFERRERS = [
+  { table: "placements", objectType: "placement", label: "Placement", studio: "placements" },
+  { table: "entitlement_rules", objectType: "entitlement_rule", label: "Entitlement rule", studio: "plans-entitlements" }
+];
+function checkObjectiveRefs(graph) {
+  const known = referenceNamespace(graph, "objectives", "handle");
+  if (!known) return [];
+  const findings = [];
+  for (const referrer of OBJECTIVE_REFERRERS) {
+    for (const [index, row] of (graph[referrer.table] ?? []).entries()) {
+      const value = row.objective;
+      if (typeof value !== "string" || value.length === 0 || known.has(value)) continue;
+      const id = String(row.handle ?? row.id ?? "");
+      findings.push(
+        finding(
+          "VAL-OBJ-01",
+          {
+            object_type: referrer.objectType,
+            object_id: id,
+            field: "objective",
+            path: [referrer.table, index, "objective"],
+            studio: referrer.studio
+          },
+          {
+            message: `${referrer.label} '${id || "unnamed"}' names objective '${value}', which no objective declares.`,
+            detail: "An objective reference must be an objective's handle, not its config id. A reference that matches nothing drops this object out of the objective slice, so its results report under no objective." + knownHandlesHint(known, "objective handles")
+          }
+        )
+      );
+    }
+  }
+  return findings;
+}
+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 : {};
@@ -10996,6 +12312,90 @@ function checkSegmentExperimentRefs(graph) {
   }
   return findings;
 }
+function checkReservedSegmentHandles(graph) {
+  const findings = [];
+  for (const table2 of ["segments", "segment_values"]) {
+    for (const [index, segment] of (graph[table2] ?? []).entries()) {
+      const handle = segment.handle;
+      if (typeof handle !== "string" || !isReservedSegmentHandle(handle)) continue;
+      if (table2 === "segments" && isGeneratedBuiltinSegment(segment)) continue;
+      findings.push(
+        finding(
+          "VAL-SEG-02",
+          {
+            object_type: "segment",
+            object_id: handle,
+            field: "handle",
+            path: [table2, index, "handle"],
+            studio: "targeting"
+          },
+          {
+            message: `Segment '${handle}' uses the reserved '${BUILTIN_SEGMENT_HANDLE_PREFIX}' handle prefix.`,
+            detail: `Handles starting with '${BUILTIN_SEGMENT_HANDLE_PREFIX}' are reserved for RevTurbine's built-in segments, which are generated at export. Rename the segment; to target a built-in value, select it from the built-in dimension instead.`
+          }
+        )
+      );
+    }
+  }
+  return findings;
+}
+var HANDLE_UNIQUENESS_COLLECTIONS = [
+  { table: "plans", handleFields: ["unique_handle", "handle"], objectType: "plan", studio: "plans-entitlements" },
+  { table: "addons", handleFields: ["unique_handle", "handle"], objectType: "addon", studio: "plans-entitlements" },
+  {
+    table: "entitlements",
+    handleFields: ["unique_handle", "handle"],
+    objectType: "entitlement",
+    studio: "plans-entitlements"
+  },
+  {
+    table: "segments",
+    handleFields: ["handle"],
+    objectType: "segment",
+    studio: "targeting",
+    exempt: (row) => isGeneratedBuiltinSegment(row)
+  },
+  { table: "segment_values", handleFields: ["handle"], objectType: "segment", studio: "targeting" },
+  { table: "seat_types", handleFields: ["handle"], objectType: "seat_type", studio: "plans-entitlements" }
+];
+function checkHandleUniqueness(graph) {
+  const findings = [];
+  for (const { table: table2, handleFields, objectType, studio, exempt } of HANDLE_UNIQUENESS_COLLECTIONS) {
+    const rows = graph[table2];
+    if (!rows?.length) continue;
+    const seen = /* @__PURE__ */ new Set();
+    for (const [index, row] of rows.entries()) {
+      if (row.is_current === false) continue;
+      if (exempt?.(row)) continue;
+      const field = firstStringField(row, handleFields);
+      if (!field) continue;
+      const tenant = String(row.tenant_id ?? "");
+      const environment = String(row.environment_id ?? "");
+      const key2 = `${tenant}::${environment}::${field.value}`;
+      if (!seen.has(key2)) {
+        seen.add(key2);
+        continue;
+      }
+      const id = String(row.id ?? field.value);
+      findings.push(
+        finding(
+          "VAL-UNI-01",
+          {
+            object_type: objectType,
+            object_id: id,
+            field: field.field,
+            path: [table2, index, field.field],
+            studio
+          },
+          {
+            detail: `Handle '${field.value}' is used by more than one ${objectType} \u2014 handles must be unique within a ${objectType} collection.`
+          }
+        )
+      );
+    }
+  }
+  return findings;
+}
 function checkExperimentMetricRefs(graph, knownMetricIds) {
   if (!knownMetricIds) return [];
   const findings = [];
@@ -11244,7 +12644,6 @@ function evaluate(graph, opts = {}) {
   if (!opts.focus) return findings;
   return findings.map((f) => spotlights(f, opts.focus) ? { ...f, spotlight: true } : f);
 }
-var HANDLE_PATTERN2 = /^[a-z0-9._]{1,100}$/;
 var SchemaPersistence2 = {
   Persisted: "persisted",
   Transient: "transient"
@@ -11506,6 +12905,8 @@ var CtaActionTypeSchema2 = z39.enum([
   "snooze",
   "custom"
 ]).meta({ id: "CtaActionType", "x-revturbine-schema-persistence": Transient30, "x-revturbine-schema-exposure": External14 });
+var ObjectiveField2 = HandleField2.optional();
+var NullableObjectiveField2 = z39.string().min(1).max(100).nullable().optional();
 var IdentityKind2 = {
   /** Author-given, human-meaningful handle (plans, entitlements, segments, …). */
   Named: "named",
@@ -11711,6 +13112,16 @@ 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). A reference by handle to an
+  // `objectives[]` entity (D-15; VAL-OBJ-01). 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.
+  // Nullable on the persisted entity so an editor can CLEAR the reference
+  // (a PATCH merges, so omission keeps the old value); the portable
+  // projection stays optional-only and omits it when unset.
+  objective: NullableObjectiveField2.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),
@@ -12129,6 +13540,39 @@ var TrialInstanceSchema2 = IdField2.merge(TimestampFields2).merge(TenantIdField2
   usage_limit_value: z72.number().int().min(1).optional().meta(Unrestricted33),
   converted_at: NullableDatetimeField2.meta(Unrestricted33),
   cancelled_at: NullableDatetimeField2.meta(Unrestricted33),
+  /**
+   * Stable identity of the trial EPISODE this row represents
+   * (BL-0247 / plan 276 TASK-12). A customer can run more than one
+   * trial, and a subscription can re-enter `trialing`, so the
+   * (customer, subscription) pair does not name an occurrence. The
+   * billing lane already discriminates an episode by the Stripe
+   * subscription id plus its `trial_start`; this column persists
+   * that same discriminator so a fact about one episode can be
+   * written to exactly that episode's row.
+   *
+   * Nullable: rows created before the column existed, and rows
+   * created by paths that have no Stripe evidence to mint an id
+   * from, carry NULL. NULL means "this episode has no first-class
+   * identity", never "episode zero" — and Postgres treats NULLs as
+   * distinct, so the composite UNIQUE below does not collapse them.
+   */
+  trial_episode_id: z72.string().min(1).nullable().optional().meta(Unrestricted33),
+  /**
+   * The Stripe subscription this episode belongs to — the binding
+   * that lets a Stripe fact resolve one episode without guessing
+   * (BL-0245 carried this in `metadata.stripe_subscription_id`).
+   * Nullable because a trial need not originate from Stripe at all.
+   */
+  stripe_subscription_id: z72.string().min(1).nullable().optional().meta(Unrestricted33),
+  /**
+   * The EVIDENCED end of the episode: the moment a provider fact
+   * said the trial actually stopped. Distinct from `expires_at`,
+   * which is the SCHEDULED end and must stay distinguishable
+   * (plan 276 R-1 — no clock authority; an elapsed `expires_at`
+   * with no fact behind it is not an end). Null until a fact
+   * proves one.
+   */
+  actual_end_at: NullableDatetimeField2.meta(Unrestricted33),
   metadata: MetadataField2.meta(Unrestricted33)
 }).meta(
   { id: "TrialInstance", "x-revturbine-schema-persistence": Persisted32, "x-revturbine-schema-exposure": Internal32 }
@@ -12331,7 +13775,12 @@ var trialPaths2 = {
       summary: "List trial instances",
       tags: ["trials"],
       responses: { "200": { description: "Trial instance list", content: { "application/json": { schema: ListEnvelope2(TrialInstanceSchema2) } } } },
-      "x-revturbine-operation": { exposure: "internal", resource: "trial-instances", persistence: { table: "trialInstances", mode: "list" } }
+      // One row per trial EPISODE (BL-0247 / plan 276 TASK-12). This is the
+      // ON CONFLICT target the Stripe binding writer upserts against, so a
+      // re-delivered `customer.subscription.*` event updates the episode it
+      // already created instead of minting a duplicate. NULL episode ids are
+      // distinct in Postgres, so pre-existing and non-Stripe rows are unaffected.
+      "x-revturbine-operation": { exposure: "internal", resource: "trial-instances", persistence: { table: "trialInstances", mode: "list", uniqueBy: ["tenant_id", "customer_id", "trial_episode_id"] } }
     })
   },
   "/api/trials/instances/{instanceId}": {
@@ -12885,6 +14334,16 @@ var PersonalizationTokenSchema2 = IdField2.merge(TimestampFields2).merge(TenantI
   { id: "PersonalizationToken", "x-revturbine-schema-persistence": Persisted52, "x-revturbine-schema-exposure": Internal42, ...PENDING_PLAYBOOK_FACETS22, ...namedIdentity2() }
 );
 var PersonalizationTokenAnchorSchema2 = makeAnchor2("PersonalizationTokenAnchor");
+var ObjectiveSchema2 = IdField2.merge(TimestampFields2).merge(TenantIdField2).merge(AnchorFields2).merge(VersionFields2).extend({
+  anchor_id: z92.string().min(1).meta({ ...Unrestricted52, readOnly: true }),
+  handle: HandleField2.meta(Unrestricted52),
+  name: NameField2.meta(Unrestricted52),
+  description: DescriptionField2.meta(Unrestricted52),
+  metadata: MetadataField2.meta(Unrestricted52)
+}).meta(
+  { id: "Objective", "x-revturbine-schema-persistence": Persisted52, "x-revturbine-schema-exposure": Internal42, ...PLAYBOOK_AUTHORING_FACETS22, ...namedIdentity2() }
+);
+var ObjectiveAnchorSchema2 = makeAnchor2("ObjectiveAnchor");
 var OnboardingStateSchema2 = z92.enum(["not_started", "started", "details_submitted", "charges_enabled", "activated", "deauthorized"]).meta({ id: "OnboardingState", "x-revturbine-schema-persistence": Transient52, "x-revturbine-schema-exposure": Internal42 });
 var StripeIntegrationConfigSchema2 = IdField2.merge(TimestampFields2).merge(TenantIdField2).merge(AnchorFields2).merge(VersionFields2).extend({
   handle: HandleField2.meta({ ...Unrestricted52, readOnly: true }),
@@ -13202,7 +14661,9 @@ var RevTurbineConfigEntitlementRulesItemSchema2 = z92.object({
   }).shape,
   current_usage: z92.number().default(0).meta(Unrestricted52),
   /** How usage is partitioned across the identity hierarchy. */
-  allocation: UsageAllocationSchema2.optional().meta(Unrestricted52)
+  allocation: UsageAllocationSchema2.optional().meta(Unrestricted52),
+  /** Optional business objective, by `objectives[].handle` (VAL-OBJ-01). Config-only. */
+  objective: ObjectiveField2.meta(Unrestricted52)
 }).meta(
   { id: "RevTurbineConfigEntitlementRulesItem", "x-revturbine-schema-persistence": Transient52, "x-revturbine-schema-exposure": External42, ...PLAYBOOK_SDK_FACETS42 }
 );
@@ -13298,6 +14759,13 @@ var RevTurbineConfigPersonalizationTokensItemSchema2 = z92.object({
 }).meta(
   { id: "RevTurbineConfigPersonalizationTokensItem", "x-revturbine-schema-persistence": Transient52, "x-revturbine-schema-exposure": External42, ...PLAYBOOK_SDK_FACETS42 }
 );
+var RevTurbineConfigObjectivesItemSchema2 = z92.object({
+  handle: HandleField2.meta(Unrestricted52),
+  name: NameField2.meta(Unrestricted52),
+  description: DescriptionField2.meta(Unrestricted52)
+}).meta(
+  { id: "RevTurbineConfigObjectivesItem", "x-revturbine-schema-persistence": Transient52, "x-revturbine-schema-exposure": External42, ...PLAYBOOK_AUTHORING_FACETS22 }
+);
 var MessageBlockContentSchema2 = z92.object({
   header: z92.string().optional().meta(Unrestricted52),
   body: z92.string().optional().meta(Unrestricted52),
@@ -13401,7 +14869,9 @@ var RevTurbineConfigPlacementItemSchema2 = z92.object({
   category: RevTurbineConfigPlacementCategorySchema2.meta(Unrestricted52),
   trigger: RevTurbineConfigPlacementTriggerSchema2.meta(Unrestricted52),
   payloads: z92.array(RevTurbineConfigStudioPayloadSchema2).meta(Unrestricted52),
-  order: z92.number().int().min(0).meta(Unrestricted52)
+  order: z92.number().int().min(0).meta(Unrestricted52),
+  /** Optional business objective, by `objectives[].handle` (VAL-OBJ-01). Config-only. */
+  objective: ObjectiveField2.meta(Unrestricted52)
 }).meta(
   { id: "RevTurbineConfigPlacementItem", "x-revturbine-schema-persistence": Transient52, "x-revturbine-schema-exposure": External42, ...PLAYBOOK_SDK_FACETS42 }
 );
@@ -13495,6 +14965,14 @@ var PlaybookBodySchema2 = z92.object({
    */
   free_trial_rules: z92.array(RevTurbineConfigFreeTrialRuleItemSchema2).optional().meta({ ...Unrestricted52, ...PLAYBOOK_AUTHORING_FACETS22 }),
   reverse_trial_rules: z92.array(RevTurbineConfigReverseTrialRuleItemSchema2).optional().meta({ ...Unrestricted52, ...PLAYBOOK_AUTHORING_FACETS22 }),
+  /**
+   * Business objectives (BL-0176 / BL-0178, ruling D-15). Optional so every
+   * Playbook authored before objectives existed still parses. Placements and
+   * entitlement rules reference an entry by `handle` through their optional
+   * `objective` field. Authoring-only: no runtime decision reads it, so it is
+   * not an SDK input and never lowers into the IR.
+   */
+  objectives: z92.array(RevTurbineConfigObjectivesItemSchema2).optional().meta({ ...Unrestricted52, ...PLAYBOOK_AUTHORING_FACETS22 }),
   // Plan / add-on variation prices carried by handle (plan 118 TASK-16). These
   // live on the legacy schema (not just the canonical Playbook body) so that a
   // legacy `version`-shaped config — the shape the demo-data configs and the
@@ -13760,6 +15238,56 @@ var configPaths2 = {
       "x-revturbine-operation": { exposure: "internal", resource: "personalization-tokens", persistence: { table: "personalizationTokenVersions", mode: "delete" } }
     })
   },
+  "/api/objective-anchors": {
+    get: operation2({
+      operationId: "listObjectiveAnchors",
+      requestParams: { query: ListQueryParamsSchema2 },
+      summary: "List objective anchors (identity registry)",
+      tags: ["config"],
+      responses: {
+        "200": { description: "Objective anchor list", content: { "application/json": { schema: ListEnvelope2(ObjectiveAnchorSchema2) } } },
+        default: { description: "Error response", content: { "application/json": { schema: ErrorEnvelope2 } } }
+      },
+      "x-revturbine-operation": { exposure: "internal", resource: "objective-anchors", persistence: { table: "objectives", mode: "list" } }
+    })
+  },
+  "/api/config/objectives": {
+    get: operation2({
+      operationId: "listObjectives",
+      requestParams: { query: ListQueryParamsSchema2 },
+      summary: "List objectives",
+      tags: ["config"],
+      responses: { "200": { description: "Objective list", content: { "application/json": { schema: ListEnvelope2(ObjectiveSchema2) } } } },
+      "x-revturbine-operation": { exposure: "internal", resource: "objectives", persistence: { table: "objectiveVersions", mode: "list" } }
+    }),
+    post: operation2({
+      operationId: "createObjective",
+      summary: "Create objective",
+      tags: ["config"],
+      requestBody: { required: true, content: { "application/json": { schema: toCreateSchema2(ObjectiveSchema2) } } },
+      responses: { "201": { description: "Created", content: { "application/json": { schema: ObjectiveSchema2 } } } },
+      "x-revturbine-operation": { exposure: "internal", resource: "objectives", persistence: { table: "objectiveVersions", mode: "create" } }
+    })
+  },
+  "/api/config/objectives/{id}": {
+    patch: operation2({
+      operationId: "updateObjective",
+      requestParams: { path: z92.object({ id: z92.string() }) },
+      summary: "Update objective",
+      tags: ["config"],
+      requestBody: { required: true, content: { "application/json": { schema: ObjectiveSchema2.partial() } } },
+      responses: { "200": { description: "Updated", content: { "application/json": { schema: ObjectiveSchema2 } } } },
+      "x-revturbine-operation": { exposure: "internal", resource: "objectives", persistence: { table: "objectiveVersions", mode: "update" } }
+    }),
+    delete: operation2({
+      operationId: "deleteObjective",
+      requestParams: { path: z92.object({ id: z92.string() }) },
+      summary: "Delete objective",
+      tags: ["config"],
+      responses: { "204": { description: "Deleted" } },
+      "x-revturbine-operation": { exposure: "internal", resource: "objectives", persistence: { table: "objectiveVersions", mode: "delete" } }
+    })
+  },
   "/api/config/stripe": {
     get: operation2({
       operationId: "getStripeIntegrationConfig",
@@ -13934,7 +15462,7 @@ function repairDeprecatedFields(config, schema = PlaybookObjectSchema2) {
 }
 
 // src/schema/version.ts
-var SCHEMA_VERSION = "0.1.325";
+var SCHEMA_VERSION = "0.1.362";
 
 // src/lib/credentials.ts
 import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
@@ -14223,7 +15751,9 @@ var COLLECTIONS = [
   "surface_templates",
   "placements",
   "free_trial_rules",
-  "reverse_trial_rules"
+  "reverse_trial_rules",
+  // BL-0176 / BL-0178: first-class objectives, keyed by handle.
+  "objectives"
 ];
 function keyOf(item) {
   return item?.handle ?? item?.unique_handle ?? item?.name ?? item?.id ?? JSON.stringify(item);
@@ -14283,7 +15813,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`, {