@quonfig/cli 0.0.46 → 0.0.48

package/dist/migrate/migration-report.d.ts

@@ -1,4 +1,5 @@
 import type { IdentifierMap } from './identifier-map.js';
+import type { ConversionNote } from './quonfig-target/report.js';
 import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolutionSummary, SkippedConfigSummary } from './source.js';
 export interface MigrationReportCounts {
     configsMigrated: number;
@@ -38,6 +39,14 @@ export interface MigrationReportData {
      * was coerced.
      */
     coercedSentinels?: CoercedSentinelSummary | null;
+    /**
+     * Structured conversion notes from a provider's `translate()` — re-bucketed
+     * rollouts, dropped prerequisites, lossy individual-target conversions, etc.
+     * (the LaunchDarkly `quonfig-target/report.ts` set). Rendered into the
+     * "Users will be re-bucketed" + "Conversion notes" sections. Undefined or
+     * empty when the source emitted none.
+     */
+    conversionNotes?: ConversionNote[];
     counts: MigrationReportCounts;
     /**
      * Override sections that were dropped during translate() because the env.id was not

package/dist/migrate/migration-report.js

@@ -126,6 +126,68 @@ const renderSkippedConfigs = (skipped) => {
     }
     return lines.join('\n');
 };
+/**
+ * Human-readable headings for the non-rollout conversion-note categories.
+ * `skipped-config` is intentionally absent — it has its own dedicated section
+ * (`renderSkippedConfigs`). `rebucketed-rollout` is absent because it gets its
+ * own top-level section (`renderRebucketedRollouts`) — plan §5.4 requires it
+ * be impossible to miss.
+ */
+const CONVERSION_NOTE_HEADINGS = {
+    'ai-config-skipped': 'AI Configs skipped (out of v1 scope)',
+    'dropped-custom-properties': 'Dropped custom properties',
+    'dropped-experiment-metadata': 'Dropped experiment metadata',
+    'dropped-maintainer': 'Dropped maintainer metadata',
+    'dropped-mobile-key-availability': 'Dropped mobile-key availability',
+    'dropped-prerequisite': 'Dropped prerequisites',
+    'dropped-private-attribute': 'Dropped private attributes',
+    'individual-target-as-rule': 'Individual targets converted to rules',
+    'skipped-rule': 'Skipped rules (unsupported operators)',
+    'unexportable-segment-membership': 'Unexportable segment membership',
+};
+const renderRebucketedRollouts = (notes) => {
+    const rollouts = (notes ?? []).filter((n) => n.category === 'rebucketed-rollout');
+    if (rollouts.length === 0)
+        return null;
+    const lines = [
+        '## Users will be re-bucketed',
+        '',
+        `**${rollouts.length}** flag(s)/segment(s) use a percentage rollout. LaunchDarkly and Quonfig hash buckets ` +
+            `differently, so which users land in which bucket *will change* after migration — the rollout percentage is ` +
+            `preserved, but individual user assignments are not. Review these before cutover so the re-bucketing is not a surprise:`,
+        '',
+    ];
+    const sorted = [...rollouts].sort((a, b) => a.key.localeCompare(b.key));
+    for (const note of sorted) {
+        lines.push(`- \`${note.key}\` — ${note.detail}`);
+    }
+    return lines.join('\n');
+};
+const renderConversionNotes = (notes) => {
+    // `skipped-config` (own section) and `rebucketed-rollout` (own section) are
+    // rendered elsewhere — everything else is grouped by category here.
+    const grouped = (notes ?? []).filter((n) => n.category !== 'rebucketed-rollout' && n.category !== 'skipped-config');
+    if (grouped.length === 0)
+        return null;
+    const lines = [
+        '## Conversion notes',
+        '',
+        `**${grouped.length}** note(s) where the converter could not represent a source concept exactly. Nothing was ` +
+            `silently dropped — each entry below names the exact flag/segment and what was lost so you can rebuild it by hand if needed.`,
+    ];
+    const categoriesInOrder = Object.keys(CONVERSION_NOTE_HEADINGS);
+    for (const category of categoriesInOrder) {
+        const forCategory = grouped.filter((n) => n.category === category);
+        if (forCategory.length === 0)
+            continue;
+        lines.push('', `### ${CONVERSION_NOTE_HEADINGS[category]}`, '');
+        const sorted = [...forCategory].sort((a, b) => a.key.localeCompare(b.key));
+        for (const note of sorted) {
+            lines.push(`- \`${note.key}\` — ${note.detail}`);
+        }
+    }
+    return lines.join('\n');
+};
 const renderFollowUp = (followUp) => {
     const must = followUp.mustFixBeforeCutover.length === 0
         ? NONE
@@ -163,6 +225,12 @@ export const buildMigrationReport = (data) => {
     const coerced = renderCoercedSentinels(data.coercedSentinels);
     if (coerced !== null)
         sections.push(coerced);
+    const rebucketed = renderRebucketedRollouts(data.conversionNotes);
+    if (rebucketed !== null)
+        sections.push(rebucketed);
+    const conversionNotes = renderConversionNotes(data.conversionNotes);
+    if (conversionNotes !== null)
+        sections.push(conversionNotes);
     sections.push(renderFollowUp(data.followUp));
     return sections.join('\n\n') + '\n';
 };

package/dist/migrate/push-to-cloud.js

@@ -94,6 +94,7 @@ export const pushMigrationToCloud = async (opts) => {
                     acc.coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
                     acc.duplicateResolutions =
                         resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
+                    const conversionNotes = opts.source.getConversionNotes?.() ?? null;
                     const skippedTotal = (acc.skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
                     const environmentsCount = opts.environments?.length ?? 0;
                     const counts = buildMigrationCounts(livePaths, environmentsCount, skippedTotal);
@@ -102,6 +103,7 @@ export const pushMigrationToCloud = async (opts) => {
                         ...opts.reportData,
                         counts,
                         ...(acc.coercedSentinels ? { coercedSentinels: acc.coercedSentinels } : {}),
+                        ...(conversionNotes && conversionNotes.length > 0 ? { conversionNotes } : {}),
                         ...(acc.droppedOverrides ? { droppedOverrides: acc.droppedOverrides } : {}),
                         ...(acc.duplicateResolutions ? { duplicateResolutions: acc.duplicateResolutions } : {}),
                         ...(acc.skippedConfigs ? { skippedConfigs: acc.skippedConfigs } : {}),

package/dist/migrate/quonfig-target/operators.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared verb: provider clause operator + `negate` flag → Quonfig criterion
+ * operator, or a skip reason.
+ *
+ * This is part of the `quonfig-target/` verb library (plan §3.1, D1) — written
+ * once, consumed by every provider's `translate.ts`. The mapping table and the
+ * negation rules below are LaunchDarkly-shaped today, but the *shape* of the
+ * verb (op + negate → operator | skip) is provider-independent; a second
+ * provider extends the table rather than reinventing the dispatch.
+ */
+/** Quonfig criterion operators — mirrors `OperatorSchema` in app-quonfig's config-schemas.ts. */
+export type QuonfigOperator = 'ALWAYS_TRUE' | 'IN_SEG' | 'IS_NOT_PRESENT' | 'IS_PRESENT' | 'NOT_IN_SEG' | 'PROP_AFTER' | 'PROP_BEFORE' | 'PROP_CONTAINS_ONE_OF' | 'PROP_DOES_NOT_CONTAIN_ONE_OF' | 'PROP_DOES_NOT_END_WITH_ONE_OF' | 'PROP_DOES_NOT_MATCH' | 'PROP_DOES_NOT_START_WITH_ONE_OF' | 'PROP_ENDS_WITH_ONE_OF' | 'PROP_GREATER_THAN' | 'PROP_GREATER_THAN_OR_EQUAL' | 'PROP_IS_NOT_ONE_OF' | 'PROP_IS_ONE_OF' | 'PROP_LESS_THAN' | 'PROP_LESS_THAN_OR_EQUAL' | 'PROP_MATCHES' | 'PROP_SEMVER_EQUAL' | 'PROP_SEMVER_GREATER_THAN' | 'PROP_SEMVER_LESS_THAN' | 'PROP_STARTS_WITH_ONE_OF';
+export type OperatorMapping = {
+    operator: QuonfigOperator;
+} | {
+    reason: string;
+    skip: true;
+};
+/**
+ * Map a LaunchDarkly clause `op` + `negate` to a Quonfig operator.
+ *
+ * Returns `{skip: true, reason}` for clauses v1 cannot honor:
+ *  - negated comparison/date/semver ops (D3)
+ *  - `applicationVersionSupported` (no Quonfig equivalent)
+ *  - any operator not in the LaunchDarkly enum we recognize
+ */
+export declare function mapLaunchDarklyOperator(op: string, negate: boolean): OperatorMapping;

package/dist/migrate/quonfig-target/operators.js

@@ -0,0 +1,71 @@
+/**
+ * Shared verb: provider clause operator + `negate` flag → Quonfig criterion
+ * operator, or a skip reason.
+ *
+ * This is part of the `quonfig-target/` verb library (plan §3.1, D1) — written
+ * once, consumed by every provider's `translate.ts`. The mapping table and the
+ * negation rules below are LaunchDarkly-shaped today, but the *shape* of the
+ * verb (op + negate → operator | skip) is provider-independent; a second
+ * provider extends the table rather than reinventing the dispatch.
+ */
+/**
+ * Operators that have a direct negated form in Quonfig. `negate: true` simply
+ * selects the negated operator — semantics-preserving, always converted.
+ */
+const NEGATABLE = {
+    contains: { negated: 'PROP_DOES_NOT_CONTAIN_ONE_OF', plain: 'PROP_CONTAINS_ONE_OF' },
+    endsWith: { negated: 'PROP_DOES_NOT_END_WITH_ONE_OF', plain: 'PROP_ENDS_WITH_ONE_OF' },
+    in: { negated: 'PROP_IS_NOT_ONE_OF', plain: 'PROP_IS_ONE_OF' },
+    matches: { negated: 'PROP_DOES_NOT_MATCH', plain: 'PROP_MATCHES' },
+    segmentMatch: { negated: 'NOT_IN_SEG', plain: 'IN_SEG' },
+    startsWith: { negated: 'PROP_DOES_NOT_START_WITH_ONE_OF', plain: 'PROP_STARTS_WITH_ONE_OF' },
+};
+/**
+ * Comparison / date / semver operators. Quonfig has no negated form of any of
+ * these (decision D3). `negate: false` converts directly; `negate: true` is
+ * skip + report — an algebraic flip would need a within-rule OR for the
+ * missing-attribute case, which Quonfig cannot express.
+ */
+const COMPARISON_ONLY = {
+    after: 'PROP_AFTER',
+    before: 'PROP_BEFORE',
+    greaterThan: 'PROP_GREATER_THAN',
+    greaterThanOrEqual: 'PROP_GREATER_THAN_OR_EQUAL',
+    lessThan: 'PROP_LESS_THAN',
+    lessThanOrEqual: 'PROP_LESS_THAN_OR_EQUAL',
+    semVerEqual: 'PROP_SEMVER_EQUAL',
+    semVerGreaterThan: 'PROP_SEMVER_GREATER_THAN',
+    semVerLessThan: 'PROP_SEMVER_LESS_THAN',
+};
+/**
+ * Map a LaunchDarkly clause `op` + `negate` to a Quonfig operator.
+ *
+ * Returns `{skip: true, reason}` for clauses v1 cannot honor:
+ *  - negated comparison/date/semver ops (D3)
+ *  - `applicationVersionSupported` (no Quonfig equivalent)
+ *  - any operator not in the LaunchDarkly enum we recognize
+ */
+export function mapLaunchDarklyOperator(op, negate) {
+    const negatable = NEGATABLE[op];
+    if (negatable) {
+        return { operator: negate ? negatable.negated : negatable.plain };
+    }
+    const comparison = COMPARISON_ONLY[op];
+    if (comparison) {
+        if (negate) {
+            return {
+                reason: `negated comparison operator "${op}" — Quonfig has no negated form and no within-rule OR, ` +
+                    `so an algebraic flip is unsafe (missing-attribute trap). Recreate this clause by hand.`,
+                skip: true,
+            };
+        }
+        return { operator: comparison };
+    }
+    if (op === 'applicationVersionSupported') {
+        return {
+            reason: `operator "applicationVersionSupported" has no Quonfig equivalent`,
+            skip: true,
+        };
+    }
+    return { reason: `unrecognized LaunchDarkly operator "${op}"`, skip: true };
+}

package/dist/migrate/quonfig-target/report.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared verb: structured conversion-report accumulator.
+ *
+ * Part of the `quonfig-target/` verb library (plan §3.1, D1). Every
+ * skip/drop/coerce path in a provider's `translate.ts` records a structured
+ * entry here so it lands in `MIGRATION_REPORT.md` — nothing is silently
+ * dropped (plan §5.4).
+ *
+ * The categories below are the LaunchDarkly v1 set; a second provider adds its
+ * own categories. The accumulator itself is provider-independent.
+ */
+export type ConversionNoteCategory = 
+/** A flag/segment that could not be converted at all. */
+'skipped-config'
+/** A rule dropped because a clause's operator has no v1 Quonfig mapping (D3). */
+ | 'skipped-rule'
+/** An individual/context target converted to a leading PROP_IS_ONE_OF rule (lossy — plan §5.4). */
+ | 'individual-target-as-rule'
+/** Prerequisites dropped — no cross-flag dependency operator in Quonfig v1. */
+ | 'dropped-prerequisite'
+/** `privateAttributes` dropped — no Quonfig equivalent. */
+ | 'dropped-private-attribute'
+/** Experiment rollout converted to plain weighted_values; seed/kind dropped. */
+ | 'dropped-experiment-metadata'
+/** Maintainer metadata dropped — Quonfig authorship lives in git history. */
+ | 'dropped-maintainer'
+/** `customProperties` dropped — report-only in v1 (D6). */
+ | 'dropped-custom-properties'
+/** clientSideAvailability mobile-key dimension dropped. */
+ | 'dropped-mobile-key-availability'
+/** A percentage rollout that will re-bucket users post-migration (plan §5.4). */
+ | 'rebucketed-rollout'
+/** A big/synced segment whose membership is not exportable via REST. */
+ | 'unexportable-segment-membership'
+/** An AI Config enumerated but not emitted (out of v1 scope, D9). */
+ | 'ai-config-skipped';
+export interface ConversionNote {
+    category: ConversionNoteCategory;
+    /** Human-readable detail — names the exact thing lost and why. */
+    detail: string;
+    /** Source key the note is about (flag or segment key). */
+    key: string;
+}
+/**
+ * Collects conversion notes during a migration run. A provider source holds
+ * one instance, passes it to every `translate()` call, and surfaces its
+ * contents through the `MigrationSource` reporting accessors.
+ */
+export declare class ConversionReport {
+    private readonly notes;
+    get size(): number;
+    add(category: ConversionNoteCategory, key: string, detail: string): void;
+    /** All notes, in insertion order. */
+    all(): ConversionNote[];
+    /** Notes of one category, in insertion order. */
+    byCategory(category: ConversionNoteCategory): ConversionNote[];
+    isEmpty(): boolean;
+    reset(): void;
+}

package/dist/migrate/quonfig-target/report.js

@@ -0,0 +1,39 @@
+/**
+ * Shared verb: structured conversion-report accumulator.
+ *
+ * Part of the `quonfig-target/` verb library (plan §3.1, D1). Every
+ * skip/drop/coerce path in a provider's `translate.ts` records a structured
+ * entry here so it lands in `MIGRATION_REPORT.md` — nothing is silently
+ * dropped (plan §5.4).
+ *
+ * The categories below are the LaunchDarkly v1 set; a second provider adds its
+ * own categories. The accumulator itself is provider-independent.
+ */
+/**
+ * Collects conversion notes during a migration run. A provider source holds
+ * one instance, passes it to every `translate()` call, and surfaces its
+ * contents through the `MigrationSource` reporting accessors.
+ */
+export class ConversionReport {
+    notes = [];
+    get size() {
+        return this.notes.length;
+    }
+    add(category, key, detail) {
+        this.notes.push({ category, detail, key });
+    }
+    /** All notes, in insertion order. */
+    all() {
+        return [...this.notes];
+    }
+    /** Notes of one category, in insertion order. */
+    byCategory(category) {
+        return this.notes.filter((n) => n.category === category);
+    }
+    isEmpty() {
+        return this.notes.length === 0;
+    }
+    reset() {
+        this.notes.length = 0;
+    }
+}

package/dist/migrate/quonfig-target/ruleset.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared verb: collapse a provider's targeting model into Quonfig's ordered,
+ * first-match-wins rule list.
+ *
+ * Part of the `quonfig-target/` verb library (plan §3.1, D1). The hard part of
+ * every converter is topology translation into Quonfig's specific shape — no
+ * "flag off" toggle, no individual-target primitive, no within-rule OR. These
+ * verbs do the LaunchDarkly collapse; a second provider with a different
+ * topology composes them differently.
+ */
+import type { ConversionReport } from './report.js';
+import { type QuonfigOperator } from './operators.js';
+import { type QuonfigValue, type QuonfigValueType } from './values.js';
+export interface QuonfigCriterion {
+    operator: QuonfigOperator | 'ALWAYS_TRUE';
+    propertyName?: string;
+    valueToMatch?: QuonfigValue;
+}
+export interface QuonfigWeightedValues {
+    type: 'weighted_values';
+    value: {
+        hashByPropertyName: string;
+        weightedValues: Array<{
+            value: QuonfigValue;
+            weight: number;
+        }>;
+    };
+}
+export type QuonfigRuleValue = QuonfigValue | QuonfigWeightedValues;
+export interface QuonfigRule {
+    criteria: QuonfigCriterion[];
+    value: QuonfigRuleValue;
+}
+interface SourceClause {
+    attribute: string;
+    contextKind?: string;
+    negate?: boolean;
+    op: string;
+    values: unknown[];
+}
+interface SourceRollout {
+    bucketBy?: string;
+    contextKind?: string;
+    kind?: string;
+    seed?: number;
+    variations: Array<{
+        variation: number;
+        weight: number;
+    }>;
+}
+interface SourceRule {
+    _id?: string;
+    clauses: SourceClause[];
+    rollout?: SourceRollout;
+    variation?: number;
+}
+interface SourceTarget {
+    contextKind?: string;
+    values: string[];
+    variation: number;
+}
+interface SourceVariationOrRollout {
+    rollout?: SourceRollout;
+    variation?: number;
+}
+interface SourceFlagEnvironment {
+    contextTargets?: SourceTarget[];
+    fallthrough?: SourceVariationOrRollout;
+    offVariation?: number;
+    on: boolean;
+    prerequisites?: Array<{
+        key: string;
+        variation: number;
+    }>;
+    rules?: SourceRule[];
+    targets?: SourceTarget[];
+}
+export interface RulesetContext {
+    report: ConversionReport;
+    /** Source flag/segment key — used for precise report entries. */
+    sourceKey: string;
+    /** The flag's resolved Quonfig value type. */
+    valueType: QuonfigValueType;
+    /** Raw variation values, indexed as the provider indexes them. */
+    variationValues: unknown[];
+}
+/**
+ * LaunchDarkly attribute → Quonfig property name. The context kind becomes a
+ * namespace prefix (plan §5.1: `organization` + `plan` → `organization.plan`),
+ * defaulting to `user`. A nested JSON-pointer attribute (`/address/city`)
+ * becomes a dotted path (`address.city`).
+ */
+export declare function normalizeAttribute(contextKind: string | undefined, attribute: string): string;
+/**
+ * Map one provider clause to a Quonfig criterion, or `null` when the clause's
+ * operator has no v1 mapping (D3 — negated comparisons, applicationVersion…).
+ * A null result means the whole containing rule must be dropped: keeping a
+ * partial AND would silently broaden targeting.
+ */
+export declare function clauseToCriterion(clause: SourceClause, ctx: RulesetContext): QuonfigCriterion | null;
+/**
+ * Build a Quonfig rule from a provider rule's clauses (AND semantics) plus its
+ * served value. Returns `null` when any clause cannot be mapped — the rule is
+ * dropped wholesale and reported, rather than silently broadened.
+ */
+export declare function buildRule(clauses: SourceClause[], value: QuonfigRuleValue, ctx: RulesetContext): QuonfigRule | null;
+/**
+ * Convert a provider rollout to a Quonfig `weighted_values`. The experiment
+ * framing (`kind: "experiment"` + `seed`) is dropped + reported (plan §5.4),
+ * and every rollout is recorded as re-bucketing (LD and Quonfig hash
+ * differently, so post-migration bucket assignments differ).
+ */
+export declare function rolloutToWeightedValues(rollout: SourceRollout, ctx: RulesetContext): QuonfigWeightedValues;
+/** Resolve a `variation`-or-`rollout` pointer (rule served value / fallthrough). */
+export declare function servedValue(voR: SourceVariationOrRollout, ctx: RulesetContext): QuonfigRuleValue;
+/**
+ * Collapse a single LaunchDarkly per-environment flag state into an ordered,
+ * first-match-wins Quonfig rule list.
+ *
+ *  - `on: false` → one ALWAYS_TRUE rule serving the `offVariation` value.
+ *  - `on: true`  → individual/context targets become leading PROP_IS_ONE_OF
+ *    rules; `rules[]` translate in order; `fallthrough` becomes a trailing
+ *    ALWAYS_TRUE rule. Prerequisites are dropped + reported (no Quonfig
+ *    cross-flag dependency operator in v1).
+ */
+export declare function collapseEnvironment(env: SourceFlagEnvironment, ctx: RulesetContext): QuonfigRule[];
+export {};

package/dist/migrate/quonfig-target/ruleset.js

@@ -0,0 +1,192 @@
+/**
+ * Shared verb: collapse a provider's targeting model into Quonfig's ordered,
+ * first-match-wins rule list.
+ *
+ * Part of the `quonfig-target/` verb library (plan §3.1, D1). The hard part of
+ * every converter is topology translation into Quonfig's specific shape — no
+ * "flag off" toggle, no individual-target primitive, no within-rule OR. These
+ * verbs do the LaunchDarkly collapse; a second provider with a different
+ * topology composes them differently.
+ */
+import { mapLaunchDarklyOperator } from './operators.js';
+import { toQuonfigValue } from './values.js';
+const ALWAYS_TRUE = { operator: 'ALWAYS_TRUE' };
+/** Operators whose `valueToMatch` is a `string_list` of every clause value. */
+const STRING_LIST_OPERATORS = new Set([
+    'PROP_CONTAINS_ONE_OF',
+    'PROP_DOES_NOT_CONTAIN_ONE_OF',
+    'PROP_DOES_NOT_END_WITH_ONE_OF',
+    'PROP_DOES_NOT_START_WITH_ONE_OF',
+    'PROP_ENDS_WITH_ONE_OF',
+    'PROP_IS_NOT_ONE_OF',
+    'PROP_IS_ONE_OF',
+    'PROP_STARTS_WITH_ONE_OF',
+]);
+const NUMERIC_OPERATORS = new Set([
+    'PROP_GREATER_THAN',
+    'PROP_GREATER_THAN_OR_EQUAL',
+    'PROP_LESS_THAN',
+    'PROP_LESS_THAN_OR_EQUAL',
+]);
+/**
+ * LaunchDarkly attribute → Quonfig property name. The context kind becomes a
+ * namespace prefix (plan §5.1: `organization` + `plan` → `organization.plan`),
+ * defaulting to `user`. A nested JSON-pointer attribute (`/address/city`)
+ * becomes a dotted path (`address.city`).
+ */
+export function normalizeAttribute(contextKind, attribute) {
+    const kind = contextKind && contextKind.length > 0 ? contextKind : 'user';
+    const dotted = attribute.replace(/^\//, '').replaceAll('/', '.');
+    return `${kind}.${dotted}`;
+}
+/** Build a `valueToMatch` typed value for a non-presence, non-segment clause. */
+function valueToMatchFor(operator, clause, ctx) {
+    if (STRING_LIST_OPERATORS.has(operator)) {
+        return { type: 'string_list', value: clause.values.map(String) };
+    }
+    if (operator === 'IN_SEG' || operator === 'NOT_IN_SEG') {
+        if (clause.values.length > 1) {
+            ctx.report.add('skipped-rule', ctx.sourceKey, `segmentMatch clause listed ${clause.values.length} segments; Quonfig IN_SEG matches one — only "${String(clause.values[0])}" kept, the rest dropped`);
+        }
+        return { type: 'string', value: String(clause.values[0] ?? '') };
+    }
+    if (operator === 'PROP_MATCHES' || operator === 'PROP_DOES_NOT_MATCH') {
+        if (clause.values.length > 1) {
+            ctx.report.add('skipped-rule', ctx.sourceKey, `regex clause listed ${clause.values.length} patterns; Quonfig PROP_MATCHES takes one — only the first kept`);
+        }
+        return { type: 'string', value: String(clause.values[0] ?? '') };
+    }
+    if (NUMERIC_OPERATORS.has(operator)) {
+        const raw = clause.values[0];
+        const num = typeof raw === 'number' ? raw : Number(raw);
+        return { type: Number.isInteger(num) ? 'int' : 'double', value: num };
+    }
+    if (operator === 'PROP_BEFORE' || operator === 'PROP_AFTER') {
+        const raw = clause.values[0];
+        // LD before/after take an epoch-ms number or an RFC3339 string; the SDK's
+        // dateToMillis accepts both, so pass the native shape straight through.
+        return typeof raw === 'number' ? { type: 'int', value: raw } : { type: 'string', value: String(raw) };
+    }
+    // Semver operators — the SDK requires a string value.
+    return { type: 'string', value: String(clause.values[0] ?? '') };
+}
+/**
+ * Map one provider clause to a Quonfig criterion, or `null` when the clause's
+ * operator has no v1 mapping (D3 — negated comparisons, applicationVersion…).
+ * A null result means the whole containing rule must be dropped: keeping a
+ * partial AND would silently broaden targeting.
+ */
+export function clauseToCriterion(clause, ctx) {
+    const mapping = mapLaunchDarklyOperator(clause.op, Boolean(clause.negate));
+    if ('skip' in mapping) {
+        ctx.report.add('skipped-rule', ctx.sourceKey, `clause on "${clause.attribute}" skipped: ${mapping.reason}`);
+        return null;
+    }
+    const { operator } = mapping;
+    const propertyName = normalizeAttribute(clause.contextKind, clause.attribute);
+    const criterion = { operator, propertyName };
+    criterion.valueToMatch = valueToMatchFor(operator, clause, ctx);
+    return criterion;
+}
+/**
+ * Build a Quonfig rule from a provider rule's clauses (AND semantics) plus its
+ * served value. Returns `null` when any clause cannot be mapped — the rule is
+ * dropped wholesale and reported, rather than silently broadened.
+ */
+export function buildRule(clauses, value, ctx) {
+    const criteria = [];
+    for (const clause of clauses) {
+        const criterion = clauseToCriterion(clause, ctx);
+        if (criterion === null)
+            return null;
+        criteria.push(criterion);
+    }
+    // A rule with no clauses matches everyone — represent that as ALWAYS_TRUE.
+    return { criteria: criteria.length > 0 ? criteria : [ALWAYS_TRUE], value };
+}
+/** Resolve a variation index to its typed Quonfig value. */
+function variationValue(index, ctx) {
+    const raw = ctx.variationValues[index];
+    return toQuonfigValue(raw, ctx.valueType);
+}
+/**
+ * Convert a provider rollout to a Quonfig `weighted_values`. The experiment
+ * framing (`kind: "experiment"` + `seed`) is dropped + reported (plan §5.4),
+ * and every rollout is recorded as re-bucketing (LD and Quonfig hash
+ * differently, so post-migration bucket assignments differ).
+ */
+export function rolloutToWeightedValues(rollout, ctx) {
+    if (rollout.kind === 'experiment') {
+        ctx.report.add('dropped-experiment-metadata', ctx.sourceKey, `experiment rollout converted to a plain weighted_values; experiment kind${rollout.seed === undefined ? '' : ` and seed ${rollout.seed}`} dropped`);
+    }
+    const hashByPropertyName = rollout.bucketBy
+        ? normalizeAttribute(rollout.contextKind, rollout.bucketBy)
+        : `${rollout.contextKind && rollout.contextKind.length > 0 ? rollout.contextKind : 'user'}.key`;
+    ctx.report.add('rebucketed-rollout', ctx.sourceKey, `percentage rollout hashed on "${hashByPropertyName}" — LaunchDarkly and Quonfig bucket differently, so users will be re-bucketed`);
+    return {
+        type: 'weighted_values',
+        value: {
+            hashByPropertyName,
+            weightedValues: rollout.variations.map((wv) => ({
+                value: variationValue(wv.variation, ctx),
+                weight: wv.weight,
+            })),
+        },
+    };
+}
+/** Resolve a `variation`-or-`rollout` pointer (rule served value / fallthrough). */
+export function servedValue(voR, ctx) {
+    if (voR.rollout)
+        return rolloutToWeightedValues(voR.rollout, ctx);
+    return variationValue(voR.variation ?? 0, ctx);
+}
+/**
+ * Collapse a single LaunchDarkly per-environment flag state into an ordered,
+ * first-match-wins Quonfig rule list.
+ *
+ *  - `on: false` → one ALWAYS_TRUE rule serving the `offVariation` value.
+ *  - `on: true`  → individual/context targets become leading PROP_IS_ONE_OF
+ *    rules; `rules[]` translate in order; `fallthrough` becomes a trailing
+ *    ALWAYS_TRUE rule. Prerequisites are dropped + reported (no Quonfig
+ *    cross-flag dependency operator in v1).
+ */
+export function collapseEnvironment(env, ctx) {
+    if (!env.on) {
+        return [{ criteria: [ALWAYS_TRUE], value: variationValue(env.offVariation ?? 0, ctx) }];
+    }
+    const rules = [];
+    if (env.prerequisites && env.prerequisites.length > 0) {
+        ctx.report.add('dropped-prerequisite', ctx.sourceKey, `${env.prerequisites.length} prerequisite(s) dropped (${env.prerequisites
+            .map((p) => p.key)
+            .join(', ')}) — Quonfig has no cross-flag dependency operator`);
+    }
+    // Individual + context targets evaluate before rules in LaunchDarkly, so
+    // they become leading rules. Lossy: the LD UI affordance is gone (plan §5.4).
+    const allTargets = [...(env.targets ?? []), ...(env.contextTargets ?? [])];
+    for (const target of allTargets) {
+        if (target.values.length === 0)
+            continue;
+        const kind = target.contextKind && target.contextKind.length > 0 ? target.contextKind : 'user';
+        rules.push({
+            criteria: [
+                {
+                    operator: 'PROP_IS_ONE_OF',
+                    propertyName: `${kind}.key`,
+                    valueToMatch: { type: 'string_list', value: [...target.values] },
+                },
+            ],
+            value: variationValue(target.variation, ctx),
+        });
+        ctx.report.add('individual-target-as-rule', ctx.sourceKey, `${target.values.length} ${kind} target(s) converted to a leading PROP_IS_ONE_OF rule on ${kind}.key`);
+    }
+    for (const rule of env.rules ?? []) {
+        const value = rule.rollout === undefined ? variationValue(rule.variation ?? 0, ctx) : rolloutToWeightedValues(rule.rollout, ctx);
+        const built = buildRule(rule.clauses, value, ctx);
+        if (built !== null)
+            rules.push(built);
+    }
+    if (env.fallthrough) {
+        rules.push({ criteria: [ALWAYS_TRUE], value: servedValue(env.fallthrough, ctx) });
+    }
+    return rules;
+}