@quonfig/cli 0.0.65 → 0.0.67

package/dist/migrate/key-rewriter.js

@@ -0,0 +1,190 @@
+/**
+ * Per-run key rewriter for `qfg migrate` (qfg-6na9.3).
+ *
+ * `sanitizePolicyAKey` (key-sanitize.ts) fixes ONE key in isolation. This module
+ * turns that into a workspace-consistent map so that:
+ *
+ *   1. two distinct source keys that sanitize to the same key (`foo bar` and
+ *      `foo-bar` -> `foo-bar`), or that collide case-insensitively (`Foo`/`foo`,
+ *      which the FS-safety floor hard-rejects), are DISAMBIGUATED deterministically
+ *      (`-2`, `-3`, ...) instead of silently clobbering one another; and
+ *   2. a key and every by-key REFERENCE to it (a flag's `IN_SEG`/`NOT_IN_SEG`
+ *      rule pointing at a segment key) resolve to the SAME final key — so a
+ *      renamed segment never leaves a dangling targeting reference.
+ *
+ * Usage: `resetKeyRewriter()` then `planKeyRewrites(allSourceKeys)` BEFORE
+ * translating any change, then `resolveKey(sourceKey)` at every key-definition
+ * and reference site. `getKeyRewrites()` drives MIGRATION_REPORT.md + the
+ * machine-readable key map.
+ *
+ * `resolveKey` on a key that was never planned falls back to a pure
+ * `sanitizePolicyAKey` (NO disambiguation, NO state mutation) so that direct
+ * 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() };
+export function resetKeyRewriter() {
+    state.bySource = new Map();
+    state.persisted = new Map();
+    state.takenLower = new Map();
+}
+/**
+ * Seed the rewriter with the complete source->final map 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)) {
+        state.persisted.set(sourceKey, final);
+        state.takenLower.set(final.toLowerCase(), sourceKey);
+    }
+}
+/** Find the first case-insensitively-free variant of `base` (base, base-2, ...). */
+function disambiguate(base) {
+    if (!state.takenLower.has(base.toLowerCase()))
+        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()))
+            return candidate;
+    }
+}
+/** Disambiguate `base`, record the mapping, and mark the final taken. */
+function assignFinal(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 });
+    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:
+ *
+ *   0. Keys mapped by a PREVIOUS run keep their persisted final verbatim (see
+ *      `seedPersistedKeyPlan`) — full and delta runs must resolve identically.
+ *   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
+ *      get("my-flag") must keep resolving to the same flag even when a source
+ *      key like "my flag" sanitizes to the same name. If two VALID keys
+ *      collide case-insensitively ("Foo"/"foo" — a genuine source conflict the
+ *      FS-floor hard-rejects), the lexicographically-first one keeps its name
+ *      and the other is suffixed.
+ *   2. Keys that needed sanitizing then disambiguate AROUND the valid ones
+ *      (-2, -3, ...).
+ */
+export function planKeyRewrites(sourceKeys) {
+    const fresh = [...new Set(sourceKeys)].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) {
+        const persistedFinal = state.persisted.get(sourceKey);
+        if (persistedFinal === undefined) {
+            unpersisted.push(sourceKey);
+            continue;
+        }
+        const sanitized = sanitizePolicyAKey(sourceKey);
+        const reasons = persistedFinal === sanitized.key
+            ? [...sanitized.reasons]
+            : [...sanitized.reasons, 'kept the key assigned by a previous import run'];
+        state.bySource.set(sourceKey, { final: persistedFinal, reasons, source: sourceKey });
+        state.takenLower.set(persistedFinal.toLowerCase(), sourceKey);
+    }
+    // Pass 1: already-valid keys claim their own names.
+    const needsSanitizing = [];
+    for (const sourceKey of unpersisted) {
+        const sanitized = sanitizePolicyAKey(sourceKey);
+        if (sanitized.changed) {
+            needsSanitizing.push({ sanitized, sourceKey });
+        }
+        else {
+            assignFinal(sourceKey, sourceKey, []);
+        }
+    }
+    // Pass 2: sanitized keys disambiguate around them.
+    for (const { sanitized, sourceKey } of needsSanitizing) {
+        assignFinal(sourceKey, sanitized.key, sanitized.reasons);
+    }
+}
+/**
+ * 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.
+ */
+export function resolveKey(sourceKey) {
+    const planned = state.bySource.get(sourceKey);
+    if (planned)
+        return planned.final;
+    const persisted = state.persisted.get(sourceKey);
+    if (persisted !== undefined)
+        return persisted;
+    return sanitizePolicyAKey(sourceKey).key;
+}
+/** Every key that was actually rewritten (conforming keys are omitted). */
+export function getKeyRewrites() {
+    return [...state.bySource.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)
+        merged.set(source, rewrite.final);
+    const out = {};
+    for (const source of [...merged.keys()].sort())
+        out[source] = merged.get(source);
+    return out;
+}
+/**
+ * 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.
+ */
+export function planKeyRewritesForChanges(changes, persistedKeys) {
+    resetKeyRewriter();
+    if (persistedKeys)
+        seedPersistedKeyPlan(persistedKeys);
+    planKeyRewrites(changes.flatMap((c) => (typeof c.key === 'string' ? [c.key] : [])));
+}
+/**
+ * `--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
+ * source first instead of accepting the (reported) rewrites.
+ */
+export class StrictKeysError extends Error {
+    rewrites;
+    constructor(rewrites) {
+        super(`--strict-keys: ${rewrites.length} source key(s) do not conform to Policy A and would be rewritten:\n` +
+            rewrites.map((r) => `  "${r.source}" -> "${r.final}" (${r.reasons.join('; ')})`).join('\n') +
+            `\nRename the key(s) in the source system and re-run, or drop --strict-keys to accept the rewrites.`);
+        this.rewrites = rewrites;
+        this.name = 'StrictKeysError';
+    }
+}
+/**
+ * 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.
+ */
+export function preflightKeyRewrites(changes, opts) {
+    planKeyRewritesForChanges(changes, opts?.persistedKeys);
+    if (opts?.strict) {
+        const rewrites = getKeyRewrites();
+        if (rewrites.length > 0)
+            throw new StrictKeysError(rewrites);
+    }
+}

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

