@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.10

package/lib/models/date-literal.js

@@ -0,0 +1,1164 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/**
+ * The 52 date literals supported by the ISV DateLiteral.cls (after CLI-3419).
+ * These are the ONLY literals the CLI should generate — they correspond 1:1
+ * to the constants in the ISV product's DateLiteral class.
+ *
+ * Pre-CLI-3419 vocabulary was 14 entries (year-tier cap of 4 + 4 base
+ * non-year-tier + 2 span). CLI-3419 raises the cap to 10 across all
+ * non-span tiers, extending the cascade vocabulary to N_X_AGO:2..9 for
+ * day/week/month/quarter and N_YEARS_AGO:4..9 for year.
+ */
+export const SUPPORTED_DATE_LITERALS = [
+    // Day tier
+    'TODAY',
+    'YESTERDAY',
+    'N_DAYS_AGO:2',
+    'N_DAYS_AGO:3',
+    'N_DAYS_AGO:4',
+    'N_DAYS_AGO:5',
+    'N_DAYS_AGO:6',
+    'N_DAYS_AGO:7',
+    'N_DAYS_AGO:8',
+    'N_DAYS_AGO:9',
+    // Week tier
+    'THIS_WEEK',
+    'LAST_WEEK',
+    'N_WEEKS_AGO:2',
+    'N_WEEKS_AGO:3',
+    'N_WEEKS_AGO:4',
+    'N_WEEKS_AGO:5',
+    'N_WEEKS_AGO:6',
+    'N_WEEKS_AGO:7',
+    'N_WEEKS_AGO:8',
+    'N_WEEKS_AGO:9',
+    // Month tier
+    'THIS_MONTH',
+    'LAST_MONTH',
+    'N_MONTHS_AGO:2',
+    'N_MONTHS_AGO:3',
+    'N_MONTHS_AGO:4',
+    'N_MONTHS_AGO:5',
+    'N_MONTHS_AGO:6',
+    'N_MONTHS_AGO:7',
+    'N_MONTHS_AGO:8',
+    'N_MONTHS_AGO:9',
+    // Quarter tier
+    'THIS_QUARTER',
+    'LAST_QUARTER',
+    'N_QUARTERS_AGO:2',
+    'N_QUARTERS_AGO:3',
+    'N_QUARTERS_AGO:4',
+    'N_QUARTERS_AGO:5',
+    'N_QUARTERS_AGO:6',
+    'N_QUARTERS_AGO:7',
+    'N_QUARTERS_AGO:8',
+    'N_QUARTERS_AGO:9',
+    // Year tier
+    'THIS_YEAR',
+    'LAST_YEAR',
+    'N_YEARS_AGO:2',
+    'N_YEARS_AGO:3',
+    'N_YEARS_AGO:4',
+    'N_YEARS_AGO:5',
+    'N_YEARS_AGO:6',
+    'N_YEARS_AGO:7',
+    'N_YEARS_AGO:8',
+    'N_YEARS_AGO:9',
+    // Span tier (out of scope for cascade — single-period aggregate)
+    'LAST_N_YEARS:2',
+    'LAST_N_YEARS:3',
+];
+/**
+ * Customer-facing labels for each date literal.
+ * Used in definition names, descriptions, and time category display.
+ *
+ * Word-form convention for N≥2 mirrors the existing year-tier labels
+ * ("Two Years Ago", "Three Years Ago") — see CLI-3419 Decision #3.
+ */
+export const DATE_LITERAL_LABELS = {
+    // Day tier
+    TODAY: 'Today',
+    YESTERDAY: 'Yesterday',
+    'N_DAYS_AGO:2': 'Two Days Ago',
+    'N_DAYS_AGO:3': 'Three Days Ago',
+    'N_DAYS_AGO:4': 'Four Days Ago',
+    'N_DAYS_AGO:5': 'Five Days Ago',
+    'N_DAYS_AGO:6': 'Six Days Ago',
+    'N_DAYS_AGO:7': 'Seven Days Ago',
+    'N_DAYS_AGO:8': 'Eight Days Ago',
+    'N_DAYS_AGO:9': 'Nine Days Ago',
+    // Week tier
+    THIS_WEEK: 'This Week',
+    LAST_WEEK: 'Last Week',
+    'N_WEEKS_AGO:2': 'Two Weeks Ago',
+    'N_WEEKS_AGO:3': 'Three Weeks Ago',
+    'N_WEEKS_AGO:4': 'Four Weeks Ago',
+    'N_WEEKS_AGO:5': 'Five Weeks Ago',
+    'N_WEEKS_AGO:6': 'Six Weeks Ago',
+    'N_WEEKS_AGO:7': 'Seven Weeks Ago',
+    'N_WEEKS_AGO:8': 'Eight Weeks Ago',
+    'N_WEEKS_AGO:9': 'Nine Weeks Ago',
+    // Month tier
+    THIS_MONTH: 'This Month',
+    LAST_MONTH: 'Last Month',
+    'N_MONTHS_AGO:2': 'Two Months Ago',
+    'N_MONTHS_AGO:3': 'Three Months Ago',
+    'N_MONTHS_AGO:4': 'Four Months Ago',
+    'N_MONTHS_AGO:5': 'Five Months Ago',
+    'N_MONTHS_AGO:6': 'Six Months Ago',
+    'N_MONTHS_AGO:7': 'Seven Months Ago',
+    'N_MONTHS_AGO:8': 'Eight Months Ago',
+    'N_MONTHS_AGO:9': 'Nine Months Ago',
+    // Quarter tier
+    THIS_QUARTER: 'This Quarter',
+    LAST_QUARTER: 'Last Quarter',
+    'N_QUARTERS_AGO:2': 'Two Quarters Ago',
+    'N_QUARTERS_AGO:3': 'Three Quarters Ago',
+    'N_QUARTERS_AGO:4': 'Four Quarters Ago',
+    'N_QUARTERS_AGO:5': 'Five Quarters Ago',
+    'N_QUARTERS_AGO:6': 'Six Quarters Ago',
+    'N_QUARTERS_AGO:7': 'Seven Quarters Ago',
+    'N_QUARTERS_AGO:8': 'Eight Quarters Ago',
+    'N_QUARTERS_AGO:9': 'Nine Quarters Ago',
+    // Year tier
+    THIS_YEAR: 'This Year',
+    LAST_YEAR: 'Last Year',
+    'N_YEARS_AGO:2': 'Two Years Ago',
+    'N_YEARS_AGO:3': 'Three Years Ago',
+    'N_YEARS_AGO:4': 'Four Years Ago',
+    'N_YEARS_AGO:5': 'Five Years Ago',
+    'N_YEARS_AGO:6': 'Six Years Ago',
+    'N_YEARS_AGO:7': 'Seven Years Ago',
+    'N_YEARS_AGO:8': 'Eight Years Ago',
+    'N_YEARS_AGO:9': 'Nine Years Ago',
+    // Span tier
+    'LAST_N_YEARS:2': 'Last Two Years',
+    'LAST_N_YEARS:3': 'Last Three Years',
+};
+/** Maps each literal to its tier */
+export const LITERAL_TIERS = {
+    // Day tier
+    TODAY: 'day',
+    YESTERDAY: 'day',
+    'N_DAYS_AGO:2': 'day',
+    'N_DAYS_AGO:3': 'day',
+    'N_DAYS_AGO:4': 'day',
+    'N_DAYS_AGO:5': 'day',
+    'N_DAYS_AGO:6': 'day',
+    'N_DAYS_AGO:7': 'day',
+    'N_DAYS_AGO:8': 'day',
+    'N_DAYS_AGO:9': 'day',
+    // Week tier
+    THIS_WEEK: 'week',
+    LAST_WEEK: 'week',
+    'N_WEEKS_AGO:2': 'week',
+    'N_WEEKS_AGO:3': 'week',
+    'N_WEEKS_AGO:4': 'week',
+    'N_WEEKS_AGO:5': 'week',
+    'N_WEEKS_AGO:6': 'week',
+    'N_WEEKS_AGO:7': 'week',
+    'N_WEEKS_AGO:8': 'week',
+    'N_WEEKS_AGO:9': 'week',
+    // Month tier
+    THIS_MONTH: 'month',
+    LAST_MONTH: 'month',
+    'N_MONTHS_AGO:2': 'month',
+    'N_MONTHS_AGO:3': 'month',
+    'N_MONTHS_AGO:4': 'month',
+    'N_MONTHS_AGO:5': 'month',
+    'N_MONTHS_AGO:6': 'month',
+    'N_MONTHS_AGO:7': 'month',
+    'N_MONTHS_AGO:8': 'month',
+    'N_MONTHS_AGO:9': 'month',
+    // Quarter tier
+    THIS_QUARTER: 'quarter',
+    LAST_QUARTER: 'quarter',
+    'N_QUARTERS_AGO:2': 'quarter',
+    'N_QUARTERS_AGO:3': 'quarter',
+    'N_QUARTERS_AGO:4': 'quarter',
+    'N_QUARTERS_AGO:5': 'quarter',
+    'N_QUARTERS_AGO:6': 'quarter',
+    'N_QUARTERS_AGO:7': 'quarter',
+    'N_QUARTERS_AGO:8': 'quarter',
+    'N_QUARTERS_AGO:9': 'quarter',
+    // Year tier
+    THIS_YEAR: 'year',
+    LAST_YEAR: 'year',
+    'N_YEARS_AGO:2': 'year',
+    'N_YEARS_AGO:3': 'year',
+    'N_YEARS_AGO:4': 'year',
+    'N_YEARS_AGO:5': 'year',
+    'N_YEARS_AGO:6': 'year',
+    'N_YEARS_AGO:7': 'year',
+    'N_YEARS_AGO:8': 'year',
+    'N_YEARS_AGO:9': 'year',
+    // Span tier (out of scope for cascade)
+    'LAST_N_YEARS:2': 'span',
+    'LAST_N_YEARS:3': 'span',
+};
+/**
+ * Maximum cascade depth per tier — interpreted as max absolute offset from
+ * the current period plus one (offsets 0..MAX-1 are valid).
+ *
+ * CLI-3419 raised the cap from 4 (year-tier only) to 10 across all non-span
+ * tiers. The cascade vocabulary now covers offsets 0..9 — labels "This X"
+ * through "Nine X Ago" — at every non-span tier. Span literals
+ * (LAST_N_YEARS:2/3) stay at depth 1 because they already aggregate multiple
+ * periods (AC4).
+ */
+export const TIER_MAX_DEPTH = {
+    year: 10,
+    quarter: 10,
+    month: 10,
+    week: 10,
+    day: 10,
+    span: 1,
+};
+/**
+ * Depth cascade arrays per literal.
+ *
+ * Starting from a given literal at depth 0, each subsequent depth level
+ * adds the next literal in the cascade. Cascades always move backward in time.
+ *
+ * Cap interpretation (CLI-3419): cap=10 means max absolute offset is 9.
+ * Each base's cascade contains the literals from its own offset down to the
+ * tier max. E.g., LAST_QUARTER (offset 1) cascade has 9 entries
+ * (offsets 1..9); N_QUARTERS_AGO:9 cascade has 1 entry.
+ *
+ * Examples:
+ * - THIS_YEAR with depth 3 → [THIS_YEAR, LAST_YEAR, N_YEARS_AGO:2]
+ * - THIS_QUARTER with depth 4 → [THIS_QUARTER, LAST_QUARTER, N_QUARTERS_AGO:2, N_QUARTERS_AGO:3]
+ */
+export const LITERAL_CASCADES = {
+    // Day tier (offsets 0..9 = TODAY, YESTERDAY, N_DAYS_AGO:2..9)
+    TODAY: [
+        'TODAY',
+        'YESTERDAY',
+        'N_DAYS_AGO:2',
+        'N_DAYS_AGO:3',
+        'N_DAYS_AGO:4',
+        'N_DAYS_AGO:5',
+        'N_DAYS_AGO:6',
+        'N_DAYS_AGO:7',
+        'N_DAYS_AGO:8',
+        'N_DAYS_AGO:9',
+    ],
+    YESTERDAY: [
+        'YESTERDAY',
+        'N_DAYS_AGO:2',
+        'N_DAYS_AGO:3',
+        'N_DAYS_AGO:4',
+        'N_DAYS_AGO:5',
+        'N_DAYS_AGO:6',
+        'N_DAYS_AGO:7',
+        'N_DAYS_AGO:8',
+        'N_DAYS_AGO:9',
+    ],
+    'N_DAYS_AGO:2': [
+        'N_DAYS_AGO:2',
+        'N_DAYS_AGO:3',
+        'N_DAYS_AGO:4',
+        'N_DAYS_AGO:5',
+        'N_DAYS_AGO:6',
+        'N_DAYS_AGO:7',
+        'N_DAYS_AGO:8',
+        'N_DAYS_AGO:9',
+    ],
+    'N_DAYS_AGO:3': [
+        'N_DAYS_AGO:3',
+        'N_DAYS_AGO:4',
+        'N_DAYS_AGO:5',
+        'N_DAYS_AGO:6',
+        'N_DAYS_AGO:7',
+        'N_DAYS_AGO:8',
+        'N_DAYS_AGO:9',
+    ],
+    'N_DAYS_AGO:4': ['N_DAYS_AGO:4', 'N_DAYS_AGO:5', 'N_DAYS_AGO:6', 'N_DAYS_AGO:7', 'N_DAYS_AGO:8', 'N_DAYS_AGO:9'],
+    'N_DAYS_AGO:5': ['N_DAYS_AGO:5', 'N_DAYS_AGO:6', 'N_DAYS_AGO:7', 'N_DAYS_AGO:8', 'N_DAYS_AGO:9'],
+    'N_DAYS_AGO:6': ['N_DAYS_AGO:6', 'N_DAYS_AGO:7', 'N_DAYS_AGO:8', 'N_DAYS_AGO:9'],
+    'N_DAYS_AGO:7': ['N_DAYS_AGO:7', 'N_DAYS_AGO:8', 'N_DAYS_AGO:9'],
+    'N_DAYS_AGO:8': ['N_DAYS_AGO:8', 'N_DAYS_AGO:9'],
+    'N_DAYS_AGO:9': ['N_DAYS_AGO:9'],
+    // Week tier (offsets 0..9 = THIS_WEEK, LAST_WEEK, N_WEEKS_AGO:2..9)
+    THIS_WEEK: [
+        'THIS_WEEK',
+        'LAST_WEEK',
+        'N_WEEKS_AGO:2',
+        'N_WEEKS_AGO:3',
+        'N_WEEKS_AGO:4',
+        'N_WEEKS_AGO:5',
+        'N_WEEKS_AGO:6',
+        'N_WEEKS_AGO:7',
+        'N_WEEKS_AGO:8',
+        'N_WEEKS_AGO:9',
+    ],
+    LAST_WEEK: [
+        'LAST_WEEK',
+        'N_WEEKS_AGO:2',
+        'N_WEEKS_AGO:3',
+        'N_WEEKS_AGO:4',
+        'N_WEEKS_AGO:5',
+        'N_WEEKS_AGO:6',
+        'N_WEEKS_AGO:7',
+        'N_WEEKS_AGO:8',
+        'N_WEEKS_AGO:9',
+    ],
+    'N_WEEKS_AGO:2': [
+        'N_WEEKS_AGO:2',
+        'N_WEEKS_AGO:3',
+        'N_WEEKS_AGO:4',
+        'N_WEEKS_AGO:5',
+        'N_WEEKS_AGO:6',
+        'N_WEEKS_AGO:7',
+        'N_WEEKS_AGO:8',
+        'N_WEEKS_AGO:9',
+    ],
+    'N_WEEKS_AGO:3': [
+        'N_WEEKS_AGO:3',
+        'N_WEEKS_AGO:4',
+        'N_WEEKS_AGO:5',
+        'N_WEEKS_AGO:6',
+        'N_WEEKS_AGO:7',
+        'N_WEEKS_AGO:8',
+        'N_WEEKS_AGO:9',
+    ],
+    'N_WEEKS_AGO:4': [
+        'N_WEEKS_AGO:4',
+        'N_WEEKS_AGO:5',
+        'N_WEEKS_AGO:6',
+        'N_WEEKS_AGO:7',
+        'N_WEEKS_AGO:8',
+        'N_WEEKS_AGO:9',
+    ],
+    'N_WEEKS_AGO:5': ['N_WEEKS_AGO:5', 'N_WEEKS_AGO:6', 'N_WEEKS_AGO:7', 'N_WEEKS_AGO:8', 'N_WEEKS_AGO:9'],
+    'N_WEEKS_AGO:6': ['N_WEEKS_AGO:6', 'N_WEEKS_AGO:7', 'N_WEEKS_AGO:8', 'N_WEEKS_AGO:9'],
+    'N_WEEKS_AGO:7': ['N_WEEKS_AGO:7', 'N_WEEKS_AGO:8', 'N_WEEKS_AGO:9'],
+    'N_WEEKS_AGO:8': ['N_WEEKS_AGO:8', 'N_WEEKS_AGO:9'],
+    'N_WEEKS_AGO:9': ['N_WEEKS_AGO:9'],
+    // Month tier (offsets 0..9 = THIS_MONTH, LAST_MONTH, N_MONTHS_AGO:2..9)
+    THIS_MONTH: [
+        'THIS_MONTH',
+        'LAST_MONTH',
+        'N_MONTHS_AGO:2',
+        'N_MONTHS_AGO:3',
+        'N_MONTHS_AGO:4',
+        'N_MONTHS_AGO:5',
+        'N_MONTHS_AGO:6',
+        'N_MONTHS_AGO:7',
+        'N_MONTHS_AGO:8',
+        'N_MONTHS_AGO:9',
+    ],
+    LAST_MONTH: [
+        'LAST_MONTH',
+        'N_MONTHS_AGO:2',
+        'N_MONTHS_AGO:3',
+        'N_MONTHS_AGO:4',
+        'N_MONTHS_AGO:5',
+        'N_MONTHS_AGO:6',
+        'N_MONTHS_AGO:7',
+        'N_MONTHS_AGO:8',
+        'N_MONTHS_AGO:9',
+    ],
+    'N_MONTHS_AGO:2': [
+        'N_MONTHS_AGO:2',
+        'N_MONTHS_AGO:3',
+        'N_MONTHS_AGO:4',
+        'N_MONTHS_AGO:5',
+        'N_MONTHS_AGO:6',
+        'N_MONTHS_AGO:7',
+        'N_MONTHS_AGO:8',
+        'N_MONTHS_AGO:9',
+    ],
+    'N_MONTHS_AGO:3': [
+        'N_MONTHS_AGO:3',
+        'N_MONTHS_AGO:4',
+        'N_MONTHS_AGO:5',
+        'N_MONTHS_AGO:6',
+        'N_MONTHS_AGO:7',
+        'N_MONTHS_AGO:8',
+        'N_MONTHS_AGO:9',
+    ],
+    'N_MONTHS_AGO:4': [
+        'N_MONTHS_AGO:4',
+        'N_MONTHS_AGO:5',
+        'N_MONTHS_AGO:6',
+        'N_MONTHS_AGO:7',
+        'N_MONTHS_AGO:8',
+        'N_MONTHS_AGO:9',
+    ],
+    'N_MONTHS_AGO:5': ['N_MONTHS_AGO:5', 'N_MONTHS_AGO:6', 'N_MONTHS_AGO:7', 'N_MONTHS_AGO:8', 'N_MONTHS_AGO:9'],
+    'N_MONTHS_AGO:6': ['N_MONTHS_AGO:6', 'N_MONTHS_AGO:7', 'N_MONTHS_AGO:8', 'N_MONTHS_AGO:9'],
+    'N_MONTHS_AGO:7': ['N_MONTHS_AGO:7', 'N_MONTHS_AGO:8', 'N_MONTHS_AGO:9'],
+    'N_MONTHS_AGO:8': ['N_MONTHS_AGO:8', 'N_MONTHS_AGO:9'],
+    'N_MONTHS_AGO:9': ['N_MONTHS_AGO:9'],
+    // Quarter tier (offsets 0..9 = THIS_QUARTER, LAST_QUARTER, N_QUARTERS_AGO:2..9)
+    THIS_QUARTER: [
+        'THIS_QUARTER',
+        'LAST_QUARTER',
+        'N_QUARTERS_AGO:2',
+        'N_QUARTERS_AGO:3',
+        'N_QUARTERS_AGO:4',
+        'N_QUARTERS_AGO:5',
+        'N_QUARTERS_AGO:6',
+        'N_QUARTERS_AGO:7',
+        'N_QUARTERS_AGO:8',
+        'N_QUARTERS_AGO:9',
+    ],
+    LAST_QUARTER: [
+        'LAST_QUARTER',
+        'N_QUARTERS_AGO:2',
+        'N_QUARTERS_AGO:3',
+        'N_QUARTERS_AGO:4',
+        'N_QUARTERS_AGO:5',
+        'N_QUARTERS_AGO:6',
+        'N_QUARTERS_AGO:7',
+        'N_QUARTERS_AGO:8',
+        'N_QUARTERS_AGO:9',
+    ],
+    'N_QUARTERS_AGO:2': [
+        'N_QUARTERS_AGO:2',
+        'N_QUARTERS_AGO:3',
+        'N_QUARTERS_AGO:4',
+        'N_QUARTERS_AGO:5',
+        'N_QUARTERS_AGO:6',
+        'N_QUARTERS_AGO:7',
+        'N_QUARTERS_AGO:8',
+        'N_QUARTERS_AGO:9',
+    ],
+    'N_QUARTERS_AGO:3': [
+        'N_QUARTERS_AGO:3',
+        'N_QUARTERS_AGO:4',
+        'N_QUARTERS_AGO:5',
+        'N_QUARTERS_AGO:6',
+        'N_QUARTERS_AGO:7',
+        'N_QUARTERS_AGO:8',
+        'N_QUARTERS_AGO:9',
+    ],
+    'N_QUARTERS_AGO:4': [
+        'N_QUARTERS_AGO:4',
+        'N_QUARTERS_AGO:5',
+        'N_QUARTERS_AGO:6',
+        'N_QUARTERS_AGO:7',
+        'N_QUARTERS_AGO:8',
+        'N_QUARTERS_AGO:9',
+    ],
+    'N_QUARTERS_AGO:5': [
+        'N_QUARTERS_AGO:5',
+        'N_QUARTERS_AGO:6',
+        'N_QUARTERS_AGO:7',
+        'N_QUARTERS_AGO:8',
+        'N_QUARTERS_AGO:9',
+    ],
+    'N_QUARTERS_AGO:6': ['N_QUARTERS_AGO:6', 'N_QUARTERS_AGO:7', 'N_QUARTERS_AGO:8', 'N_QUARTERS_AGO:9'],
+    'N_QUARTERS_AGO:7': ['N_QUARTERS_AGO:7', 'N_QUARTERS_AGO:8', 'N_QUARTERS_AGO:9'],
+    'N_QUARTERS_AGO:8': ['N_QUARTERS_AGO:8', 'N_QUARTERS_AGO:9'],
+    'N_QUARTERS_AGO:9': ['N_QUARTERS_AGO:9'],
+    // Year tier (offsets 0..9 = THIS_YEAR, LAST_YEAR, N_YEARS_AGO:2..9)
+    THIS_YEAR: [
+        'THIS_YEAR',
+        'LAST_YEAR',
+        'N_YEARS_AGO:2',
+        'N_YEARS_AGO:3',
+        'N_YEARS_AGO:4',
+        'N_YEARS_AGO:5',
+        'N_YEARS_AGO:6',
+        'N_YEARS_AGO:7',
+        'N_YEARS_AGO:8',
+        'N_YEARS_AGO:9',
+    ],
+    LAST_YEAR: [
+        'LAST_YEAR',
+        'N_YEARS_AGO:2',
+        'N_YEARS_AGO:3',
+        'N_YEARS_AGO:4',
+        'N_YEARS_AGO:5',
+        'N_YEARS_AGO:6',
+        'N_YEARS_AGO:7',
+        'N_YEARS_AGO:8',
+        'N_YEARS_AGO:9',
+    ],
+    'N_YEARS_AGO:2': [
+        'N_YEARS_AGO:2',
+        'N_YEARS_AGO:3',
+        'N_YEARS_AGO:4',
+        'N_YEARS_AGO:5',
+        'N_YEARS_AGO:6',
+        'N_YEARS_AGO:7',
+        'N_YEARS_AGO:8',
+        'N_YEARS_AGO:9',
+    ],
+    'N_YEARS_AGO:3': [
+        'N_YEARS_AGO:3',
+        'N_YEARS_AGO:4',
+        'N_YEARS_AGO:5',
+        'N_YEARS_AGO:6',
+        'N_YEARS_AGO:7',
+        'N_YEARS_AGO:8',
+        'N_YEARS_AGO:9',
+    ],
+    'N_YEARS_AGO:4': [
+        'N_YEARS_AGO:4',
+        'N_YEARS_AGO:5',
+        'N_YEARS_AGO:6',
+        'N_YEARS_AGO:7',
+        'N_YEARS_AGO:8',
+        'N_YEARS_AGO:9',
+    ],
+    'N_YEARS_AGO:5': ['N_YEARS_AGO:5', 'N_YEARS_AGO:6', 'N_YEARS_AGO:7', 'N_YEARS_AGO:8', 'N_YEARS_AGO:9'],
+    'N_YEARS_AGO:6': ['N_YEARS_AGO:6', 'N_YEARS_AGO:7', 'N_YEARS_AGO:8', 'N_YEARS_AGO:9'],
+    'N_YEARS_AGO:7': ['N_YEARS_AGO:7', 'N_YEARS_AGO:8', 'N_YEARS_AGO:9'],
+    'N_YEARS_AGO:8': ['N_YEARS_AGO:8', 'N_YEARS_AGO:9'],
+    'N_YEARS_AGO:9': ['N_YEARS_AGO:9'],
+    // Span literals: no cascade (they already combine multiple periods)
+    'LAST_N_YEARS:2': ['LAST_N_YEARS:2'],
+    'LAST_N_YEARS:3': ['LAST_N_YEARS:3'],
+};
+/**
+ * Validates a date literal value against the ISV-supported set.
+ *
+ * @param value - The date literal string to validate
+ * @returns undefined if valid, error message string if invalid
+ */
+export function validateDateLiteral(value) {
+    const upper = value.toUpperCase();
+    if (!SUPPORTED_DATE_LITERALS.includes(upper)) {
+        return `Invalid date literal "${value}". Supported values: ${SUPPORTED_DATE_LITERALS.join(', ')}`;
+    }
+    return undefined;
+}
+/**
+ * Resolves CLI flag inputs into a validated DateLiteralRange.
+ *
+ * @param input - Raw flag inputs
+ * @returns Resolved DateLiteralRange
+ * @throws Error if inputs are invalid
+ */
+export function resolveDateLiteralRange(input) {
+    const upper = input.dateLiteral.toUpperCase();
+    const validationError = validateDateLiteral(upper);
+    if (validationError) {
+        throw new Error(validationError);
+    }
+    const tier = LITERAL_TIERS[upper];
+    const maxDepth = TIER_MAX_DEPTH[tier];
+    const cascade = LITERAL_CASCADES[upper];
+    const depth = input.depth ?? 1;
+    if (depth < 1) {
+        throw new Error(`--depth must be at least 1, got ${depth}`);
+    }
+    const effectiveMax = Math.min(cascade.length, maxDepth);
+    if (depth > effectiveMax) {
+        const hint = tier === 'span'
+            ? '--depth is not supported for span-tier date literals. Span literals already aggregate multiple periods.'
+            : cascade.length < maxDepth
+                ? `"${upper}" supports a maximum depth of ${cascade.length}. Use an earlier ${tier}-tier literal for deeper cascading (max: ${maxDepth}).`
+                : `Maximum depth for ${tier} tier: ${maxDepth}.`;
+        throw new Error(`--depth ${depth} exceeds maximum of ${effectiveMax} for "${upper}". ${hint}`);
+    }
+    const entries = cascade.slice(0, depth).map((literal) => ({
+        literal,
+        label: DATE_LITERAL_LABELS[literal],
+    }));
+    return {
+        entries,
+        dateField: input.dateField ?? 'CreatedDate',
+    };
+}
+/**
+ * Returns the customer-facing label for a date literal.
+ *
+ * @param literal - A supported date literal value
+ * @returns The label string, or the raw literal if not found
+ */
+export function getDateLiteralLabel(literal) {
+    const upper = literal.toUpperCase();
+    return DATE_LITERAL_LABELS[upper] ?? literal;
+}
+/**
+ * Customer-facing labels for known date-field API names.
+ * Used by humanizeDateField() to render filter labels and description text.
+ */
+export const DATE_FIELD_LABELS = {
+    CreatedDate: 'Created Date',
+    LastModifiedDate: 'Last Modified Date',
+};
+/**
+ * Converts a date-field API name into a customer-facing label.
+ *
+ * Examples:
+ * - `humanizeDateField('CreatedDate')` returns `'Created Date'`
+ * - `humanizeDateField('LastModifiedDate')` returns `'Last Modified Date'`
+ * - `humanizeDateField('SomeCustomDate__c')` returns `'Some Custom Date'`
+ * - `humanizeDateField('')` returns `''`
+ *
+ * Known field names return their canonical label from DATE_FIELD_LABELS.
+ * Unknown PascalCase identifiers are split into space-separated words
+ * with custom-field `__c` suffix stripped. Falsy input is returned
+ * as-is so caller-side `label ? ... : dateField` truthy guards continue
+ * to work unchanged.
+ *
+ * @param dateField - The date-field API name (e.g., 'CreatedDate')
+ * @returns The customer-facing label
+ */
+export function humanizeDateField(dateField) {
+    if (!dateField)
+        return dateField;
+    const known = DATE_FIELD_LABELS[dateField];
+    if (known)
+        return known;
+    const withoutCustomSuffix = dateField.replace(/__c$/i, '').replace(/__/g, ' ');
+    return withoutCustomSuffix
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/_/g, ' ')
+        .trim();
+}
+/**
+ * Maps each date literal to its `$Constant.*` display value for the expression builder.
+ * These are the values that `fsc_expressionBuilder3` renders in the Value field.
+ *
+ * Naming mirrors the existing year-tier convention ($Constant.TwoYearsAgo,
+ * $Constant.ThreeYearsAgo) — CLI-3419 extends to all non-span tiers.
+ */
+export const DATE_LITERAL_CONSTANTS = {
+    // Day tier
+    TODAY: '$Constant.Today',
+    YESTERDAY: '$Constant.Yesterday',
+    'N_DAYS_AGO:2': '$Constant.TwoDaysAgo',
+    'N_DAYS_AGO:3': '$Constant.ThreeDaysAgo',
+    'N_DAYS_AGO:4': '$Constant.FourDaysAgo',
+    'N_DAYS_AGO:5': '$Constant.FiveDaysAgo',
+    'N_DAYS_AGO:6': '$Constant.SixDaysAgo',
+    'N_DAYS_AGO:7': '$Constant.SevenDaysAgo',
+    'N_DAYS_AGO:8': '$Constant.EightDaysAgo',
+    'N_DAYS_AGO:9': '$Constant.NineDaysAgo',
+    // Week tier
+    THIS_WEEK: '$Constant.ThisWeek',
+    LAST_WEEK: '$Constant.LastWeek',
+    'N_WEEKS_AGO:2': '$Constant.TwoWeeksAgo',
+    'N_WEEKS_AGO:3': '$Constant.ThreeWeeksAgo',
+    'N_WEEKS_AGO:4': '$Constant.FourWeeksAgo',
+    'N_WEEKS_AGO:5': '$Constant.FiveWeeksAgo',
+    'N_WEEKS_AGO:6': '$Constant.SixWeeksAgo',
+    'N_WEEKS_AGO:7': '$Constant.SevenWeeksAgo',
+    'N_WEEKS_AGO:8': '$Constant.EightWeeksAgo',
+    'N_WEEKS_AGO:9': '$Constant.NineWeeksAgo',
+    // Month tier
+    THIS_MONTH: '$Constant.ThisMonth',
+    LAST_MONTH: '$Constant.LastMonth',
+    'N_MONTHS_AGO:2': '$Constant.TwoMonthsAgo',
+    'N_MONTHS_AGO:3': '$Constant.ThreeMonthsAgo',
+    'N_MONTHS_AGO:4': '$Constant.FourMonthsAgo',
+    'N_MONTHS_AGO:5': '$Constant.FiveMonthsAgo',
+    'N_MONTHS_AGO:6': '$Constant.SixMonthsAgo',
+    'N_MONTHS_AGO:7': '$Constant.SevenMonthsAgo',
+    'N_MONTHS_AGO:8': '$Constant.EightMonthsAgo',
+    'N_MONTHS_AGO:9': '$Constant.NineMonthsAgo',
+    // Quarter tier
+    THIS_QUARTER: '$Constant.ThisQuarter',
+    LAST_QUARTER: '$Constant.LastQuarter',
+    'N_QUARTERS_AGO:2': '$Constant.TwoQuartersAgo',
+    'N_QUARTERS_AGO:3': '$Constant.ThreeQuartersAgo',
+    'N_QUARTERS_AGO:4': '$Constant.FourQuartersAgo',
+    'N_QUARTERS_AGO:5': '$Constant.FiveQuartersAgo',
+    'N_QUARTERS_AGO:6': '$Constant.SixQuartersAgo',
+    'N_QUARTERS_AGO:7': '$Constant.SevenQuartersAgo',
+    'N_QUARTERS_AGO:8': '$Constant.EightQuartersAgo',
+    'N_QUARTERS_AGO:9': '$Constant.NineQuartersAgo',
+    // Year tier
+    THIS_YEAR: '$Constant.ThisYear',
+    LAST_YEAR: '$Constant.LastYear',
+    'N_YEARS_AGO:2': '$Constant.TwoYearsAgo',
+    'N_YEARS_AGO:3': '$Constant.ThreeYearsAgo',
+    'N_YEARS_AGO:4': '$Constant.FourYearsAgo',
+    'N_YEARS_AGO:5': '$Constant.FiveYearsAgo',
+    'N_YEARS_AGO:6': '$Constant.SixYearsAgo',
+    'N_YEARS_AGO:7': '$Constant.SevenYearsAgo',
+    'N_YEARS_AGO:8': '$Constant.EightYearsAgo',
+    'N_YEARS_AGO:9': '$Constant.NineYearsAgo',
+    // Span tier
+    'LAST_N_YEARS:2': '$Constant.LastTwoYears',
+    'LAST_N_YEARS:3': '$Constant.LastThreeYears',
+};
+/**
+ * Builds an ISV-compatible filterJson string for date literal filtering.
+ *
+ * Produces the full expression builder JSON schema that `fsc_expressionBuilder3` expects,
+ * including all 12 required fields per expression line. The `parameter` field uses `$Constant.*`
+ * display values and `parameterValue` / `dateLiteral` use the SOQL literal.
+ *
+ * The outer envelope (hasFilters, setA) is required by ProfilingDefinitionApiService.resolveFilterClause()
+ * to enable WHERE clause filtering. setA.json must be an object (not a string) — the API
+ * does JSON.serialize() on it.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
+ * @param dateLiteral - The date literal value (e.g., 'THIS_YEAR', 'N_YEARS_AGO:2')
+ * @param objectName - The Salesforce object API name (e.g., 'Account', 'Lead'). Defaults to empty string for backward compatibility.
+ * @param objectLabel - The Salesforce object label (e.g., 'Account', 'Lead'). Defaults to objectName.
+ * @returns JSON string compatible with GlobalProfilingService.createProfilingDefinition()
+ */
+export function buildDateLiteralFilterJson(dateField, dateLiteral, objectName = '', objectLabel) {
+    const label = objectLabel ?? objectName;
+    const constantValue = DATE_LITERAL_CONSTANTS[dateLiteral] ?? dateLiteral;
+    const expressionJson = {
+        expressions: [
+            {
+                objectType: objectName,
+                parameter: constantValue,
+                parameterValue: dateLiteral,
+                dataType: 'DATETIME',
+                label: label ? `${label}: ${humanizeDateField(dateField)}` : dateField,
+                type: objectName,
+                fieldName: dateField,
+                operator: 'equals',
+                operatorSymbol: '=',
+                value: objectName ? `$${objectName}.${dateField}` : dateField,
+                dateLiteral,
+            },
+        ],
+        logicType: 'AND',
+    };
+    return JSON.stringify({
+        hasFilters: true,
+        setA: {
+            json: expressionJson,
+            expression: `${dateField} = ${dateLiteral}`,
+        },
+    });
+}
+/**
+ * Builds an ISV-compatible filterJson string for date-literal comparative definitions.
+ * Creates SetA (primary period) and SetB (prior period), both using SOQL date literals.
+ *
+ * Used when method='comparative' with a date literal that has a prior period in its cascade.
+ * The prior literal is derived from LITERAL_CASCADES[setALiteral][1] by the caller.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
+ * @param setALiteral - The primary (current) date literal for SetA
+ * @param setBLiteral - The prior period date literal for SetB
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label
+ * @returns JSON string with hasFilters, setA, and setB
+ */
+export function buildComparativeDateLiteralFilterJson(dateField, setALiteral, setBLiteral, objectName = '', objectLabel) {
+    const label = objectLabel ?? objectName;
+    const fieldLabel = label ? `${label}: ${humanizeDateField(dateField)}` : dateField;
+    const fieldValue = objectName ? `$${objectName}.${dateField}` : dateField;
+    const buildExpression = (literal) => {
+        const constantValue = DATE_LITERAL_CONSTANTS[literal] ?? literal;
+        return {
+            expressions: [
+                {
+                    objectType: objectName,
+                    parameter: constantValue,
+                    parameterValue: literal,
+                    dataType: 'DATETIME',
+                    label: fieldLabel,
+                    type: objectName,
+                    fieldName: dateField,
+                    operator: 'equals',
+                    operatorSymbol: '=',
+                    value: fieldValue,
+                    dateLiteral: literal,
+                },
+            ],
+            logicType: 'AND',
+        };
+    };
+    return JSON.stringify({
+        hasFilters: true,
+        setA: {
+            json: buildExpression(setALiteral),
+            expression: `${dateField} = ${setALiteral}`,
+        },
+        setB: {
+            json: buildExpression(setBLiteral),
+            expression: `${dateField} = ${setBLiteral}`,
+        },
+    });
+}
+/**
+ * Formats a year boundary as an ISO 8601 UTC midnight string.
+ * Used for explicit date range expressions in year-based comparisons.
+ */
+export function yearBoundaryISO(year) {
+    return `${year}-01-01T00:00:00.000Z`;
+}
+/**
+ * Formats a year boundary as a human-readable display string (M/d/yyyy, h:mm a).
+ * Used for the `parameter` display value in expression builder JSON.
+ */
+export function yearBoundaryDisplay(year) {
+    return `1/1/${year}, 12:00 AM`;
+}
+/**
+ * Builds an ISV-compatible filterJson string for a single year (SetA only, no SetB).
+ * Used for historical definitions scoped to a specific year via --year flag.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate')
+ * @param year - The target year
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label
+ * @returns JSON string with hasFilters and setA (no setB)
+ */
+export function buildHistoricalYearFilterJson(dateField, year, objectName = '', objectLabel) {
+    const label = objectLabel ?? objectName;
+    const fieldLabel = label ? `${label}: ${humanizeDateField(dateField)}` : dateField;
+    const fieldValue = objectName ? `$${objectName}.${dateField}` : dateField;
+    const yearStart = yearBoundaryISO(year);
+    const yearEnd = yearBoundaryISO(year + 1);
+    const yearStartDisplay = yearBoundaryDisplay(year);
+    const yearEndDisplay = yearBoundaryDisplay(year + 1);
+    return JSON.stringify({
+        hasFilters: true,
+        setA: {
+            json: {
+                expressions: [
+                    {
+                        objectType: objectName,
+                        parameter: yearStartDisplay,
+                        parameterValue: yearStart,
+                        dataType: 'DATETIME',
+                        label: fieldLabel,
+                        type: objectName,
+                        fieldName: dateField,
+                        operator: 'greater_or_equal',
+                        operatorSymbol: '>=',
+                        value: fieldValue,
+                        dateLiteral: '',
+                    },
+                    {
+                        objectType: objectName,
+                        parameter: yearEndDisplay,
+                        parameterValue: yearEnd,
+                        dataType: 'DATETIME',
+                        label: fieldLabel,
+                        type: objectName,
+                        fieldName: dateField,
+                        operator: 'less_than',
+                        operatorSymbol: '<',
+                        value: fieldValue,
+                        dateLiteral: '',
+                    },
+                ],
+                logicType: 'AND',
+            },
+            expression: `${dateField} >= ${yearStart} AND ${dateField} < ${yearEnd}`,
+        },
+    });
+}
+/**
+ * Builds an ISV-compatible filterJson string for year-based comparative definitions.
+ * Creates SetA (target year) and SetB (prior year or all prior years) using explicit
+ * date range expressions (>= start AND < end), not date literals.
+ *
+ * This approach supports arbitrary years with no lookback limitation.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
+ * @param year - The target year for SetA
+ * @param usePrior - When true, SetB is all records before the target year. When false, SetB is the prior year.
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label
+ * @returns JSON string with hasFilters, setA, and setB
+ */
+export function buildComparativeYearFilterJson(dateField, year, usePrior, objectName = '', objectLabel) {
+    const label = objectLabel ?? objectName;
+    const fieldLabel = label ? `${label}: ${humanizeDateField(dateField)}` : dateField;
+    const fieldValue = objectName ? `$${objectName}.${dateField}` : dateField;
+    const yearStart = yearBoundaryISO(year);
+    const yearEnd = yearBoundaryISO(year + 1);
+    const yearStartDisplay = yearBoundaryDisplay(year);
+    const yearEndDisplay = yearBoundaryDisplay(year + 1);
+    // SetA: target year (>= Jan 1 year AND < Jan 1 year+1)
+    const setAJson = {
+        expressions: [
+            {
+                objectType: objectName,
+                parameter: yearStartDisplay,
+                parameterValue: yearStart,
+                dataType: 'DATETIME',
+                label: fieldLabel,
+                type: objectName,
+                fieldName: dateField,
+                operator: 'greater_or_equal',
+                operatorSymbol: '>=',
+                value: fieldValue,
+                dateLiteral: '',
+            },
+            {
+                objectType: objectName,
+                parameter: yearEndDisplay,
+                parameterValue: yearEnd,
+                dataType: 'DATETIME',
+                label: fieldLabel,
+                type: objectName,
+                fieldName: dateField,
+                operator: 'less_than',
+                operatorSymbol: '<',
+                value: fieldValue,
+                dateLiteral: '',
+            },
+        ],
+        logicType: 'AND',
+    };
+    // SetB: prior year or all prior
+    let setBJson;
+    let setBExpression;
+    if (usePrior) {
+        // All records before the target year
+        setBJson = {
+            expressions: [
+                {
+                    objectType: objectName,
+                    parameter: yearStartDisplay,
+                    parameterValue: yearStart,
+                    dataType: 'DATETIME',
+                    label: fieldLabel,
+                    type: objectName,
+                    fieldName: dateField,
+                    operator: 'less_than',
+                    operatorSymbol: '<',
+                    value: fieldValue,
+                    dateLiteral: '',
+                },
+            ],
+            logicType: 'AND',
+        };
+        setBExpression = `${dateField} < ${yearStart}`;
+    }
+    else {
+        // Prior year only (>= Jan 1 year-1 AND < Jan 1 year)
+        const priorStart = yearBoundaryISO(year - 1);
+        const priorStartDisplay = yearBoundaryDisplay(year - 1);
+        setBJson = {
+            expressions: [
+                {
+                    objectType: objectName,
+                    parameter: priorStartDisplay,
+                    parameterValue: priorStart,
+                    dataType: 'DATETIME',
+                    label: fieldLabel,
+                    type: objectName,
+                    fieldName: dateField,
+                    operator: 'greater_or_equal',
+                    operatorSymbol: '>=',
+                    value: fieldValue,
+                    dateLiteral: '',
+                },
+                {
+                    objectType: objectName,
+                    parameter: yearStartDisplay,
+                    parameterValue: yearStart,
+                    dataType: 'DATETIME',
+                    label: fieldLabel,
+                    type: objectName,
+                    fieldName: dateField,
+                    operator: 'less_than',
+                    operatorSymbol: '<',
+                    value: fieldValue,
+                    dateLiteral: '',
+                },
+            ],
+            logicType: 'AND',
+        };
+        setBExpression = `${dateField} >= ${priorStart} AND ${dateField} < ${yearStart}`;
+    }
+    return JSON.stringify({
+        hasFilters: true,
+        setA: {
+            json: setAJson,
+            expression: `${dateField} >= ${yearStart} AND ${dateField} < ${yearEnd}`,
+        },
+        setB: {
+            json: setBJson,
+            expression: setBExpression,
+        },
+    });
+}
+/**
+ * Builds an ISV-compatible filterJson string for the lifetime-vs-X comparative variant.
+ *
+ * SetA is unfiltered (empty expressions array — represents "all records / lifetime"); SetB carries the supplied
+ * secondary filter. This is the inverse of `buildComparativeYearFilterJson`, where SetA is the year-scoped set and
+ * SetB is the prior-year (or unbounded) set.
+ *
+ * @param dateField - The date/datetime field to filter on (e.g., 'CreatedDate', 'LastModifiedDate')
+ * @param secondary - The secondary filter spec applied to SetB. Accepts `{ kind: 'year', year }` for a year-bounded SetB,
+ * or `{ kind: 'dateLiteral', literal }` for a SOQL date-literal SetB.
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label (defaults to objectName)
+ * @returns JSON string with hasFilters, setA (empty), and setB (filtered)
+ */
+export function buildLifetimeComparativeFilterJson(dateField, secondary, objectName = '', objectLabel) {
+    const label = objectLabel ?? objectName;
+    const fieldLabel = label ? `${label}: ${humanizeDateField(dateField)}` : dateField;
+    const fieldValue = objectName ? `$${objectName}.${dateField}` : dateField;
+    // SetA — empty expressions array represents "lifetime / all records" at the ISV layer.
+    const setAJson = {
+        expressions: [],
+        logicType: 'AND',
+    };
+    let setBJson;
+    let setBExpression;
+    if (secondary.kind === 'year') {
+        const yearStart = yearBoundaryISO(secondary.year);
+        const yearEnd = yearBoundaryISO(secondary.year + 1);
+        const yearStartDisplay = yearBoundaryDisplay(secondary.year);
+        const yearEndDisplay = yearBoundaryDisplay(secondary.year + 1);
+        setBJson = {
+            expressions: [
+                {
+                    objectType: objectName,
+                    parameter: yearStartDisplay,
+                    parameterValue: yearStart,
+                    dataType: 'DATETIME',
+                    label: fieldLabel,
+                    type: objectName,
+                    fieldName: dateField,
+                    operator: 'greater_or_equal',
+                    operatorSymbol: '>=',
+                    value: fieldValue,
+                    dateLiteral: '',
+                },
+                {
+                    objectType: objectName,
+                    parameter: yearEndDisplay,
+                    parameterValue: yearEnd,
+                    dataType: 'DATETIME',
+                    label: fieldLabel,
+                    type: objectName,
+                    fieldName: dateField,
+                    operator: 'less_than',
+                    operatorSymbol: '<',
+                    value: fieldValue,
+                    dateLiteral: '',
+                },
+            ],
+            logicType: 'AND',
+        };
+        setBExpression = `${dateField} >= ${yearStart} AND ${dateField} < ${yearEnd}`;
+    }
+    else {
+        const constantValue = DATE_LITERAL_CONSTANTS[secondary.literal] ?? secondary.literal;
+        setBJson = {
+            expressions: [
+                {
+                    objectType: objectName,
+                    parameter: constantValue,
+                    parameterValue: secondary.literal,
+                    dataType: 'DATETIME',
+                    label: fieldLabel,
+                    type: objectName,
+                    fieldName: dateField,
+                    operator: 'equals',
+                    operatorSymbol: '=',
+                    value: fieldValue,
+                    dateLiteral: secondary.literal,
+                },
+            ],
+            logicType: 'AND',
+        };
+        setBExpression = `${dateField} = ${secondary.literal}`;
+    }
+    return JSON.stringify({
+        hasFilters: true,
+        setA: {
+            json: setAJson,
+            expression: '',
+        },
+        setB: {
+            json: setBJson,
+            expression: setBExpression,
+        },
+    });
+}
+/**
+ * Single expression-builder JSON line representing a `RecordTypeId = <rtId>` condition.
+ * Matches the 11-field schema (12 with optional `id`) that `fsc_expressionBuilder3` expects,
+ * used when scoping a profiling definition to a specific record type.
+ *
+ * @param rtId - The RecordType Salesforce ID (15 or 18 chars)
+ * @param objectName - The Salesforce object API name (e.g., 'Case')
+ * @param objectLabel - The Salesforce object label (defaults to objectName)
+ * @returns Expression line ready to embed in `setA.json.expressions` / `setB.json.expressions`
+ */
+export function buildRecordTypeFilterExpression(rtId, objectName = '', objectLabel) {
+    const label = objectLabel ?? objectName;
+    // parameterValue must be SOQL-ready: server-side ExpressionBuilder concatenates it raw into
+    // the WHERE clause for non-DATETIME types (open-source/classes/ExpressionBuilder.cls:572), and
+    // RecordTypeId is an Id reference field — without the surrounding single quotes the emitted
+    // SOQL is "RecordTypeId = 012ABC..." and Salesforce returns MALFORMED_QUERY 400.
+    return {
+        objectType: objectName,
+        parameter: rtId,
+        parameterValue: `'${rtId}'`,
+        dataType: 'STRING',
+        label: label ? `${label}: Record Type ID` : 'Record Type ID',
+        type: objectName,
+        fieldName: 'RecordTypeId',
+        operator: 'equals',
+        operatorSymbol: '=',
+        value: objectName ? `$${objectName}.RecordTypeId` : 'RecordTypeId',
+        dateLiteral: '',
+    };
+}
+/**
+ * Composes a RecordTypeId scope filter into an existing ISV filterJson envelope so the server
+ * restricts profiling SOQL to a single record type. CLI-3834: `--method recordtype` was writing
+ * the RT name to `Prop_SegmentCategory__c` (label only) without populating the filter/RT-scope
+ * fields. This helper appends the RT condition to `setA` (and `setB` when present) preserving
+ * the source `logicType` (defaults to `'AND'` for the legacy canonical builders).
+ *
+ * When `filterJson` is `undefined`/`null` (Lifetime path), returns a fresh envelope with
+ * `setA.json.expressions = [rtExpression]` and `hasFilters: true`.
+ *
+ * @param filterJson - Existing filterJson string from a `buildXxxFilterJson` helper, or undefined
+ * @param rtId - The RecordType Salesforce ID
+ * @param objectName - The Salesforce object API name
+ * @param objectLabel - The Salesforce object label (defaults to objectName)
+ * @returns Updated filterJson string carrying the RT scope on every existing filter side
+ */
+export function composeRecordTypeFilter(filterJson, rtId, objectName = '', objectLabel) {
+    const rtExpression = buildRecordTypeFilterExpression(rtId, objectName, objectLabel);
+    const rtExpressionText = `RecordTypeId = '${rtId}'`;
+    if (!filterJson) {
+        return JSON.stringify({
+            hasFilters: true,
+            setA: {
+                json: {
+                    expressions: [rtExpression],
+                    logicType: 'AND',
+                },
+                expression: rtExpressionText,
+            },
+        });
+    }
+    const parsed = JSON.parse(filterJson);
+    const append = (set) => {
+        if (!set)
+            return undefined;
+        const updatedExpressions = [...set.json.expressions, rtExpression];
+        const composedExpression = set.expression ? `${set.expression} AND ${rtExpressionText}` : rtExpressionText;
+        return {
+            ...set,
+            json: {
+                ...set.json,
+                expressions: updatedExpressions,
+                logicType: set.json.logicType ?? 'AND',
+            },
+            expression: composedExpression,
+        };
+    };
+    return JSON.stringify({
+        hasFilters: true,
+        ...(parsed.setA ? { setA: append(parsed.setA) } : {}),
+        ...(parsed.setB ? { setB: append(parsed.setB) } : {}),
+    });
+}
+//# sourceMappingURL=date-literal.js.map