@quonfig/cli 0.0.69 → 0.0.71

package/dist/codegen/code-generators/react-typescript-generator.js

@@ -1,5 +1,4 @@
 import { stripIndent } from 'common-tags';
-import camelCase from 'lodash.camelcase';
 import { z } from 'zod';
 import { ZodToTypescriptMapper } from '../language-mappers/zod-to-typescript-mapper.js';
 import { ZodToTypescriptReturnValueMapper } from '../language-mappers/zod-to-typescript-return-value-mapper.js';
@@ -78,17 +77,15 @@ export class ReactTypeScriptGenerator extends BaseTypescriptGenerator {
         return this.configurations().filter((config) => config.configType === 'FEATURE_FLAG' || config.sendToClientSdk === true);
     }
     generateAccessorMethods() {
-        const uniqueMethods = {};
-        const schemaTypes = this.filteredConfigurations().map((config) => {
-            let methodName = camelCase(config.key);
-            // If the method name starts with a digit, prefix it with an underscore to ensure method name is valid
-            if (/^\d/.test(methodName)) {
-                methodName = `_${methodName}`;
-            }
-            if (uniqueMethods[methodName]) {
-                throw new Error(`Method '${methodName}' is already registered. Quonfig key ${config.key} conflicts with '${uniqueMethods[methodName]}'!`);
-            }
-            uniqueMethods[methodName] = config.key;
+        const configs = this.filteredConfigurations();
+        // qfg-hbuy.8: colliding camelCased identifiers get deterministic numeric
+        // suffixes (with a warning) instead of throwing — see the base class. Runs
+        // on the client-side-filtered set, so a collision among server-only keys
+        // does not affect (or warn in) the react output.
+        const { collisions, methodNameByKey } = this.assignAccessorMethodNames(configs.map((c) => c.key));
+        this.warnOnAccessorNameCollisions(collisions);
+        const schemaTypes = configs.map((config) => {
+            const methodName = methodNameByKey.get(config.key);
             if (config.hasFunction) {
                 const returnValue = new ZodToTypescriptReturnValueMapper().resolveType(config.schema);
                 return stripIndent `

package/dist/commands/generate.js

@@ -256,11 +256,13 @@ Example quonfig.config.json:
         }
     }
     resolveGenerator(language, configFile) {
+        // warn (unlike verboseLog) is always visible — identifier-collision dedup
+        // notices (qfg-hbuy.8) must reach the user without --verbose.
         switch (language) {
             case SupportedLanguage.Node:
-                return new NodeTypeScriptGenerator({ configFile, log: this.verboseLog });
+                return new NodeTypeScriptGenerator({ configFile, log: this.verboseLog, warn: (m) => this.warn(m) });
             case SupportedLanguage.React:
-                return new ReactTypeScriptGenerator({ configFile, log: this.verboseLog });
+                return new ReactTypeScriptGenerator({ configFile, log: this.verboseLog, warn: (m) => this.warn(m) });
         }
     }
     resolveLanguage(languageTarget) {

package/dist/commands/verify.js

@@ -35,6 +35,10 @@ export default class Verify extends BaseCommand {
         }
         if (this.jsonEnabled()) {
             if (!result.valid) {
+                // Print the JSON findings BEFORE exiting non-zero. `this.exit()` throws,
+                // so exiting first would swallow the very output `--json` exists to
+                // produce (qfg-ez47). Same order as `migrate doctor`: emit, then exit.
+                this.logJson(result);
                 this.exit(1);
             }
             return result;

package/dist/init/schema.js

@@ -238,9 +238,18 @@ export function storedConfigJsonSchema() {
             key: {
                 type: 'string',
                 minLength: 1,
-                maxLength: 512,
+                // Policy A key rule (qfg-hbuy.9): tightened from the old loose
+                // maxLength:512 + `^[^/\\]+$` to match what the prod qfg-verify hook
+                // (and app-quonfig PolicyAKeySchema) actually enforce, so a file that
+                // validates green against this published schema in a customer's editor
+                // is no longer hard-rejected at push time. Charset `^[A-Za-z0-9._-]+$`,
+                // 200-char cap. (The hook additionally enforces the FS-safety floor —
+                // no leading/trailing dot, no Windows reserved device names — which
+                // JSON Schema's pattern can't express cleanly; the charset + cap are
+                // the parts that fit here.)
+                maxLength: 200,
                 not: { const: 'new' },
-                pattern: '^[^/\\\\]+$',
+                pattern: '^[A-Za-z0-9._-]+$',
                 description: 'Unique identifier. Must match the filename (without .json).',
             },
             type: {

package/dist/migrate/import-state.d.ts

@@ -1,3 +1,4 @@
+import type { KeyPlanData } from './key-rewriter.js';
 export interface ImportState {
     lastProcessedAt?: number | string;
     source: string;
@@ -10,8 +11,8 @@ export declare class CrossSourceError extends Error {
 }
 export declare function writeImportState(outputDir: string, state: ImportState): void;
 export declare function readImportState(outputDir: string): ImportState | null;
-export declare function writeKeyPlan(outputDir: string, keys: Record<string, string>): void;
+export declare function writeKeyPlan(outputDir: string, plan: KeyPlanData): void;
 /** The persisted plan, or null when absent/unreadable (treat as first run). */
-export declare function readKeyPlan(outputDir: string): null | Record<string, string>;
+export declare function readKeyPlan(outputDir: string): KeyPlanData | null;
 export declare function assertSourceMatches(outputDir: string, requestedSource: string): void;
 export declare function removeQfFromGitignore(outputDir: string): void;

package/dist/migrate/import-state.js

@@ -38,13 +38,19 @@ export function readImportState(outputDir) {
 function keyPlanPath(outputDir) {
     return path.join(outputDir, '.qf', 'key-plan.json');
 }
-export function writeKeyPlan(outputDir, keys) {
+function sortRecord(record) {
+    const sorted = {};
+    for (const source of Object.keys(record).sort())
+        sorted[source] = record[source];
+    return sorted;
+}
+export function writeKeyPlan(outputDir, plan) {
     const filePath = keyPlanPath(outputDir);
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const sorted = {};
-    for (const source of Object.keys(keys).sort())
-        sorted[source] = keys[source];
-    const serialized = { keys: sorted, version: 1 };
+    const keys = sortRecord(plan.keys);
+    const serialized = Object.keys(plan.segmentKeys).length > 0
+        ? { keys, segmentKeys: sortRecord(plan.segmentKeys), version: 2 }
+        : { keys, version: 1 };
     fs.writeFileSync(filePath, JSON.stringify(serialized, null, 2) + '\n', 'utf8');
 }
 /** The persisted plan, or null when absent/unreadable (treat as first run). */
@@ -56,10 +62,17 @@ export function readKeyPlan(outputDir) {
         const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
         if (typeof parsed?.keys !== 'object' || parsed.keys === null || Array.isArray(parsed.keys))
             return null;
-        const out = {};
+        const out = { keys: {}, segmentKeys: {} };
         for (const [source, final] of Object.entries(parsed.keys)) {
             if (typeof final === 'string')
-                out[source] = final;
+                out.keys[source] = final;
+        }
+        // Version-1 files have no segmentKeys — read as empty (backward compat).
+        if (typeof parsed.segmentKeys === 'object' && parsed.segmentKeys !== null && !Array.isArray(parsed.segmentKeys)) {
+            for (const [source, final] of Object.entries(parsed.segmentKeys)) {
+                if (typeof final === 'string')
+                    out.segmentKeys[source] = final;
+            }
         }
         return out;
     }

package/dist/migrate/key-rewriter.d.ts

@@ -6,22 +6,51 @@ export interface KeyRewrite {
     /** The original source-system key. */
     source: string;
 }
+/**
+ * qfg-hbuy.10: source-side key namespaces. LaunchDarkly flags and segments are
+ * SEPARATE key namespaces, so a project can legitimately carry a flag and a
+ * segment with the same source key. Quonfig keys are globally unique across
+ * type trees, so the two need distinct finals: the flag (default namespace)
+ * keeps the clean name and the segment is deterministically suffixed
+ * `-segment`. Everything that isn't a segment plans in `default`.
+ */
+export type KeyNamespace = 'default' | 'segment';
+/**
+ * The complete persisted key plan (.qf/key-plan.json): the default-namespace
+ * map plus the segment-namespace map. `segmentKeys` only carries segments that
+ * COLLIDED with a default-namespace key and were suffixed — a lone segment
+ * plans in the default flow and stays in `keys`, exactly as before
+ * qfg-hbuy.10, so existing version-1 plans keep resolving unchanged.
+ */
+export interface KeyPlanData {
+    keys: Record<string, string>;
+    segmentKeys: Record<string, string>;
+}
 export declare function resetKeyRewriter(): void;
 /**
- * Seed the rewriter with the complete source->final map persisted by previous
+ * Seed the rewriter with the complete source->final maps persisted by previous
  * runs. Every persisted final is immediately marked taken (case-insensitively)
  * so keys planned later this run can never claim one. Call after
  * `resetKeyRewriter()` and before `planKeyRewrites()` — `planKeyRewritesForChanges`
  * does this ordering for you.
  */
-export declare function seedPersistedKeyPlan(keys: Readonly<Record<string, string>>): void;
+export declare function seedPersistedKeyPlan(plan: Readonly<KeyPlanData>): void;
 /**
- * Pre-pass: compute the final key for every source key. Three passes, each
- * sorted so every assignment is deterministic and independent of the order
- * changes were fetched in:
+ * qfg-hbuy.12: seed the rewriter with keys that ALREADY EXIST in the target
+ * workspace (push mode clones it; local mode may reuse a pulled dir). Call
+ * after `seedPersistedKeyPlan()` — persisted mappings stay authoritative,
+ * workspace seeding only fills in what the plan doesn't cover. See
+ * `existingLower` for the exact/case-variant semantics.
+ */
+export declare function seedExistingWorkspaceKeys(keys: Iterable<string>): void;
+/**
+ * Pre-pass: compute the final key for every source key. Sorted passes so every
+ * assignment is deterministic and independent of the order changes were
+ * fetched in:
  *
  *   0. Keys mapped by a PREVIOUS run keep their persisted final verbatim (see
  *      `seedPersistedKeyPlan`) — full and delta runs must resolve identically.
+ *      Applies to both namespaces.
  *   1. Keys that are ALREADY fully valid (sanitize is an identity: they pass
  *      Policy A and the FS-floor) claim their own names FIRST and are never
  *      renamed to make room for sanitized junk — customer code calling
@@ -32,33 +61,55 @@ export declare function seedPersistedKeyPlan(keys: Readonly<Record<string, strin
  *      and the other is suffixed.
  *   2. Keys that needed sanitizing then disambiguate AROUND the valid ones
  *      (-2, -3, ...).
+ *   3. qfg-hbuy.10: SEGMENTS whose source key is also claimed by the default
+ *      namespace this run (an LD flag and segment sharing one key) get the
+ *      deterministic `-segment` suffix, disambiguating around every name
+ *      assigned above — a suffixed segment can never steal a different valid
+ *      key's name. Segments with no such collision plan in the default flow
+ *      (passes 0-2) and keep their clean names.
  */
-export declare function planKeyRewrites(sourceKeys: Iterable<string>): void;
+export declare function planKeyRewrites(sourceKeys: Iterable<string>, segmentSourceKeys?: Iterable<string>): void;
 /**
  * The final key for `sourceKey`. Uses the planned map when present, then the
  * PERSISTED map (a delta run's flag can reference a segment that was migrated
  * in the full run but is absent from the delta's change set), else a pure
  * sanitize (no disambiguation, no mutation) as a safe fallback.
+ *
+ * Segment definitions and by-key segment references (IN_SEG/NOT_IN_SEG) pass
+ * `namespace: 'segment'`: the segment-namespace maps are consulted first, then
+ * resolution falls back to the default namespace — a segment that never
+ * collided with a flag plans in the default flow and lives there.
+ */
+export declare function resolveKey(sourceKey: string, namespace?: KeyNamespace): string;
+/**
+ * qfg-hbuy.11: the final key for `sourceKey` ONLY when this run (or a
+ * persisted plan) actually mapped it, else null. For rewriting by-key
+ * REFERENCES whose target may legitimately live outside the import — a
+ * config's `schemaKey` or a value's `decryptWith` can point at a pre-existing
+ * workspace key the migrator does not own; those must be left untouched
+ * rather than speculatively sanitized (default namespace only — both fields
+ * reference configs/schemas, never segments).
  */
-export declare function resolveKey(sourceKey: string): string;
+export declare function resolveMappedKey(sourceKey: string): null | string;
 /** Every key that was actually rewritten (conforming keys are omitted). */
 export declare function getKeyRewrites(): KeyRewrite[];
 /**
- * The COMPLETE source->final map to persist to `.qf/key-plan.json`: every key
+ * The COMPLETE source->final maps to persist to `.qf/key-plan.json`: every key
  * planned this run (unchanged ones included) merged over everything persisted
  * by previous runs, sorted by source key for stable on-disk diffs.
  */
-export declare function getFullKeyPlan(): Record<string, string>;
+export declare function getFullKeyPlan(): KeyPlanData;
 /**
  * Run-level pre-pass: reset the rewriter, seed the persisted plan from any
  * previous run, and plan every source key BEFORE any change is translated, so
  * both key-definition and by-key reference sites resolve against the same
- * fully-disambiguated map. Structurally typed on `{key?}` to stay decoupled
- * from LegacyChange.
+ * fully-disambiguated map. Structurally typed on `{key?, keyNamespace?}` to
+ * stay decoupled from LegacyChange.
  */
 export declare function planKeyRewritesForChanges(changes: ReadonlyArray<{
     key?: string;
-}>, persistedKeys?: Readonly<Record<string, string>>): void;
+    keyNamespace?: string;
+}>, persistedKeys?: Readonly<KeyPlanData>, existingKeys?: Iterable<string>): void;
 /**
  * `--strict-keys` escape hatch: refuse to migrate if any source key would need
  * rewriting, so a customer who requires byte-identical keys can clean up the
@@ -72,11 +123,16 @@ export declare class StrictKeysError extends Error {
  * Plan the rewrites for a run and, when `strict`, throw `StrictKeysError` if any
  * key would be rewritten. Call once at the top of each migrate orchestrator
  * before translating. `persistedKeys` (from `readKeyPlan`) makes previously
- * mapped keys resolve exactly as they did on the run that mapped them.
+ * mapped keys resolve exactly as they did on the run that mapped them;
+ * `existingKeys` (qfg-hbuy.12: the keys already on disk in the target
+ * workspace) makes case-variant collisions rename deterministically instead
+ * of aborting at the verify gate, while byte-equal matches keep overwriting.
  */
 export declare function preflightKeyRewrites(changes: ReadonlyArray<{
     key?: string;
+    keyNamespace?: string;
 }>, opts?: {
-    persistedKeys?: Readonly<Record<string, string>>;
+    existingKeys?: Iterable<string>;
+    persistedKeys?: Readonly<KeyPlanData>;
     strict?: boolean;
 }): void;

package/dist/migrate/key-rewriter.js

@@ -22,53 +22,109 @@
  * unit calls to a source's path builders stay referentially transparent.
  */
 import { sanitizePolicyAKey } from './key-sanitize.js';
-const state = { bySource: new Map(), persisted: new Map(), takenLower: new Map() };
+const state = {
+    bySource: new Map(),
+    bySourceSegment: new Map(),
+    existingLower: new Map(),
+    persisted: new Map(),
+    persistedSegment: new Map(),
+    takenLower: new Map(),
+};
 export function resetKeyRewriter() {
     state.bySource = new Map();
+    state.bySourceSegment = new Map();
+    state.existingLower = new Map();
     state.persisted = new Map();
+    state.persistedSegment = new Map();
     state.takenLower = new Map();
 }
 /**
- * Seed the rewriter with the complete source->final map persisted by previous
+ * Seed the rewriter with the complete source->final maps persisted by previous
  * runs. Every persisted final is immediately marked taken (case-insensitively)
  * so keys planned later this run can never claim one. Call after
  * `resetKeyRewriter()` and before `planKeyRewrites()` — `planKeyRewritesForChanges`
  * does this ordering for you.
  */
-export function seedPersistedKeyPlan(keys) {
-    for (const [sourceKey, final] of Object.entries(keys)) {
+export function seedPersistedKeyPlan(plan) {
+    for (const [sourceKey, final] of Object.entries(plan.keys)) {
         state.persisted.set(sourceKey, final);
         state.takenLower.set(final.toLowerCase(), sourceKey);
     }
+    for (const [sourceKey, final] of Object.entries(plan.segmentKeys)) {
+        state.persistedSegment.set(sourceKey, final);
+        state.takenLower.set(final.toLowerCase(), sourceKey);
+    }
+}
+/**
+ * qfg-hbuy.12: seed the rewriter with keys that ALREADY EXIST in the target
+ * workspace (push mode clones it; local mode may reuse a pulled dir). Call
+ * after `seedPersistedKeyPlan()` — persisted mappings stay authoritative,
+ * workspace seeding only fills in what the plan doesn't cover. See
+ * `existingLower` for the exact/case-variant semantics.
+ */
+export function seedExistingWorkspaceKeys(keys) {
+    for (const key of keys) {
+        const lower = key.toLowerCase();
+        if (!state.existingLower.has(lower))
+            state.existingLower.set(lower, key);
+    }
+}
+/** Append `suffix` to `base`, truncating `base` so the result stays <= 200 chars. */
+function withSuffix(base, suffix) {
+    const room = 200 - suffix.length;
+    return (base.length > room ? base.slice(0, room) : base) + suffix;
+}
+/**
+ * Is `candidate` unavailable? Keys claimed this run / by the persisted plan
+ * (`takenLower`) always block. Keys that merely EXIST in the target workspace
+ * block case-variants and — when `allowExactExistingMatch` is false — even
+ * byte-equal candidates: a key claiming its OWN name may overwrite its
+ * existing file (re-migration), but a disambiguation suffix must never land
+ * on an unrelated existing key (qfg-hbuy.12).
+ */
+function isTaken(candidate, allowExactExistingMatch) {
+    const lower = candidate.toLowerCase();
+    if (state.takenLower.has(lower))
+        return true;
+    const existing = state.existingLower.get(lower);
+    if (existing === undefined)
+        return false;
+    return allowExactExistingMatch ? existing !== candidate : true;
 }
-/** Find the first case-insensitively-free variant of `base` (base, base-2, ...). */
+/** Find the first free variant of `base` (base, base-2, ...). */
 function disambiguate(base) {
-    if (!state.takenLower.has(base.toLowerCase()))
+    if (!isTaken(base, true))
         return base;
     for (let n = 2;; n++) {
-        const suffix = `-${n}`;
-        const room = 200 - suffix.length;
-        const candidate = (base.length > room ? base.slice(0, room) : base) + suffix;
-        if (!state.takenLower.has(candidate.toLowerCase()))
+        const candidate = withSuffix(base, `-${n}`);
+        if (!isTaken(candidate, false))
             return candidate;
     }
 }
-/** Disambiguate `base`, record the mapping, and mark the final taken. */
-function assignFinal(sourceKey, base, sanitizeReasons) {
+/** Disambiguate `base`, record the mapping in `map`, and mark the final taken. */
+function assignFinal(map, sourceKey, base, sanitizeReasons) {
     const final = disambiguate(base);
     const reasons = [...sanitizeReasons];
-    if (final !== base)
-        reasons.push('appended a numeric suffix to keep the key unique');
-    state.bySource.set(sourceKey, { final, reasons, source: sourceKey });
+    if (final !== base) {
+        // Name the blocker when it was a case-variant key already in the target
+        // workspace (qfg-hbuy.12) — that report line is the customer's cue that
+        // the import collided with something they created outside the migration.
+        const existing = state.existingLower.get(base.toLowerCase());
+        reasons.push(existing !== undefined && existing !== base && !state.takenLower.has(base.toLowerCase())
+            ? `renamed: the target workspace already has "${existing}", which differs only by case`
+            : 'appended a numeric suffix to keep the key unique');
+    }
+    map.set(sourceKey, { final, reasons, source: sourceKey });
     state.takenLower.set(final.toLowerCase(), sourceKey);
 }
 /**
- * Pre-pass: compute the final key for every source key. Three passes, each
- * sorted so every assignment is deterministic and independent of the order
- * changes were fetched in:
+ * Pre-pass: compute the final key for every source key. Sorted passes so every
+ * assignment is deterministic and independent of the order changes were
+ * fetched in:
  *
  *   0. Keys mapped by a PREVIOUS run keep their persisted final verbatim (see
  *      `seedPersistedKeyPlan`) — full and delta runs must resolve identically.
+ *      Applies to both namespaces.
  *   1. Keys that are ALREADY fully valid (sanitize is an identity: they pass
  *      Policy A and the FS-floor) claim their own names FIRST and are never
  *      renamed to make room for sanitized junk — customer code calling
@@ -79,9 +135,24 @@ function assignFinal(sourceKey, base, sanitizeReasons) {
  *      and the other is suffixed.
  *   2. Keys that needed sanitizing then disambiguate AROUND the valid ones
  *      (-2, -3, ...).
+ *   3. qfg-hbuy.10: SEGMENTS whose source key is also claimed by the default
+ *      namespace this run (an LD flag and segment sharing one key) get the
+ *      deterministic `-segment` suffix, disambiguating around every name
+ *      assigned above — a suffixed segment can never steal a different valid
+ *      key's name. Segments with no such collision plan in the default flow
+ *      (passes 0-2) and keep their clean names.
  */
-export function planKeyRewrites(sourceKeys) {
-    const fresh = [...new Set(sourceKeys)].sort().filter((k) => !state.bySource.has(k));
+export function planKeyRewrites(sourceKeys, segmentSourceKeys = []) {
+    const defaultKeys = [...new Set(sourceKeys)];
+    const freshSegments = [...new Set(segmentSourceKeys)].sort().filter((k) => !state.bySourceSegment.has(k));
+    // Split segment keys: only a segment whose source key is ALSO claimed by the
+    // default namespace this run — or that a previous run already namespaced
+    // (sticky, so re-runs stay stable) — needs its own namespace. Everything
+    // else plans in the default flow, exactly as before qfg-hbuy.10.
+    const defaultKeySet = new Set([...defaultKeys, ...state.bySource.keys()]);
+    const scopedSegments = freshSegments.filter((k) => state.persistedSegment.has(k) || defaultKeySet.has(k));
+    const plainSegments = freshSegments.filter((k) => !state.persistedSegment.has(k) && !defaultKeySet.has(k));
+    const fresh = [...new Set([...defaultKeys, ...plainSegments])].sort().filter((k) => !state.bySource.has(k));
     // Pass 0: previously-mapped keys resolve to their persisted final, always.
     const unpersisted = [];
     for (const sourceKey of fresh) {
@@ -97,6 +168,22 @@ export function planKeyRewrites(sourceKeys) {
         state.bySource.set(sourceKey, { final: persistedFinal, reasons, source: sourceKey });
         state.takenLower.set(persistedFinal.toLowerCase(), sourceKey);
     }
+    // Pass 0 (segment namespace): persisted segment mappings are just as
+    // authoritative — record them so the report and full plan carry them.
+    const unpersistedSegments = [];
+    for (const sourceKey of scopedSegments) {
+        const persistedFinal = state.persistedSegment.get(sourceKey);
+        if (persistedFinal === undefined) {
+            unpersistedSegments.push(sourceKey);
+            continue;
+        }
+        state.bySourceSegment.set(sourceKey, {
+            final: persistedFinal,
+            reasons: ['kept the segment key assigned by a previous import run'],
+            source: sourceKey,
+        });
+        state.takenLower.set(persistedFinal.toLowerCase(), sourceKey);
+    }
     // Pass 1: already-valid keys claim their own names.
     const needsSanitizing = [];
     for (const sourceKey of unpersisted) {
@@ -105,12 +192,23 @@ export function planKeyRewrites(sourceKeys) {
             needsSanitizing.push({ sanitized, sourceKey });
         }
         else {
-            assignFinal(sourceKey, sourceKey, []);
+            assignFinal(state.bySource, sourceKey, sourceKey, []);
         }
     }
     // Pass 2: sanitized keys disambiguate around them.
     for (const { sanitized, sourceKey } of needsSanitizing) {
-        assignFinal(sourceKey, sanitized.key, sanitized.reasons);
+        assignFinal(state.bySource, sourceKey, sanitized.key, sanitized.reasons);
+    }
+    // Pass 3 (qfg-hbuy.10): colliding segments take the '-segment' suffix,
+    // disambiguating around every name assigned above.
+    for (const sourceKey of unpersistedSegments) {
+        const sanitized = sanitizePolicyAKey(sourceKey);
+        const base = withSuffix(sanitized.key, '-segment');
+        const reasons = [
+            ...sanitized.reasons,
+            `suffixed "-segment": a feature flag in this import shares the source key "${sourceKey}"`,
+        ];
+        assignFinal(state.bySourceSegment, sourceKey, base, reasons);
     }
 }
 /**
@@ -118,8 +216,21 @@ export function planKeyRewrites(sourceKeys) {
  * PERSISTED map (a delta run's flag can reference a segment that was migrated
  * in the full run but is absent from the delta's change set), else a pure
  * sanitize (no disambiguation, no mutation) as a safe fallback.
+ *
+ * Segment definitions and by-key segment references (IN_SEG/NOT_IN_SEG) pass
+ * `namespace: 'segment'`: the segment-namespace maps are consulted first, then
+ * resolution falls back to the default namespace — a segment that never
+ * collided with a flag plans in the default flow and lives there.
  */
-export function resolveKey(sourceKey) {
+export function resolveKey(sourceKey, namespace = 'default') {
+    if (namespace === 'segment') {
+        const plannedSegment = state.bySourceSegment.get(sourceKey);
+        if (plannedSegment)
+            return plannedSegment.final;
+        const persistedSegment = state.persistedSegment.get(sourceKey);
+        if (persistedSegment !== undefined)
+            return persistedSegment;
+    }
     const planned = state.bySource.get(sourceKey);
     if (planned)
         return planned.final;
@@ -128,36 +239,70 @@ export function resolveKey(sourceKey) {
         return persisted;
     return sanitizePolicyAKey(sourceKey).key;
 }
+/**
+ * qfg-hbuy.11: the final key for `sourceKey` ONLY when this run (or a
+ * persisted plan) actually mapped it, else null. For rewriting by-key
+ * REFERENCES whose target may legitimately live outside the import — a
+ * config's `schemaKey` or a value's `decryptWith` can point at a pre-existing
+ * workspace key the migrator does not own; those must be left untouched
+ * rather than speculatively sanitized (default namespace only — both fields
+ * reference configs/schemas, never segments).
+ */
+export function resolveMappedKey(sourceKey) {
+    const planned = state.bySource.get(sourceKey);
+    if (planned)
+        return planned.final;
+    return state.persisted.get(sourceKey) ?? null;
+}
 /** Every key that was actually rewritten (conforming keys are omitted). */
 export function getKeyRewrites() {
-    return [...state.bySource.values()].filter((r) => r.final !== r.source);
+    return [...state.bySource.values(), ...state.bySourceSegment.values()].filter((r) => r.final !== r.source);
 }
-/**
- * The COMPLETE source->final map to persist to `.qf/key-plan.json`: every key
- * planned this run (unchanged ones included) merged over everything persisted
- * by previous runs, sorted by source key for stable on-disk diffs.
- */
-export function getFullKeyPlan() {
-    const merged = new Map(state.persisted);
-    for (const [source, rewrite] of state.bySource)
+/** Persisted map merged under this run's planned finals, sorted by source key. */
+function sortMerged(persisted, planned) {
+    const merged = new Map(persisted);
+    for (const [source, rewrite] of planned)
         merged.set(source, rewrite.final);
     const out = {};
     for (const source of [...merged.keys()].sort())
         out[source] = merged.get(source);
     return out;
 }
+/**
+ * The COMPLETE source->final maps to persist to `.qf/key-plan.json`: every key
+ * planned this run (unchanged ones included) merged over everything persisted
+ * by previous runs, sorted by source key for stable on-disk diffs.
+ */
+export function getFullKeyPlan() {
+    return {
+        keys: sortMerged(state.persisted, state.bySource),
+        segmentKeys: sortMerged(state.persistedSegment, state.bySourceSegment),
+    };
+}
 /**
  * Run-level pre-pass: reset the rewriter, seed the persisted plan from any
  * previous run, and plan every source key BEFORE any change is translated, so
  * both key-definition and by-key reference sites resolve against the same
- * fully-disambiguated map. Structurally typed on `{key?}` to stay decoupled
- * from LegacyChange.
+ * fully-disambiguated map. Structurally typed on `{key?, keyNamespace?}` to
+ * stay decoupled from LegacyChange.
  */
-export function planKeyRewritesForChanges(changes, persistedKeys) {
+export function planKeyRewritesForChanges(changes, persistedKeys, existingKeys) {
     resetKeyRewriter();
     if (persistedKeys)
         seedPersistedKeyPlan(persistedKeys);
-    planKeyRewrites(changes.flatMap((c) => (typeof c.key === 'string' ? [c.key] : [])));
+    if (existingKeys)
+        seedExistingWorkspaceKeys(existingKeys);
+    const defaultKeys = [];
+    const segmentKeys = [];
+    for (const change of changes) {
+        if (typeof change.key !== 'string')
+            continue;
+        if (change.keyNamespace === 'segment')
+            segmentKeys.push(change.key);
+        else
+            defaultKeys.push(change.key);
+    }
+    planKeyRewrites(defaultKeys, segmentKeys);
 }
 /**
  * `--strict-keys` escape hatch: refuse to migrate if any source key would need
@@ -178,10 +323,13 @@ export class StrictKeysError extends Error {
  * Plan the rewrites for a run and, when `strict`, throw `StrictKeysError` if any
  * key would be rewritten. Call once at the top of each migrate orchestrator
  * before translating. `persistedKeys` (from `readKeyPlan`) makes previously
- * mapped keys resolve exactly as they did on the run that mapped them.
+ * mapped keys resolve exactly as they did on the run that mapped them;
+ * `existingKeys` (qfg-hbuy.12: the keys already on disk in the target
+ * workspace) makes case-variant collisions rename deterministically instead
+ * of aborting at the verify gate, while byte-equal matches keep overwriting.
  */
 export function preflightKeyRewrites(changes, opts) {
-    planKeyRewritesForChanges(changes, opts?.persistedKeys);
+    planKeyRewritesForChanges(changes, opts?.persistedKeys, opts?.existingKeys);
     if (opts?.strict) {
         const rewrites = getKeyRewrites();
         if (rewrites.length > 0)

package/dist/migrate/local-write.d.ts

@@ -110,4 +110,14 @@ export declare const buildAuditFinalCommit: (opts: BuildAuditFinalCommitOptions)
  * only the last slice.
  */
 export declare const collectLivePathsOnDisk: (dir: string) => string[];
+/**
+ * qfg-hbuy.12: every key ALREADY present in the target workspace on disk —
+ * used to seed the key rewriter so an import that case-collides with an
+ * existing key (incoming `Foo`, workspace `foo`) renames deterministically
+ * instead of aborting at the verify gate, while a byte-equal match keeps
+ * today's silent-overwrite re-migration behavior. Scans every validated
+ * content dir (uniqueness is pooled per workspace, so schemas-protected/
+ * counts too, even though the migrator never writes there).
+ */
+export declare const collectExistingWorkspaceKeys: (dir: string) => string[];
 export {};