@@ -0,0 +1,13 @@
+declare const POLICY_A_KEY_RE: RegExp;
+export interface KeySanitizeResult {
+    /** True when `key` differs from `raw`. */
+    changed: boolean;
+    /** The Policy-A-valid key (== `raw` when nothing needed changing). */
+    key: string;
+    /** Human-readable list of the transforms that fired (empty when unchanged). */
+    reasons: string[];
+}
+export declare function sanitizePolicyAKey(raw: string): KeySanitizeResult;
+/** True when a key already satisfies Policy A (no sanitizing needed). */
+export declare function isPolicyAConformant(key: string): boolean;
+export { POLICY_A_KEY_RE };

package/dist/migrate/key-sanitize.js

@@ -0,0 +1,108 @@
+/**
+ * Deterministic single-key Policy A sanitizer for `qfg migrate` (qfg-6na9.3).
+ *
+ * Migrated keys enter a workspace via `cloneAndStackPush` -> the app-gitea
+ * pre-receive `qfg-verify` hook, which hard-rejects FS-floor violations
+ * (qfg-6na9.4) and — after the warn->error soak — will hard-reject Policy A
+ * charset violations too (qfg-6na9.6). To keep migrations from (a) aborting on
+ * a floor violation or (b) seeding a permanently non-conforming key that
+ * freezes the customer once .6 flips, we rewrite every imported key so it 100%
+ * conforms to Policy A (project/plans/26-06-tighter-naming.md).
+ *
+ * This function is a PURE, deterministic single-key transform. It preserves as
+ * much of the original as possible (case included — Policy A allows mixed case)
+ * and is a strict no-op for already-conforming keys, so LaunchDarkly imports
+ * (LD keys are already `[A-Za-z0-9._-]`) produce zero rewrites.
+ *
+ * Cross-key concerns — collisions (two source keys sanitizing to the same key)
+ * and case-insensitive uniqueness — are layered on top by the per-run key
+ * rewriter (`key-rewriter.ts`), which also drives the report. Keep those
+ * concerns OUT of here so this stays trivially testable and referentially
+ * transparent (both the key-definition side and the reference side can call it
+ * independently and get the same answer).
+ */
+/* eslint-disable unicorn/better-regex -- keep the explicit [A-Za-z0-9._-] charset
+   greppable and byte-for-byte aligned with app-quonfig's PolicyAKeySchema and the
+   plan (project/plans/26-06-tighter-naming.md), rather than the equivalent [\w.-]. */
+import { createHash } from 'node:crypto';
+const RESERVED_DEVICE_RE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+const POLICY_A_KEY_RE = /^[A-Za-z0-9._-]+$/;
+const MAX_KEY_LEN = 200;
+/** First 8 hex chars of sha1(raw) — a stable, collision-resistant suffix. */
+function shortHash(raw) {
+    return createHash('sha1').update(raw).digest('hex').slice(0, 8);
+}
+export function sanitizePolicyAKey(raw) {
+    const reasons = [];
+    let k = raw;
+    // 0. Trim leading/trailing whitespace FIRST, so an edge space is dropped (a
+    //    trailing space is an FS-floor violation — stripped by Windows) rather
+    //    than surviving as a cosmetic dash via the charset replacement below.
+    const wsTrimmed = k.replaceAll(/^\s+|\s+$/g, '');
+    if (wsTrimmed !== k) {
+        k = wsTrimmed;
+        reasons.push('trimmed leading/trailing whitespace');
+    }
+    // 1. Path separators -> dot. Preserves the dotted-hierarchy intent (a `/` or
+    //    `\` in a source key becomes a namespace dot, matching the historical
+    //    normalizeKey) rather than a lossy dash.
+    if (/[/\\]/.test(k)) {
+        k = k.replaceAll(/[/\\]+/g, '.');
+        reasons.push('replaced path separators (/ or \\) with "."');
+    }
+    // 2. Any remaining char outside the Policy A charset -> single dash.
+    if (/[^A-Za-z0-9._-]/.test(k)) {
+        k = k.replaceAll(/[^A-Za-z0-9._-]+/g, '-');
+        reasons.push('replaced disallowed characters with "-"');
+    }
+    // 3. Trim leading/trailing DOTS only. A leading dot is silently skipped by
+    //    the loader/verify; a trailing dot is stripped by Windows — both are
+    //    floor violations. Leading/trailing DASHES are fully legal under Policy A
+    //    and the floor, so they are deliberately NOT trimmed: this function must
+    //    be an identity on every already-valid key (otherwise --strict-keys
+    //    aborts on keys the platform accepts, and a valid key gets "rewritten").
+    const trimmed = k.replaceAll(/^\.+/g, '').replaceAll(/\.+$/g, '');
+    if (trimmed !== k) {
+        k = trimmed;
+        reasons.push('trimmed leading/trailing dots');
+    }
+    // 4. Windows reserved device name on the FIRST dot-segment (the segment the
+    //    floor checks) -> suffix "_" so `con` -> `con_`, `nul.foo` -> `nul_.foo`.
+    const segs = k.split('.');
+    if (segs.length > 0 && RESERVED_DEVICE_RE.test(segs[0])) {
+        segs[0] = `${segs[0]}_`;
+        k = segs.join('.');
+        reasons.push('escaped Windows reserved device name');
+    }
+    // 5. The reserved whole-key "new".
+    if (k === 'new') {
+        k = 'new-key';
+        reasons.push('escaped reserved key "new"');
+    }
+    // 6. Empty — or reduced to pure separator junk — after sanitizing (e.g. the
+    //    source key was all disallowed chars, so every char became a dash). The
+    //    `k !== raw` guard keeps this an identity on ALREADY-valid separator-only
+    //    keys like "-" (legal under Policy A); only keys we transformed into
+    //    meaningless separators get the stable placeholder, so distinct junk
+    //    source keys ("!!!" vs "???") stay distinguishable.
+    if (k.length === 0) {
+        k = `key-${shortHash(raw)}`;
+        reasons.push('key was empty after sanitizing');
+    }
+    else if (k !== raw && !/[A-Za-z0-9_]/.test(k)) {
+        k = `key-${shortHash(raw)}`;
+        reasons.push('key had no letters, numbers, or underscores after sanitizing');
+    }
+    // 7. Length cap 200 (ASCII-only == byte length). Stable hash suffix keeps two
+    //    long keys sharing a 200-char prefix from colliding.
+    if (k.length > MAX_KEY_LEN) {
+        k = `${k.slice(0, MAX_KEY_LEN - 9)}-${shortHash(raw)}`;
+        reasons.push(`truncated to ${MAX_KEY_LEN} characters`);
+    }
+    return { changed: k !== raw, key: k, reasons };
+}
+/** True when a key already satisfies Policy A (no sanitizing needed). */
+export function isPolicyAConformant(key) {
+    return !sanitizePolicyAKey(key).changed;
+}
+export { POLICY_A_KEY_RE };

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

