@quonfig/cli 0.0.64 → 0.0.66

package/dist/migrate/key-rewriter.js

@@ -0,0 +1,109 @@
+/**
+ * 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(), takenLower: new Map() };
+export function resetKeyRewriter() {
+    state.bySource = new Map();
+    state.takenLower = new Map();
+}
+/** 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;
+    }
+}
+/**
+ * Pre-pass: compute the final key for every source key. Sorted first so the
+ * assignment of the un-suffixed base name on a collision is deterministic and
+ * independent of the order changes were fetched in.
+ */
+export function planKeyRewrites(sourceKeys) {
+    for (const sourceKey of [...new Set(sourceKeys)].sort()) {
+        if (state.bySource.has(sourceKey))
+            continue;
+        const san = sanitizePolicyAKey(sourceKey);
+        const final = disambiguate(san.key);
+        const reasons = [...san.reasons];
+        if (final !== san.key)
+            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);
+    }
+}
+/**
+ * The final key for `sourceKey`. Uses the planned map when present, else a pure
+ * sanitize (no disambiguation, no mutation) as a safe fallback.
+ */
+export function resolveKey(sourceKey) {
+    const planned = state.bySource.get(sourceKey);
+    return planned ? planned.final : 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);
+}
+/**
+ * Run-level pre-pass: reset the rewriter 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) {
+    resetKeyRewriter();
+    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.
+ */
+export function preflightKeyRewrites(changes, opts) {
+    planKeyRewritesForChanges(changes);
+    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,88 @@
+/**
+ * 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;
+    // 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 separators. A leading dot is silently skipped by
+    //    the loader/verify; a trailing dot or space is stripped by Windows. A
+    //    leading/trailing dash is merely cosmetic but trimmed for tidiness.
+    const trimmed = k.replaceAll(/^[.-]+/g, '').replaceAll(/[.-]+$/g, '');
+    if (trimmed !== k) {
+        k = trimmed;
+        reasons.push('trimmed leading/trailing separators');
+    }
+    // 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 after sanitizing (e.g. the source key was all disallowed chars).
+    if (k.length === 0) {
+        k = `key-${shortHash(raw)}`;
+        reasons.push('key was empty 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 { 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,10 @@ 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.
+    preflightKeyRewrites(opts.changes, { 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.`);
@@ -207,6 +212,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 } : {}),
@@ -346,6 +352,7 @@ export const buildAuditFinalCommit = (opts) => ({
         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,21 @@ 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');
+    }
     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

@@ -2,6 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
 import { buildAuditFinalCommit, buildAuditPerChangeCommits, buildMigrationCommitMessage, buildMigrationCounts, writeQuonfigFiles, } from './local-write.js';
+import { 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,10 @@ 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.
+    preflightKeyRewrites(opts.changes, { strict: opts.strictKeys });
     const acc = {
         coercedSentinels: null,
         droppedOverrides: null,
@@ -104,6 +109,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;
 /**

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

@@ -1,4 +1,5 @@
 import { zodToJsonSchema } from './zod-to-json-schema.js';
+import { resolveKey } from '../../key-rewriter.js';
 /**
  * Thrown by transformConfig when the source config is structurally invalid
  * (e.g. variant/valueType mismatch) and the migrator cannot produce a valid
@@ -24,13 +25,29 @@ export function normalizeLogLevelKey(key) {
     return key.startsWith('log-level.') ? key : `log-level.${key}`;
 }
 /**
- * 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 function normalizeKey(key) {
-    return key.replaceAll('/', '.');
+    return resolveKey(key);
+}
+/**
+ * qfg-6na9.3: an IN_SEG/NOT_IN_SEG criterion's `valueToMatch` holds a referenced
+ * segment KEY (not an arbitrary value) — resolve it through the same rewriter as
+ * the segment's own key definition so the two stay in sync.
+ */
+function resolveSegmentRef(valueToMatch) {
+    if (!valueToMatch || typeof valueToMatch !== 'object')
+        return;
+    const v = valueToMatch;
+    if (typeof v.value === 'string')
+        v.value = resolveKey(v.value);
+    else if (Array.isArray(v.value))
+        v.value = v.value.map((x) => (typeof x === 'string' ? resolveKey(x) : x));
 }
 /**
  * qfg-l18w / qfg-0q1f: Operators Quonfig accepts in rule criteria. Mirrors
@@ -202,6 +219,9 @@ function normalizeRules(rules, configKey, path) {
                 const c = crit;
                 if (c.valueToMatch) {
                     normalizeLaunchValue(c.valueToMatch, configKey, `${path}[${i}].criteria[${j}].valueToMatch`);
+                    if (c.operator === 'IN_SEG' || c.operator === 'NOT_IN_SEG') {
+                        resolveSegmentRef(c.valueToMatch);
+                    }
                 }
             }
         }

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

@@ -8,16 +8,19 @@
  * variants, per-environment state → `environments[]`, the gap dispositions of
  * plan §5.4.
  */
+import { resolveKey } from '../../key-rewriter.js';
 import { clauseToCriterion, collapseEnvironment, } from '../../quonfig-target/ruleset.js';
 import { inferFlagValueType, toQuonfigValue } from '../../quonfig-target/values.js';
 const ALWAYS_TRUE = { operator: 'ALWAYS_TRUE' };
 /**
- * LaunchDarkly keys are already flat and URL-safe, but normalize `/` → `.`
- * defensively so a key can never create a nested directory tree (matches the
- * flat-path contract `local-write.ts` enforces).
+ * qfg-6na9.3: resolve keys through the per-run key rewriter for Policy A
+ * conformance. LD keys are already `[A-Za-z0-9._-]`, so this is a strict no-op
+ * in practice — wired for uniformity + future-proofing (an odd imported key
+ * would still be made safe, and stay in sync with any IN_SEG reference to it,
+ * which resolves through `ruleset.ts`).
  */
 function normalizeKey(key) {
-    return key.replaceAll('/', '.');
+    return resolveKey(key);
 }
 /** Environment keys are LD slugs already; lowercase + hyphenate to be safe. */
 function slugifyEnvKey(key) {

package/dist/util/policy-a-key.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Policy A key rule, HARD-enforced at `qfg create` time client-side (qfg-6na9.2)
+ * so a bad key fails fast before the network round-trip. This is a deliberate,
+ * hand-kept mirror of app-quonfig `src/lib/domain/config-schemas.ts`
+ * `PolicyAKeySchema` — the two MUST move together (see
+ * project/plans/26-06-tighter-naming.md, "Decision: Policy A"):
+ *
+ *   - charset `^[A-Za-z0-9._-]+$` (uppercase IS allowed; case-insensitive
+ *     collision is a separate verify/create-handler check, not here),
+ *   - 1..200 chars (ASCII-only, so char length == byte length),
+ *   - not the reserved key `"new"`,
+ *   - no leading dot (a `.beta.json` config is silently skipped by the loader
+ *     and `qfg verify`).
+ *
+ * NOTE the layering: this is the create boundary (hard). The general charset is
+ * a *warning* in `qfg verify` (`src/verify/validate.ts`, qfg-6na9.5) during the
+ * warn->error soak, and the FS-safety floor there is already hard (qfg-6na9.4).
+ * Keep the messages aligned with app-quonfig's for a consistent UX.
+ */
+export declare const POLICY_A_KEY_RE: RegExp;
+/**
+ * Returns a human-readable error message for a key that violates Policy A, or
+ * `null` if the key is valid. First failing rule wins (matches the order Zod
+ * evaluates the refinements in app-quonfig).
+ */
+export declare function policyAKeyError(key: string): string | null;

package/dist/util/policy-a-key.js

@@ -0,0 +1,42 @@
+/**
+ * Policy A key rule, HARD-enforced at `qfg create` time client-side (qfg-6na9.2)
+ * so a bad key fails fast before the network round-trip. This is a deliberate,
+ * hand-kept mirror of app-quonfig `src/lib/domain/config-schemas.ts`
+ * `PolicyAKeySchema` — the two MUST move together (see
+ * project/plans/26-06-tighter-naming.md, "Decision: Policy A"):
+ *
+ *   - charset `^[A-Za-z0-9._-]+$` (uppercase IS allowed; case-insensitive
+ *     collision is a separate verify/create-handler check, not here),
+ *   - 1..200 chars (ASCII-only, so char length == byte length),
+ *   - not the reserved key `"new"`,
+ *   - no leading dot (a `.beta.json` config is silently skipped by the loader
+ *     and `qfg verify`).
+ *
+ * NOTE the layering: this is the create boundary (hard). The general charset is
+ * a *warning* in `qfg verify` (`src/verify/validate.ts`, qfg-6na9.5) during the
+ * warn->error soak, and the FS-safety floor there is already hard (qfg-6na9.4).
+ * Keep the messages aligned with app-quonfig's for a consistent UX.
+ */
+// Kept as the explicit char class (not the `[\w.-]` the linter suggests) so it
+// is a byte-for-byte mirror of app-quonfig's PolicyAKeySchema and greppable
+// across both sources of truth — see the module doc above.
+// eslint-disable-next-line unicorn/better-regex
+export const POLICY_A_KEY_RE = /^[A-Za-z0-9._-]+$/;
+/**
+ * Returns a human-readable error message for a key that violates Policy A, or
+ * `null` if the key is valid. First failing rule wins (matches the order Zod
+ * evaluates the refinements in app-quonfig).
+ */
+export function policyAKeyError(key) {
+    if (key.length === 0)
+        return 'Key is required';
+    if (key.length > 200)
+        return 'Key must be 200 characters or fewer';
+    if (key === 'new')
+        return 'Key cannot be "new"';
+    if (!POLICY_A_KEY_RE.test(key))
+        return 'Key can only contain letters, numbers, dots, dashes, and underscores';
+    if (key.startsWith('.'))
+        return 'Key cannot start with a dot';
+    return null;
+}

package/dist/verify/validate.d.ts

@@ -9,7 +9,8 @@
  *  - Valid JSON
  *  - Schema compliance (StoredConfigSchema from Zod)
  *  - Key matches filename
- *  - Key constraints (1-512 chars, no slashes, not "new")
+ *  - Key constraints (1-200 chars, no slashes, not "new", FS-safety floor)
+ *  - Case-insensitive key uniqueness (no Foo/foo collisions)
  *  - Config type matches directory
  *  - Segment constraints (valueType=bool, sendToClientSdk=false)
  *  - Log level constraints (valueType=log_level)
@@ -55,4 +56,5 @@ export declare function validateWorkspace(workspaceDir: string): ValidationResul
  * Used by the pre-receive hook which reads files from git objects.
  */
 export declare function validateFileMap(files: Map<string, string>): ValidationResult;
+export declare function validateKey(key: string, file: string, issues: ValidationIssue[]): void;
 export declare function formatResult(result: ValidationResult): string;