@revturbine/cli 0.19.4 → 0.19.5

package/dist/cli.js

@@ -2354,6 +2354,7 @@ var CtaActionTypeSchema = z2.enum([
   "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",
@@ -3001,10 +3002,14 @@ var EntitlementRuleSchema = IdField.merge(TimestampFields).merge(TenantIdField).
   visibility: RuleVisibilitySchema.default("public").meta(Unrestricted3),
   // Business objective this rule monetizes for — the analytics `objective`
   // slice, which resolves `rule_handle → objective` through a configuration
-  // snapshot (BL-0065 / worksheet G4). Config-only, and deliberately NOT part
-  // of the minted identity below: an objective relabel is a behaviour-only
-  // edit that coalesces onto the same rule, not a new rule scope.
-  objective: ObjectiveField.meta(Unrestricted3),
+  // 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),
@@ -3360,11 +3365,15 @@ var PlacementSchema = IdField.merge(TimestampFields).merge(TenantIdField).merge(
   category: PlacementCategorySchema.meta(Unrestricted4),
   // Business objective this placement monetizes for — the analytics
   // `objective` slice, which resolves `placement_id → objective` through a
-  // configuration snapshot (BL-0065 / worksheet G4). Config-only: nothing in
-  // the runtime decision reads it, so it is absent from the portable
-  // RevTurbineConfig projection and the compiled payload. Free handle; see
-  // `ObjectiveField` for why the value set is not enumerated here.
-  objective: ObjectiveField.meta(Unrestricted4),
+  // 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),
@@ -3844,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),
@@ -3906,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
@@ -3998,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 }),
@@ -4006,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 }
 );
@@ -4878,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",
@@ -5078,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),
@@ -5098,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)
@@ -5732,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),
@@ -5869,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 },
@@ -5879,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
@@ -5998,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"
@@ -6079,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" },
@@ -6089,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.
@@ -6467,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),
@@ -6495,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),
@@ -6525,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).
    *
@@ -6540,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
@@ -6791,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).
    *
@@ -7506,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 }
@@ -7708,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}": {
@@ -8715,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 }),
@@ -9032,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 }
 );
@@ -9128,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),
@@ -9231,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 }
 );
@@ -9325,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
@@ -9591,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",
@@ -10876,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",
@@ -10883,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": {
@@ -10970,6 +11635,15 @@ var CATALOG = {
     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
@@ -11010,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),
@@ -11019,6 +11855,8 @@ function runSemanticRules(graph, opts = {}) {
     ...checkPlacementAuthoring(graph),
     ...checkTrialRuleWidestAudience(graph),
     ...checkSegmentExperimentRefs(graph),
+    ...checkReservedSegmentHandles(graph),
+    ...checkHandleUniqueness(graph),
     ...checkExperimentMetricRefs(graph, opts.knownMetricIds),
     ...checkDanglingReferences(graph)
   ];
@@ -11054,9 +11892,43 @@ function checkDanglingReferences(graph) {
     ...checkTrialPlanRefs(graph),
     ...checkEntitlementRuleTargetRefs(graph),
     ...checkEntitlementRuleEntitlementRefs(graph),
-    ...checkPayloadSegmentChipRefs(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 [];
@@ -11440,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 = [];
@@ -11688,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"
@@ -11951,6 +12906,7 @@ var CtaActionTypeSchema2 = z39.enum([
   "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",
@@ -12158,10 +13114,14 @@ var EntitlementRuleSchema2 = IdField2.merge(TimestampFields2).merge(TenantIdFiel
   visibility: RuleVisibilitySchema2.default("public").meta(Unrestricted210),
   // Business objective this rule monetizes for — the analytics `objective`
   // slice, which resolves `rule_handle → objective` through a configuration
-  // snapshot (BL-0065 / worksheet G4). Config-only, and deliberately NOT part
-  // of the minted identity below: an objective relabel is a behaviour-only
-  // edit that coalesces onto the same rule, not a new rule scope.
-  objective: ObjectiveField2.meta(Unrestricted210),
+  // 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),
@@ -12580,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 }
@@ -12782,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}": {
@@ -13336,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 }),
@@ -13653,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 }
 );
@@ -13749,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),
@@ -13852,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 }
 );
@@ -13946,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
@@ -14211,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",
@@ -14385,7 +15462,7 @@ function repairDeprecatedFields(config, schema = PlaybookObjectSchema2) {
 }
 
 // src/schema/version.ts
-var SCHEMA_VERSION = "0.1.343";
+var SCHEMA_VERSION = "0.1.362";
 
 // src/lib/credentials.ts
 import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
@@ -14674,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);