@@ -24,6 +24,8 @@ export interface ApplyLocalMigrationOptions {
      */
     reportData: MigrationReportData;
     source: MigrationSource;
+    /** qfg-6na9.3: `--strict-keys` — refuse to migrate if any key would be rewritten. */
+    strictKeys?: boolean;
 }
 export interface ApplyLocalMigrationResult {
     /** `'initialized'` if we had to `git init` the target, `'reused'` if it was already a repo. */

package/dist/migrate/local-write.js

@@ -1,6 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { removeQfFromGitignore, writeImportState } from './import-state.js';
+import { readKeyPlan, removeQfFromGitignore, writeImportState, writeKeyPlan } from './import-state.js';
+import { getFullKeyPlan, getKeyRewrites, preflightKeyRewrites } from './key-rewriter.js';
 import { deriveFollowUpFromConversionNotes, writeMigrationReport } from './migration-report.js';
 import { detectDuplicateKeys } from './sources/launch/translate.js';
 import { MIGRATOR_IDENTITY, stackCommits } from '../util/clone-and-stack-push.js';
@@ -181,6 +182,15 @@ export const buildMigrationCommitMessage = (source, counts) => {
 export const applyLocalMigration = async (opts) => {
     const branch = opts.branch ?? 'main';
     const author = opts.author ?? MIGRATOR_IDENTITY;
+    // qfg-6na9.3: plan Policy A key rewrites over ALL changes up front (run-level,
+    // not per-commit) so key-def and reference sites resolve identically, then
+    // enforce --strict-keys before writing anything. Mappings persisted by a
+    // previous run (.qf/key-plan.json) are authoritative so a delta run cannot
+    // replan a subset and land on different finals.
+    preflightKeyRewrites(opts.changes, {
+        persistedKeys: readKeyPlan(opts.localDir) ?? undefined,
+        strict: opts.strictKeys,
+    });
     if (opts.fullHistory && !opts.source.getCommitMeta) {
         throw new Error(`--full-summary requires the source to provide per-change author + date + summary, but \`${opts.source.name}\` does not. ` +
             `Drop --full-summary or use a source (e.g. launch) that supports it.`);
@@ -195,6 +205,7 @@ export const applyLocalMigration = async (opts) => {
     const { livePaths, resolutions: resolutionEntries } = writeQuonfigFiles(opts.localDir, opts.changes, opts.source);
     removeQfFromGitignore(opts.localDir);
     writeImportState(opts.localDir, opts.importState);
+    writeKeyPlan(opts.localDir, getFullKeyPlan());
     const droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
     const skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
     const coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
@@ -207,6 +218,7 @@ export const applyLocalMigration = async (opts) => {
     const reportData = {
         ...opts.reportData,
         counts,
+        keyRewrites: getKeyRewrites(),
         ...(environmentMap && environmentMap.length > 0 ? { environmentMap } : {}),
         followUp: deriveFollowUpFromConversionNotes(opts.reportData.followUp, conversionNotes ?? undefined),
         ...(coercedSentinels ? { coercedSentinels } : {}),
@@ -341,11 +353,13 @@ export const buildAuditFinalCommit = (opts) => ({
         const duplicateResolutions = resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
         removeQfFromGitignore(dir);
         writeImportState(dir, opts.importState);
+        writeKeyPlan(dir, getFullKeyPlan());
         const skippedTotal = (skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
         const counts = buildMigrationCounts(livePaths, opts.environments.length, skippedTotal);
         const reportData = {
             ...opts.reportData,
             counts,
+            keyRewrites: getKeyRewrites(),
             ...(environmentMap && environmentMap.length > 0 ? { environmentMap } : {}),
             followUp: deriveFollowUpFromConversionNotes(opts.reportData.followUp, conversionNotes ?? undefined),
             ...(coercedSentinels ? { coercedSentinels } : {}),

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

@@ -1,4 +1,5 @@
 import type { IdentifierMap } from './identifier-map.js';
+import type { KeyRewrite } from './key-rewriter.js';
 import type { ConversionNote } from './quonfig-target/report.js';
 import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolutionSummary, EnvironmentMapEntry, SkippedConfigSummary } from './source.js';
 export type { EnvironmentMapEntry } from './source.js';
@@ -61,6 +62,13 @@ export interface MigrationReportData {
     environmentMap: EnvironmentMapEntry[];
     followUp: FollowUpChecklist;
     identifierMap: IdentifierMap;
+    /**
+     * qfg-6na9.3: source keys the migrator rewrote so the workspace is 100%
+     * Policy-A conformant (bad charset, FS-floor, or collision). The renamed key
+     * is what the customer's SDK code must now look up. Null/empty when every
+     * source key already conformed (e.g. every LaunchDarkly import).
+     */
+    keyRewrites?: KeyRewrite[] | null;
     lossyMappings: LossyMapping[];
     /**
      * qfg-l8uz: source maintainerId → email pairs. Rendered as a sub-table on
@@ -97,4 +105,10 @@ export declare const buildMigrationReport: (data: MigrationReportData) => string
  * `bare-path-diff.ts` excludes it — no server change needed.
  */
 export declare const migrationReportPath: (outputDir: string) => string;
+/**
+ * qfg-6na9.3: machine-readable `source -> quonfig` key map, next to the report
+ * under `.qf/` (excluded from the push, like MIGRATION_REPORT.md). Lets a
+ * customer script the SDK-lookup updates for renamed keys.
+ */
+export declare const keyMapPath: (outputDir: string) => string;
 export declare const writeMigrationReport: (outputDir: string, data: MigrationReportData) => string;

package/dist/migrate/migration-report.js

@@ -110,6 +110,23 @@ const renderDuplicateResolutions = (resolved) => {
     }
     return lines.join('\n');
 };
+const renderKeyRewrites = (rewrites) => {
+    if (!rewrites || rewrites.length === 0)
+        return null;
+    const lines = [
+        '## Rewritten keys (ACTION REQUIRED)',
+        '',
+        `The migrator rewrote **${rewrites.length}** source key(s) that Quonfig does not allow verbatim (Policy A: letters, numbers, \`.\`, \`-\`, \`_\`; 200 chars max; no leading dot) or that collided with another key. **The Quonfig key is what your SDK code must now look up** — update any \`get("...")\` / \`variation("...")\` call that used the old name. A machine-readable map is also written to \`.qf/key-map.json\`.`,
+        '',
+        '| Source key | Quonfig key | Why |',
+        '| --- | --- | --- |',
+    ];
+    const sorted = [...rewrites].sort((a, b) => a.source.localeCompare(b.source));
+    for (const r of sorted) {
+        lines.push(`| \`${r.source}\` | \`${r.final}\` | ${r.reasons.join('; ')} |`);
+    }
+    return lines.join('\n');
+};
 const FLAGSMITH_ENV_BUCKET_LABEL = {
     '_all-envs': 'Override rows (all environments)',
     '_cross-env': 'Cross-environment value-type divergence (no single env owns this)',
@@ -541,6 +558,9 @@ export const buildMigrationReport = (data) => {
     const dropped = renderDroppedOverrides(data.droppedOverrides);
     if (dropped !== null)
         sections.push(dropped);
+    const keyRewrites = renderKeyRewrites(data.keyRewrites);
+    if (keyRewrites !== null)
+        sections.push(keyRewrites);
     const resolved = renderDuplicateResolutions(data.duplicateResolutions);
     if (resolved !== null)
         sections.push(resolved);
@@ -577,9 +597,27 @@ export const buildMigrationReport = (data) => {
  * `bare-path-diff.ts` excludes it — no server change needed.
  */
 export const migrationReportPath = (outputDir) => path.join(outputDir, '.qf', 'MIGRATION_REPORT.md');
+/**
+ * qfg-6na9.3: machine-readable `source -> quonfig` key map, next to the report
+ * under `.qf/` (excluded from the push, like MIGRATION_REPORT.md). Lets a
+ * customer script the SDK-lookup updates for renamed keys.
+ */
+export const keyMapPath = (outputDir) => path.join(outputDir, '.qf', 'key-map.json');
 export const writeMigrationReport = (outputDir, data) => {
     const filePath = migrationReportPath(outputDir);
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, buildMigrationReport(data), 'utf8');
+    if (data.keyRewrites && data.keyRewrites.length > 0) {
+        fs.writeFileSync(keyMapPath(outputDir), JSON.stringify({
+            rewrites: data.keyRewrites.map((r) => ({ final: r.final, reasons: r.reasons, source: r.source })),
+            source: data.source,
+        }, null, 2) + '\n', 'utf8');
+    }
+    else {
+        // key-map.json describes ONE run's rewrites. A later run with zero
+        // rewrites must not leave a stale map from a previous run lying around
+        // implying those keys were rewritten by this run.
+        fs.rmSync(keyMapPath(outputDir), { force: true });
+    }
     return filePath;
 };

package/dist/migrate/push-to-cloud.d.ts

@@ -41,6 +41,8 @@ export interface PushMigrationToCloudOptions {
      */
     reportData: MigrationReportData;
     source: MigrationSource;
+    /** qfg-6na9.3: `--strict-keys` — refuse to migrate if any key would be rewritten. */
+    strictKeys?: boolean;
 }
 export interface PushMigrationToCloudResult extends CloneAndStackPushResult {
     coercedSentinels: CoercedSentinelSummary | null;

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

@@ -1,7 +1,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { removeQfFromGitignore, writeImportState } from './import-state.js';
+import { readKeyPlan, removeQfFromGitignore, writeImportState, writeKeyPlan } from './import-state.js';
 import { buildAuditFinalCommit, buildAuditPerChangeCommits, buildMigrationCommitMessage, buildMigrationCounts, writeQuonfigFiles, } from './local-write.js';
+import { getFullKeyPlan, getKeyRewrites, preflightKeyRewrites } from './key-rewriter.js';
 import { deriveFollowUpFromConversionNotes, writeMigrationReport } from './migration-report.js';
 import { cloneAndStackPush, } from '../util/clone-and-stack-push.js';
 import { formatResult, validateWorkspace } from '../verify/validate.js';
@@ -55,6 +56,17 @@ export const pushMigrationToCloud = async (opts) => {
         throw new Error(`--full-summary requires the source to provide per-change author + date + summary, but \`${opts.source.name}\` does not. ` +
             `Drop --full-summary or use a source (e.g. launch) that supports it.`);
     }
+    // qfg-6na9.3: plan Policy A key rewrites over ALL changes up front (run-level,
+    // not per-commit) so key-def and reference sites resolve identically, then
+    // enforce --strict-keys before any clone/commit/push. Mappings persisted by a
+    // previous run (.qf/key-plan.json in the reused clone) are authoritative so a
+    // delta run cannot replan a subset and land on different finals. (When the
+    // clone is fresh, the plan only comes down WITH the clone — the collapsed
+    // commit's apply() re-plans below once it can read the cloned .qf/.)
+    preflightKeyRewrites(opts.changes, {
+        persistedKeys: readKeyPlan(opts.localDir) ?? undefined,
+        strict: opts.strictKeys,
+    });
     const acc = {
         coercedSentinels: null,
         droppedOverrides: null,
@@ -85,10 +97,19 @@ export const pushMigrationToCloud = async (opts) => {
             {
                 message: () => computedCommitMessage,
                 async apply(dir) {
+                    // Re-plan now that the clone exists: a FRESH clone of a previously
+                    // migrated workspace delivers .qf/key-plan.json only at this point
+                    // (the pre-clone preflight above couldn't see it), and the
+                    // persisted mappings must win before any file is written.
+                    preflightKeyRewrites(opts.changes, {
+                        persistedKeys: readKeyPlan(dir) ?? undefined,
+                        strict: opts.strictKeys,
+                    });
                     mergeEnvsIfPresent(dir);
                     const { livePaths, resolutions: resolutionEntries } = writeQuonfigFiles(dir, opts.changes, opts.source);
                     removeQfFromGitignore(dir);
                     writeImportState(dir, opts.importState);
+                    writeKeyPlan(dir, getFullKeyPlan());
                     acc.droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
                     acc.skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
                     acc.coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
@@ -104,6 +125,7 @@ export const pushMigrationToCloud = async (opts) => {
                     const reportData = {
                         ...opts.reportData,
                         counts,
+                        keyRewrites: getKeyRewrites(),
                         ...(environmentMap && environmentMap.length > 0 ? { environmentMap } : {}),
                         followUp: deriveFollowUpFromConversionNotes(opts.reportData.followUp, conversionNotes ?? undefined),
                         ...(acc.coercedSentinels ? { coercedSentinels: acc.coercedSentinels } : {}),

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

@@ -8,6 +8,7 @@
  * verbs do the LaunchDarkly collapse; a second provider with a different
  * topology composes them differently.
  */
+import { resolveKey } from '../key-rewriter.js';
 import { mapLaunchDarklyOperator } from './operators.js';
 import { toQuonfigValue } from './values.js';
 const ALWAYS_TRUE = { operator: 'ALWAYS_TRUE' };
@@ -48,7 +49,10 @@ function valueToMatchFor(operator, clause, ctx) {
         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] ?? '') };
+        // qfg-6na9.3: this value is a referenced segment KEY — resolve it through
+        // the per-run rewriter so a sanitized/disambiguated segment key stays in
+        // sync with the IN_SEG rules pointing at it (no dangling targeting).
+        return { type: 'string', value: resolveKey(String(clause.values[0] ?? '')) };
     }
     if (operator === 'PROP_MATCHES' || operator === 'PROP_DOES_NOT_MATCH') {
         if (clause.values.length > 1) {

package/dist/migrate/sources/flagsmith/translate.js

@@ -15,6 +15,7 @@
  * mutable state. Report accumulation flows through the `ConversionReport`
  * argument supplied by the caller (the `flagsmith.ts` source).
  */
+import { resolveKey } from '../../key-rewriter.js';
 import { inferValueType, toQuonfigValue } from '../../quonfig-target/values.js';
 const ALWAYS_TRUE = { operator: 'ALWAYS_TRUE' };
 /** Flagsmith identity-override rule keys context attributes under this propertyName. */
@@ -33,8 +34,12 @@ export function flagOutputPath(name) {
 export function segmentOutputPath(name) {
     return `segments/${normalizeKey(name)}.json`;
 }
+// qfg-6na9.3: resolve every key through the per-run key rewriter so imported
+// keys 100% conform to Policy A (charset + FS-floor). Used for the segment/flag
+// key field AND the output path; the matching IN_SEG reference below resolves
+// the same source string, so a rewritten segment key never dangles its rules.
 function normalizeKey(key) {
-    return key.replaceAll('/', '.');
+    return resolveKey(key);
 }
 /** Env name → Quonfig env id slug (matches the source-module slugifier). */
 function slugifyEnvName(name) {
@@ -662,7 +667,10 @@ function buildSegmentOverrideRule(segov, segmentName, bundle, ctx) {
         criteria: [
             {
                 operator: 'IN_SEG',
-                valueToMatch: { type: 'string', value: segmentName },
+                // qfg-6na9.3: resolve the referenced segment key through the same
+                // rewriter as the segment's own key def, so a sanitized/disambiguated
+                // segment key stays in sync here (no dangling targeting).
+                valueToMatch: { type: 'string', value: resolveKey(segmentName) },
             },
         ],
         value,

package/dist/migrate/sources/launch/translate.d.ts

@@ -12,10 +12,12 @@ export declare function slugify(value: string): string;
 export declare function isLegacyLogLevel(type: string): boolean;
 export declare function normalizeLogLevelKey(key: string): string;
 /**
- * qfg-qhk1: Quonfig keys cannot contain `/` — keys are stored as flat dotted
- * filenames, and a `/` in a source key would create a nested directory tree
- * (data-loss-on-tombstone, cross-key collisions). Normalize `/` to `.` so the
- * destination is always flat.
+ * qfg-qhk1 + qfg-6na9.3: resolve keys through the per-run key rewriter so the
+ * destination is always flat AND 100% Policy-A conformant (charset + FS-floor,
+ * with collision disambiguation). Launch keys are dotted identifiers, so this is
+ * a no-op in the common case; an odd key still gets made safe, and the matching
+ * IN_SEG reference (resolveSegmentRef, below) resolves the same source string so
+ * a rewritten segment key never dangles its rules.
  */
 export declare function normalizeKey(key: string): string;
 /**