primitive-admin 1.1.0 → 1.2.0-alpha.1

package/dist/src/commands/sync.js

@@ -1629,8 +1629,8 @@ export function serializeBlobBucket(bucket, logger) {
  *
  * EXACT extraction of the inline builder shared by the existing-update and
  * 409-adopt branches — do NOT "clean up" the truthiness checks on the access
- * model. The server treats `preset` and `accessPolicy` as mutually exclusive,
- * only clears `ruleSetId` when a preset/accessPolicy is also present, and
+ * model. The server treats `preset` and `ruleSetId` as mutually exclusive,
+ * only clears `ruleSetId` when a preset is also present, and
  * refuses to leave a bucket with no access model or a blank name — so those
  * fields are not clearable. `bucketKey` and `ttlTier` are immutable and never
  * sent. Both call sites must go through this helper so their field sets never
@@ -1655,12 +1655,6 @@ export function buildBlobBucketUpdatePayload(bucket) {
             description: tomlOwned,
         },
     });
-    // `accessPolicy` is the pre-#1020 spelling of `preset`, declared in the
-    // definition's `tomlOnlyKeys`: an unmigrated file still pushes its access
-    // model, and the server takes at most one of the two.
-    if (!updatePayload.preset && bucket?.accessPolicy) {
-        updatePayload.accessPolicy = bucket.accessPolicy;
-    }
     for (const key of Object.keys(updatePayload)) {
         if (updatePayload[key] === undefined)
             delete updatePayload[key];
@@ -1698,12 +1692,9 @@ const PROMPT_CONFIG_DEFAULT_STATUS = fieldServerDefault(PROMPT_CONFIG_TABLE, "st
  * first-wins rule: making the file's meaning depend on entry order is the kind
  * of implicit behavior this issue exists to remove, and silently picking one
  * would let the repo claim something the server does not do.
- *
- * `isActive` is accepted as a legacy spelling — the create leg read it before
- * pull ever wrote a marker, so a hand-authored file carrying it keeps working.
  */
 export function promptActiveConfigName(configs) {
-    const marked = (configs || []).filter((c) => c?.active === true || c?.isActive === true);
+    const marked = (configs || []).filter((c) => c?.active === true);
     if (marked.length > 1) {
         throw new Error(`Only one [[configs]] entry may set active = true; found ${marked.length} ` +
             `(${marked.map((c) => c.name).join(", ")}).`);
@@ -1764,9 +1755,6 @@ export function buildBlobBucketCreatePayload(key, bucket) {
             },
         }),
     };
-    if (!payload.preset && bucket?.accessPolicy) {
-        payload.accessPolicy = bucket.accessPolicy;
-    }
     for (const field of Object.keys(payload)) {
         if (payload[field] === undefined)
             delete payload[field];
@@ -4012,7 +4000,7 @@ export function parseDatabaseTypeToml(tomlData) {
         },
     }));
     canonicalizeDatabaseTypeConfig(typeConfig);
-    // Both rule-set spellings; the name form resolves to an id later.
+    // The `ruleSetName` reference; it resolves to an id later.
     applyRuleSetReference(typeSection, typeConfig);
     if (tomlData.triggers) {
         typeConfig.triggers = tomlData.triggers;
@@ -4081,13 +4069,16 @@ export function parseRuleSetToml(tomlData) {
 /**
  * Read a config's rule-set reference off its TOML table (#2644).
  *
- * Both spellings are accepted — the portable `ruleSetName` and the legacy
- * `ruleSetId` — and the name form is left as `_ruleSetName` for
+ * One spelling, the portable `ruleSetName`, left as `_ruleSetName` for
  * `resolveRuleSetReference` to turn into an id once the app's rule sets are
- * known. Neither present means no reference, which push sends as an explicit
- * `null` so removing the line clears it (#1567).
+ * known. Absent means no reference, which push sends as an explicit `null` so
+ * removing the line clears it (#1567). The id spelling `ruleSetId` is retired
+ * (#3997): the preflight refuses it through `retired-keys.ts`, and it is never
+ * read here, so no id authored in TOML reaches the wire.
  */
 function applyRuleSetReference(section, entity) {
+    // The payload builder put the `ruleSetName` value on the `ruleSetId` field;
+    // the resolver sets the real id.
     delete entity.ruleSetId;
     if (section.ruleSetName && section.ruleSetName !== "") {
         // Trimmed to match the name the server stores for the rule set itself
@@ -4097,9 +4088,6 @@ function applyRuleSetReference(section, entity) {
                 ? section.ruleSetName.trim()
                 : section.ruleSetName;
     }
-    else if (section.ruleSetId && section.ruleSetId !== "") {
-        entity.ruleSetId = section.ruleSetId;
-    }
 }
 /** Drop keys the TOML did not carry, so `"x" in entity` stays meaningful. */
 function dropUndefined(entity) {
@@ -4162,22 +4150,22 @@ export function parseCollectionTypeConfigToml(tomlData) {
 // the SAME push parser before hashing.
 //
 // Parsing through the push parser — rather than hashing the raw parsed TOML —
-// is what makes the comparison encoding-independent, and is why the four known
+// is what makes the comparison encoding-independent, and is why the known
 // false-diff traps do not fire: a legacy JSON-string operation and the native
 // `[operations.definition]` table the server emits normalize to one shape
-// (`normalizeOperationFromToml`); a `ruleSetName` reference and its legacy
-// `ruleSetId` resolve to the same id (`normalizeRuleSetRefForDiff`); an omitted
-// `autoAddCreator` picks up the same default the server serializes
-// (`parseGroupTypeConfigToml`); and a metadata-category's identity is read from
-// the parsed `[metadataCategoryConfig]` content, not the filename. Hashing raw
-// parsed TOML would show a false `Modified` for each of those equivalent forms.
+// (`normalizeOperationFromToml`); a `ruleSetName` reference resolves to the id
+// the server holds (`normalizeRuleSetRefForDiff`); an omitted `autoAddCreator`
+// picks up the same default the server serializes (`parseGroupTypeConfigToml`);
+// and a metadata-category's identity is read from the parsed
+// `[metadataCategoryConfig]` content, not the filename. Hashing raw parsed TOML
+// would show a false `Modified` for each of those equivalent forms.
 /**
  * Resolve a parsed entity's rule-set reference to a stable id for hashing.
  * `parseGroupTypeConfigToml` / `parseCollectionTypeConfigToml` /
- * `parseDatabaseTypeToml` leave either `_ruleSetName` (key-based) or a legacy
- * `ruleSetId` on the entity; collapsing both to `ruleSetId` here means the two
- * encodings of the same reference hash equal. `throwOnMissing: false` so an
- * unresolvable name degrades gracefully rather than aborting the diff.
+ * `parseDatabaseTypeToml` leave the `ruleSetName` reference as `_ruleSetName`;
+ * resolving it to `ruleSetId` here means the local file and the server entity
+ * hash the same reference. `throwOnMissing: false` so an unresolvable name
+ * degrades gracefully rather than aborting the diff.
  *
  * When the name does NOT resolve — a typo, or a rule set added locally in the
  * same tree but not yet on the server — `resolveRuleSetReference` deletes
@@ -4538,16 +4526,16 @@ function jsonFieldsForDiff(table, entity) {
 /**
  * One test-case reference as the comparison reads it (#2880 behavior 17).
  *
- * A reference reaches the projection in one of three states, and all three
- * describe the same thing on both sides once this is applied:
+ * A reference reaches the projection as the value in its NAME slot, in one of
+ * two states, and both describe the same thing on both sides once this is
+ * applied:
  *
- *  - a portable NAME (`configName = "default"`), which a test file carries so
- *    it survives a move between apps;
- *  - a legacy ID that RESOLVES, which becomes that same name — otherwise a file
- *    pinned by id would differ forever from the file pull writes for it;
- *  - a legacy ID that does NOT resolve, which stays the id, because pull writes
- *    an unresolvable id straight back and comparing it away would hide a pin
- *    the next push still sends.
+ *  - a portable NAME (`configName = "default"`) — what a test file carries,
+ *    and what the server's id renders as when the lookups resolve it;
+ *  - a live ID the lookups could NOT resolve, which the comparison's rendering
+ *    (`serializeTestCaseForComparison`) carries in the name slot and which
+ *    stays the id here, so a case pinned to a deleted or unlistable config is
+ *    a difference against an unpinned file rather than hidden (#3998).
  */
 function testCaseReference(value, idToName) {
     if (typeof value !== "string" || value === "")
@@ -4824,14 +4812,6 @@ const CONFIG_DIFF_SPECS = {
         table: BLOB_BUCKET_TABLE,
         parse: (doc) => {
             const bucket = { ...(doc?.bucket ?? {}) };
-            // #1020 — `accessPolicy` is the pre-`preset` spelling, still accepted on
-            // the wire and still authored in unmigrated files. Both spellings mean
-            // the same access model, so they project the same way; without this an
-            // unmigrated file reports a difference no push can clear (push sends the
-            // legacy key and the server answers with `preset`).
-            if (bucket.preset === undefined && bucket.accessPolicy !== undefined) {
-                bucket.preset = bucket.accessPolicy;
-            }
             return {
                 bucketKey: doc?.bucket?.key ?? "",
                 ...buildPayloadFromToml(BLOB_BUCKET_TABLE, bucket, {
@@ -4865,7 +4845,7 @@ const CONFIG_DIFF_SPECS = {
             const keys = [];
             if (!bucket.name)
                 keys.push("name");
-            if (!bucket.preset && !bucket.accessPolicy)
+            if (!bucket.preset)
                 keys.push("preset");
             if (!bucket.ruleSetId)
                 keys.push("ruleSetId");
@@ -4877,17 +4857,15 @@ const CONFIG_DIFF_SPECS = {
     // edited expectation read as Synced while push applied it from the file's
     // byte hash.
     //
-    // The type's own difficulty is that a reference has two legal spellings — the
-    // portable `configName` a test file carries so it survives a move between
-    // apps, and the legacy `configId` pull still writes back when the name cannot
-    // be resolved. They name the same thing, so they project the same way; the
-    // `extra` context is what makes that possible (the id→name lookups are not in
-    // the document).
+    // The type's own difficulty is that a reference is a NAME in the file and an
+    // id on the server. The comparison renders the server's id through the
+    // id→name lookups (which are not in the document — the `extra` context
+    // carries them), so both sides project the thing referred to.
     "test-case": {
         label: "test-case",
         table: TEST_CASE_TABLE,
         parse: (doc) => parseTestCaseToml(doc),
-        serialize: (record, _maps, extra) => serializeTestCase(record, extra?.lookupMaps),
+        serialize: (record, _maps, extra) => serializeTestCaseForComparison(record, extra?.lookupMaps),
         // The server trims a test-case name on write (`src/admin-api.ts`), so a
         // padded one in the file is not a difference — it is what the server will
         // store (#2880 DSO-003).
@@ -4897,12 +4875,11 @@ const CONFIG_DIFF_SPECS = {
         },
         extras: (entity, _doc, extra) => ({
             // These three OVERRIDE the definition's fields of the same name: the
-            // value compared is the thing referred to, not the spelling that referred
-            // to it. Precedence matches the push path exactly — a file carrying both
-            // an id and a name is pushed on the id, so it is compared on the id.
-            configId: testCaseReference(entity.configId ?? entity._configName, extra?.lookupMaps?.configIdToName),
-            evaluatorPromptId: testCaseReference(entity.evaluatorPromptId ?? entity._evaluatorPromptKey, extra?.lookupMaps?.promptIdToKey),
-            evaluatorConfigId: testCaseReference(entity.evaluatorConfigId ?? entity._evaluatorConfigName, extra?.lookupMaps?.configIdToName),
+            // value compared is the thing referred to, read from the name the file
+            // (or the comparison's rendering of the server record) carries.
+            configId: testCaseReference(entity._configName, extra?.lookupMaps?.configIdToName),
+            evaluatorPromptId: testCaseReference(entity._evaluatorPromptKey, extra?.lookupMaps?.promptIdToKey),
+            evaluatorConfigId: testCaseReference(entity._evaluatorConfigName, extra?.lookupMaps?.configIdToName),
         }),
         describe: (entity) => `test case "${entity?.name}"`,
     },
@@ -5066,7 +5043,7 @@ export function hashLocalConfigForDiff(spec, parsedToml, maps, extra) {
  * Hash a SERVER entity the same way, by serializing it into the file `sync
  * pull` would write and hashing that — so the two sides are normalized
  * identically by construction, and a legacy encoding on disk (a JSON-string
- * operation, an id-based rule-set reference) is not a false `Modified`.
+ * operation) is not a false `Modified`.
  *
  * `extra` carries the sibling rows a type's file also holds: a database type's
  * operations and subscriptions, which the list response does not include.
@@ -5721,49 +5698,81 @@ export function getTestsDir(configDir, blockType, blockKey) {
 function blockSelectionLabel(blockType) {
     return blockType === "script" ? "transform" : blockType;
 }
-export function serializeTestCase(testCase, lookupMaps, options = {}) {
-    // #2644 — name any server key this CLI version does not know rather than
-    // dropping it silently on the way into the file. Test cases are a registered
-    // surface; their sidecar shape is the only thing that sets them apart.
-    warnUnrecognizedServerKeys(testCase, TEST_CASE_TABLE, options.file ?? `<block>.tests/${testCase?.name ?? "unnamed"}.toml`, options.logger);
-    // Resolve ID references to key-based references
-    const configName = testCase.configId && lookupMaps?.configIdToName
-        ? (lookupMaps.configIdToName.get(testCase.configId) || "") : "";
-    const evaluatorPromptKey = testCase.evaluatorPromptId && lookupMaps?.promptIdToKey
-        ? (lookupMaps.promptIdToKey.get(testCase.evaluatorPromptId) || "") : "";
-    const evaluatorConfigName = testCase.evaluatorConfigId && lookupMaps?.configIdToName
-        ? (lookupMaps.configIdToName.get(testCase.evaluatorConfigId) || "") : "";
+/**
+ * The `[test]` table for one server record, and the references it could not
+ * name (#3998).
+ *
+ * A sidecar authors its references by NAME only — the id spellings are retired
+ * — so a reference whose id has no lookup entry has no honest spelling in a
+ * file. `unresolvedSpelling` says what goes in the name slot for one: `"empty"`
+ * for the file pull writes (and the caller decides whether to write it at all),
+ * `"raw-id"` for the comparison's rendering, which is parsed and never written.
+ */
+function testCaseSidecarTable(testCase, lookupMaps, unresolvedSpelling) {
+    const unresolved = [];
+    const reference = (field, tomlKey, idToName) => {
+        const id = testCase?.[field];
+        if (typeof id !== "string" || id === "")
+            return "";
+        const name = idToName?.get(id);
+        if (name)
+            return name;
+        unresolved.push({ tomlKey, field, id });
+        return unresolvedSpelling === "raw-id" ? id : "";
+    };
+    const configName = reference("configId", "configName", lookupMaps?.configIdToName);
+    const evaluatorPromptKey = reference("evaluatorPromptId", "evaluatorPromptKey", lookupMaps?.promptIdToKey);
+    // The judge's config belongs to the evaluator prompt, not to this sidecar's
+    // block; config ids are app-unique, so the app-wide map names it.
+    const evaluatorConfigName = reference("evaluatorConfigId", "evaluatorConfigName", lookupMaps?.configIdToName);
     // #2644 criterion 1 — the `[test]` key set comes from the vendored
     // definition, so a field added there is emitted by pull with no edit here.
     // The three reference fields carry the resolved NAME (a test file is portable
     // across apps); the rest keep the empty-string / "{}" / "[]" spellings a test
     // file has always used for "not set".
-    const data = {
-        test: projectRecordToToml(TEST_CASE_TABLE, testCase, {
-            name: (record) => record.name || "",
-            description: (record) => record.description || "",
-            inputVariables: (record) => jsonFieldText(record.inputVariables, "{}"),
-            configId: () => configName,
-            evaluatorPromptId: () => evaluatorPromptKey,
-            evaluatorConfigId: () => evaluatorConfigName,
-            expectedOutputPattern: (record) => record.expectedOutputPattern || "",
-            expectedOutputContains: (record) => jsonFieldText(record.expectedOutputContains, "[]"),
-            expectedJsonSubset: (record) => jsonFieldText(record.expectedJsonSubset, "{}"),
-        }),
-    };
-    // #2769 — a reference the id→name lookup could not resolve (an unknown id, or
-    // a config listing that failed on this pull) is written back in the legacy id
-    // spelling the parser still accepts, NOT as an empty name. Rewriting a pinned
-    // test as unpinned would push the pin away on the next `config push`.
-    if (testCase.configId && !configName)
-        data.test.configId = testCase.configId;
-    if (testCase.evaluatorPromptId && !evaluatorPromptKey) {
-        data.test.evaluatorPromptId = testCase.evaluatorPromptId;
-    }
-    if (testCase.evaluatorConfigId && !evaluatorConfigName) {
-        data.test.evaluatorConfigId = testCase.evaluatorConfigId;
-    }
-    return stringifyConfigToml(data);
+    const test = projectRecordToToml(TEST_CASE_TABLE, testCase, {
+        name: (record) => record.name || "",
+        description: (record) => record.description || "",
+        inputVariables: (record) => jsonFieldText(record.inputVariables, "{}"),
+        configId: () => configName,
+        evaluatorPromptId: () => evaluatorPromptKey,
+        evaluatorConfigId: () => evaluatorConfigName,
+        expectedOutputPattern: (record) => record.expectedOutputPattern || "",
+        expectedOutputContains: (record) => jsonFieldText(record.expectedOutputContains, "[]"),
+        expectedJsonSubset: (record) => jsonFieldText(record.expectedJsonSubset, "{}"),
+    });
+    return { test, unresolved };
+}
+/**
+ * The sidecar `config pull` writes for one server record. It never emits an id
+ * key (#3998): a reference the lookups cannot name is written as an empty name
+ * and reported through `onUnresolved`, and `pullTestCasesForBlock` declines to
+ * write such a case rather than unpin it on disk.
+ */
+export function serializeTestCase(testCase, lookupMaps, options = {}) {
+    // #2644 — name any server key this CLI version does not know rather than
+    // dropping it silently on the way into the file. Test cases are a registered
+    // surface; their sidecar shape is the only thing that sets them apart.
+    warnUnrecognizedServerKeys(testCase, TEST_CASE_TABLE, options.file ?? `<block>.tests/${testCase?.name ?? "unnamed"}.toml`, options.logger);
+    const { test, unresolved } = testCaseSidecarTable(testCase, lookupMaps, "empty");
+    if (unresolved.length > 0)
+        options.onUnresolved?.(unresolved);
+    return stringifyConfigToml({ test });
+}
+/**
+ * The rendering of a server record that the comparison parses (#3998) — never
+ * written to disk.
+ *
+ * It differs from the file pull writes in one place: a reference the lookups
+ * cannot name carries its raw id in the NAME slot. A live case pinned to a
+ * deleted or unlistable configuration must stay a difference against an
+ * unpinned file; projecting it as "no reference" would read the pair as Synced,
+ * and the next content edit would push `configId: null` and clear the pin in
+ * silence.
+ */
+export function serializeTestCaseForComparison(testCase, lookupMaps) {
+    const { test } = testCaseSidecarTable(testCase, lookupMaps, "raw-id");
+    return stringifyConfigToml({ test });
 }
 /**
  * The TOML spelling of a JSON-valued test-case field (#2769).
@@ -5813,20 +5822,22 @@ export function parseTestCaseToml(tomlData) {
             description: (value) => (value ? value : undefined),
             // Always sent — the server requires it, and `{}` is the empty spelling.
             inputVariables: (value) => parseJsonText(value, ["{}"]) ?? {},
-            // The legacy ID-based spellings stay accepted (declared in the
-            // definition's `tomlOnlyKeys`); the name-based ones become the `_`
-            // markers below, which the push path resolves against the live app.
-            configId: (_value, _mode, toml) => toml.configId || undefined,
-            evaluatorPromptId: (_value, _mode, toml) => toml.evaluatorPromptId || undefined,
-            evaluatorConfigId: (_value, _mode, toml) => toml.evaluatorConfigId || undefined,
+            // A reference is authored by name only: the names become the `_`
+            // markers below, which the push path resolves against the live app. The
+            // id spellings are retired (#3998) and refused by the preflight, so
+            // nothing is read into the wire field here — and these producers must
+            // stay, because without one `buildPayloadFromToml` would forward the
+            // NAME (`configName`) under the id field.
+            configId: () => undefined,
+            evaluatorPromptId: () => undefined,
+            evaluatorConfigId: () => undefined,
             expectedOutputPattern: (value) => (value ? value : undefined),
             expectedOutputContains: (value) => parseJsonText(value, ["[]"]),
             expectedJsonSubset: (value) => parseJsonText(value, ["{}"]),
         },
     });
     // An omitted field must be absent from the body, not present-and-undefined:
-    // the push path tests `!testPayload.configId` and the server's unknown-key
-    // check reads the body's keys.
+    // the server's unknown-key check reads the body's keys.
     for (const key of Object.keys(payload)) {
         if (payload[key] === undefined)
             delete payload[key];
@@ -6179,6 +6190,35 @@ export async function pullFunctions(client, appId, configDir, logger = () => { }
         items,
     };
 }
+/**
+ * The id→name lookups `config pull` writes test-case references through
+ * (#3998).
+ *
+ * The prompt half is built from EVERY prompt's detail — the pull fetches them
+ * all before `--only` filters the list — so a judge prompt outside the
+ * selection still names. Configurations come from the pulled blocks (a case
+ * pins one of its own block's) and from every prompt (a judge's config is the
+ * judge prompt's). An entry without both an id and a name is skipped.
+ */
+export function testCaseLookupMapsForPull(input) {
+    const configIdToName = new Map();
+    const promptIdToKey = new Map();
+    const addConfig = (config) => {
+        if (config?.configId && config?.configName) {
+            configIdToName.set(config.configId, config.configName);
+        }
+    };
+    for (const prompt of input.prompts) {
+        if (prompt?.promptId && prompt?.promptKey) {
+            promptIdToKey.set(prompt.promptId, prompt.promptKey);
+        }
+        for (const config of prompt?.configs ?? [])
+            addConfig(config);
+    }
+    for (const config of input.configs)
+        addConfig(config);
+    return { configIdToName, promptIdToKey };
+}
 /**
  * Every test case a block has, draining the cursor (#2769).
  *
@@ -6231,6 +6271,27 @@ export function carryForwardTestCaseEntities(params) {
     }
     return carried;
 }
+/**
+ * Whether two sidecar names in `testsDir` are one file on disk (#3998).
+ *
+ * Names that differ only by case are one file on the case-insensitive
+ * filesystems most of these trees live on and two on the rest (#2896), so the
+ * answer comes from the filesystem itself: the same device and inode.
+ */
+function sameTestCaseFile(testsDir, a, b) {
+    if (a === b)
+        return true;
+    if (normalizeTestCaseKey(a) !== normalizeTestCaseKey(b))
+        return false;
+    try {
+        const left = statSync(join(testsDir, `${a}.toml`));
+        const right = statSync(join(testsDir, `${b}.toml`));
+        return left.dev === right.dev && left.ino === right.ino;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Write one block's test cases into its `<key>.tests/` sidecar and record them
  * in sync state. Exported so the unit tests can drive it against a stubbed
@@ -6246,10 +6307,9 @@ export async function pullTestCasesForBlock(params) {
     const testsDir = getTestsDir(configDir, blockType, blockKey);
     // A block with no cases and no sidecar is not a block whose sidecar is empty:
     // creating the directory here would commit an empty folder Git cannot carry.
-    if (testCases.length === 0 && !existsSync(testsDir))
-        return { ok: true, count: 0 };
-    if (testCases.length > 0)
-        ensureDir(testsDir);
+    if (testCases.length === 0 && !existsSync(testsDir)) {
+        return { ok: true, count: 0, unwritten: [] };
+    }
     const pulledSlugs = new Set();
     // #2896 — a keyed case is written to the file its key names, so pull stops
     // renaming what push authored: the repro's `full-refresh-takes-all-history`
@@ -6259,15 +6319,35 @@ export async function pullTestCasesForBlock(params) {
     // The key is server data becoming a path: the containment check an
     // attachment's filename gets, so nothing lands outside the sidecar dir.
     (name) => attachmentWritePath(testsDir, `${name}.toml`) !== null);
+    // #3998 — render every case before anything is written. A reference the
+    // lookups cannot name has no honest spelling in a sidecar (the id keys are
+    // retired, and an empty name would unpin the case on the next push), so such
+    // a case is NOT written: its file, fixtures and record stay as they were.
+    const writable = [];
+    const skipped = [];
     for (const tc of testCases) {
         const slug = fileNames.get(tc);
+        let references = [];
+        const toml = serializeTestCase(tc, lookupMaps, {
+            file: join(testsDir, `${slug}.toml`),
+            logger: (message) => log(message),
+            onUnresolved: (refs) => {
+                references = refs;
+            },
+        });
+        if (references.length > 0)
+            skipped.push({ tc, slug, references });
+        else
+            writable.push({ tc, slug, toml });
+    }
+    if (writable.length > 0)
+        ensureDir(testsDir);
+    const writtenSlugs = new Map(writable.map((w) => [w.slug, w.tc]));
+    for (const { tc, slug, toml } of writable) {
         pulledSlugs.add(slug);
         // Write test case TOML
         const tomlPath = join(testsDir, `${slug}.toml`);
-        writeFileSync(tomlPath, serializeTestCase(tc, lookupMaps, {
-            file: tomlPath,
-            logger: (message) => log(message),
-        }));
+        writeFileSync(tomlPath, toml);
         // Attachments: the sidecar directory is the authored set, so pull makes it
         // match the server — downloading what is there, recording each file's
         // content hash (so push can see a byte change under an unchanged name), and
@@ -6359,12 +6439,79 @@ export async function pullTestCasesForBlock(params) {
             }),
         };
     }
+    // #3998 — a skipped case is found by its ID in the prior state, not by the
+    // file name it would get now: the server can rename a case's key between
+    // pulls, and the old file is the one holding the pin. Every such file is
+    // kept out of the cleanup below and every such record carried forward under
+    // its existing key — unless a case written above now owns that file, whose
+    // write wins it (the key-to-file rule of #2896). "That file" is decided by
+    // the filesystem: `Alpha` and `alpha` are one file where names fold case.
+    const unwritten = [];
+    const writtenOwner = (candidate) => writtenSlugs.get(candidate) ??
+        writable.find((w) => sameTestCaseFile(testsDir, w.slug, candidate))?.tc;
+    for (const { tc, slug, references } of skipped) {
+        const priorEntries = Object.entries(params.priorTestCaseEntities ?? {}).filter(([, entry]) => entry?.blockType === blockType &&
+            entry?.blockKey === blockKey &&
+            entry?.id === tc.testCaseId);
+        const slugs = new Set([slug]);
+        for (const [stateKey, entry] of priorEntries) {
+            slugs.add(entry.slug ?? stateKey.slice(stateKey.lastIndexOf("/") + 1));
+        }
+        const preservedSlugs = [];
+        const superseded = new Set();
+        for (const candidate of slugs) {
+            const owner = writtenOwner(candidate);
+            if (owner) {
+                superseded.add(candidate);
+                warn(`  ${blockType}: ${blockKey}/${candidate}.toml now holds test case ` +
+                    `"${owner?.name ?? ""}" — the prior sidecar of unwritten test case ` +
+                    `"${tc?.name ?? ""}" at that path was superseded`);
+                continue;
+            }
+            pulledSlugs.add(candidate);
+            if (existsSync(join(testsDir, `${candidate}.toml`))) {
+                preservedSlugs.push(candidate);
+            }
+        }
+        for (const [stateKey, entry] of priorEntries) {
+            const entrySlug = entry.slug ?? stateKey.slice(stateKey.lastIndexOf("/") + 1);
+            if (superseded.has(entrySlug))
+                continue;
+            if (testCaseEntities[stateKey])
+                continue;
+            testCaseEntities[stateKey] = entry;
+        }
+        const what = references
+            .map((ref) => `${ref.tomlKey} (id ${ref.id})`)
+            .join(", ");
+        const kept = preservedSlugs.length > 0
+            ? `kept ${preservedSlugs.map((s) => `${s}.toml`).join(", ")} as it was`
+            : "no sidecar exists for it";
+        warn(`  Test case not written for ${blockType}: ${blockKey}/${slug} ` +
+            `("${tc?.name ?? ""}"): ${what} could not be resolved to a name — ` +
+            `${kept}, so the pin is not lost. The configuration or prompt may have ` +
+            "been deleted (re-pin the case on the server), or its listing failed " +
+            "on this pull (run `config pull` again).");
+        unwritten.push({
+            blockType,
+            blockKey,
+            slug,
+            name: tc?.name ?? "",
+            testCaseId: tc?.testCaseId,
+            references,
+            preservedSlugs,
+        });
+    }
     // Clean up local files for remotely-deleted test cases
     if (existsSync(testsDir)) {
         const localFiles = readdirSync(testsDir).filter((f) => f.endsWith(".toml"));
         for (const file of localFiles) {
             const localSlug = basename(file, ".toml");
-            if (!pulledSlugs.has(localSlug)) {
+            // A listing keeps the casing a file was created with, so the name a case
+            // was just written to can come back as `Alpha.toml` — the same file.
+            const pulled = pulledSlugs.has(localSlug) ||
+                [...pulledSlugs].some((slug) => sameTestCaseFile(testsDir, slug, localSlug));
+            if (!pulled) {
                 // Remove orphaned TOML
                 unlinkSync(join(testsDir, file));
                 // Remove orphaned attachment dir if exists
@@ -6384,7 +6531,7 @@ export async function pullTestCasesForBlock(params) {
             }
         }
     }
-    return { ok: true, count: testCases.length };
+    return { ok: true, count: writable.length, unwritten };
 }
 /**
  * One pull leg: every block of a type the pull selected (#2769).
@@ -6398,6 +6545,7 @@ export async function pullTestCasesForBlocks(params) {
     const log = params.logger ?? ((message) => info(message));
     let count = 0;
     const skippedBlocks = [];
+    const unwritten = [];
     for (const block of params.blocks) {
         const outcome = await pullTestCasesForBlock({
             client: params.client,
@@ -6425,9 +6573,14 @@ export async function pullTestCasesForBlocks(params) {
         if (outcome.count > 0) {
             log(`  Wrote ${outcome.count} test case(s) for ${params.blockType}: ${block.key}`);
         }
+        if (outcome.unwritten.length > 0) {
+            log(`  ${outcome.unwritten.length} test case(s) not written for ` +
+                `${params.blockType}: ${block.key} (unresolved references; see above)`);
+        }
         count += outcome.count;
+        unwritten.push(...outcome.unwritten);
     }
-    return { count, skippedBlocks };
+    return { count, skippedBlocks, unwritten };
 }
 /** The 10 MB per-attachment cap the server enforces. */
 const TEN_MB = 10 * 1024 * 1024;
@@ -6619,9 +6772,20 @@ export async function pushTestCasesForBlock(params) {
             continue;
         }
         const tomlData = parseTomlFile(filePath);
+        // #3998 — the command's preflight refuses a sidecar it cannot push, but
+        // this leg is exported and the parser no longer reads the retired id keys:
+        // a file reaching it unchecked would be pushed UNPINNED in silence. The
+        // same per-loop defense the workflow leg keeps (#976).
+        const sidecarErrors = testCaseSidecarPreflightErrors(filePath, tomlData);
+        if (sidecarErrors.length > 0) {
+            const message = sidecarErrors.join("; ");
+            warn(`  Failed to push test case ${blockKey}/${slug}: ${message}`);
+            failures.push({ type: "test-case", key: `${blockKey}/${slug}`, message });
+            continue;
+        }
         const testPayload = parseTestCaseToml(tomlData);
-        // Resolve key-based references to IDs. An authored name that does not
-        // resolve is a FAILURE: silently dropping it would push the test case with
+        // Resolve the authored names to IDs — a name is the only spelling a
+        // sidecar has (#3998). An authored name that does not resolve is a FAILURE: silently dropping it would push the test case with
         // no pin, quietly changing what the case tests (#2769). The exception is a
         // preview of a block this push has not created yet — its configs cannot
         // exist to be named, so a dry run reports the reference as pending rather
@@ -6642,7 +6806,7 @@ export async function pushTestCasesForBlock(params) {
         delete testPayload._configName;
         delete testPayload._evaluatorPromptKey;
         delete testPayload._evaluatorConfigName;
-        if (configName && !testPayload.configId) {
+        if (configName) {
             const configMap = blockType === "prompt"
                 ? resolutionMaps?.promptConfigNameToId
                 : blockType === "script"
@@ -6660,14 +6824,14 @@ export async function pushTestCasesForBlock(params) {
             else
                 noteUnresolved(`configName "${configName}"`, blockType, blockKey);
         }
-        if (evaluatorPromptKey && !testPayload.evaluatorPromptId) {
+        if (evaluatorPromptKey) {
             const resolvedId = resolutionMaps?.promptKeyToId.get(evaluatorPromptKey);
             if (resolvedId)
                 testPayload.evaluatorPromptId = resolvedId;
             else
                 noteUnresolved(`evaluatorPromptKey "${evaluatorPromptKey}"`, "prompt", evaluatorPromptKey);
         }
-        if (evaluatorConfigName && !testPayload.evaluatorConfigId) {
+        if (evaluatorConfigName) {
             let resolvedId = evaluatorPromptKey
                 ? resolutionMaps?.promptConfigNameToId.get(`${evaluatorPromptKey}#${evaluatorConfigName}`)
                 : undefined;
@@ -7248,9 +7412,10 @@ export function pairTestCases(input) {
  * integration and workflow sidecar pinned to a config reported Modified
  * forever, and push read the same pair as server drift.
  *
- * One listing per block that has sidecars, and a failed one is silent: an
- * unresolved reference compares as the id both sides carry, which is the same
- * degradation `serializeTestCase` already applies.
+ * One listing per block that has sidecars, and a failed one is silent: the
+ * live side's unresolved reference then compares as its raw id
+ * (`serializeTestCaseForComparison`), so the row reads Modified rather than
+ * hiding a pin.
  */
 async function fillBlockConfigNames(client, appId, blockType, blockId, configIdToName) {
     try {
@@ -7308,10 +7473,6 @@ export async function compareTestCasesForBlock(params) {
     });
     for (const slug of localSlugs) {
         const live = paired.bySlug.get(slug);
-        if (!live) {
-            rows.push({ ...base, slug, status: LOCAL_ONLY_NEW });
-            continue;
-        }
         const filePath = join(testsDir, `${slug}.toml`);
         let row;
         try {
@@ -7319,7 +7480,9 @@ export async function compareTestCasesForBlock(params) {
             // #2880 criterion 1 — a sidecar push's preflight would reject is not one
             // this command calls synced, and the message is the same one. The WHOLE
             // preflight, not just the sidecar's own rules: an unknown key or a
-            // mistyped value aborts push too.
+            // mistyped value aborts push too. #3998 — and an UNPAIRED sidecar is
+            // checked before it is called local-only, so a new file push would refuse
+            // (a retired id key) is reported with the guidance, not as a create.
             const errors = testCaseSidecarPreflightErrors(filePath, tomlData);
             if (errors.length > 0) {
                 row = {
@@ -7329,6 +7492,10 @@ export async function compareTestCasesForBlock(params) {
                     hint: errors.join("; "),
                 };
             }
+            else if (!live) {
+                rows.push({ ...base, slug, status: LOCAL_ONLY_NEW });
+                continue;
+            }
             else {
                 const verdict = compareLocalToRemote(spec, tomlData, live, { ruleSetIdToName: new Map(), ruleSetNameToId: new Map() }, extra, 
                 // Both sides read a reference through the same lookups — see
@@ -7345,6 +7512,12 @@ export async function compareTestCasesForBlock(params) {
                 hint: `${filePath}: ${err?.message || String(err)}`,
             };
         }
+        // An unpaired file push would refuse has no attachment plan, as a
+        // local-only one has none.
+        if (!live) {
+            rows.push(row);
+            continue;
+        }
         // #2880 behavior 19 — attachments are part of what push would do, read
         // from the SAME plan push executes. A sidecar whose text compares clean but
         // whose fixtures have not been uploaded is not Synced.
@@ -7820,7 +7993,11 @@ export function registerConfigSyncCommands(sync) {
             const appWorkflowItems = selectPull("workflow", workflowItems.filter((w) => !isPlatformOwnedWorkflow(w)), (w) => w.workflowKey);
             // Fetch details for each entity
             const integrations = selectPull("integration", await Promise.all(integrationItems.map((i) => client.getIntegration(resolvedAppId, i.integrationId))), (i) => i.integrationKey);
-            const prompts = selectPull("prompt", await Promise.all(promptItems.map((p) => client.getPrompt(resolvedAppId, p.promptId))), (p) => p.promptKey);
+            // #3998 — every prompt's detail is kept, not just the selection's: a
+            // test case of a selected block may be judged by a prompt `--only`
+            // left out, and its sidecar names that prompt by key.
+            const promptDetails = await Promise.all(promptItems.map((p) => client.getPrompt(resolvedAppId, p.promptId)));
+            const prompts = selectPull("prompt", promptDetails, (p) => p.promptKey);
             const workflows = await Promise.all(appWorkflowItems.map(async (w) => {
                 const workflowData = await client.getWorkflow(resolvedAppId, w.workflowId);
                 // #2645 — fetch EVERY config's body, not just the active one. The
@@ -8321,57 +8498,38 @@ export function registerConfigSyncCommands(sync) {
             if (pulledFunctionsCount > 0) {
                 info(`  Pulled ${pulledFunctionsCount} function(s)`);
             }
-            // Build lookup maps for test case serialization
-            const configIdToName = new Map();
-            const promptIdToKey = new Map();
-            for (const prompt of prompts) {
-                promptIdToKey.set(prompt.promptId, prompt.promptKey);
-                if (prompt.configs) {
-                    for (const config of prompt.configs) {
-                        configIdToName.set(config.configId, config.configName);
-                    }
-                }
-            }
-            // Also include workflow config names
-            for (const { configs } of workflows) {
-                if (configs) {
-                    for (const config of configs) {
-                        configIdToName.set(config.configId, config.configName);
-                    }
-                }
-            }
-            // Include script config names so a pinned script test case
-            // round-trips its `configName` reference (the same way prompt/workflow
-            // configs above do). One extra `configs` fetch per pulled script.
-            for (const [name, entity] of Object.entries(scriptEntities)) {
+            // Lookup maps for test case serialization (#3998): every prompt's
+            // detail, so a judge prompt outside an `--only` selection still names,
+            // and the configurations of the pulled blocks — a case pins one of its
+            // own block's. A reference these cannot resolve is reported by
+            // `pullTestCasesForBlock`, and its sidecar is not written.
+            const blockConfigs = [];
+            for (const { configs } of workflows)
+                blockConfigs.push(...(configs ?? []));
+            // One `configs` fetch per pulled script and integration. A failed one
+            // is non-fatal: the references it would have named are reported.
+            for (const entity of Object.values(scriptEntities)) {
                 try {
-                    const { items: scriptConfigs } = await client.listScriptConfigs(resolvedAppId, entity.id);
-                    for (const config of scriptConfigs) {
-                        configIdToName.set(config.configId, config.configName);
-                    }
+                    const { items } = await client.listScriptConfigs(resolvedAppId, entity.id);
+                    blockConfigs.push(...items);
                 }
                 catch {
-                    // Non-fatal: a script test case pinned to a config serializes with
-                    // its legacy id spelling instead of a name (#2769), so the pin
-                    // survives. The header/body still pulled fine — `name` retained.
-                    void name;
+                    // Non-fatal — see above.
                 }
             }
-            // Integration config names, for the same reason (#2769). A failed fetch
-            // is non-fatal here too: `serializeTestCase` keeps the pin as `configId`
-            // rather than writing an empty reference.
             for (const integration of integrations) {
                 try {
-                    const { items: integrationConfigs } = await client.listIntegrationConfigs(resolvedAppId, integration.integrationId);
-                    for (const config of integrationConfigs) {
-                        configIdToName.set(config.configId, config.configName);
-                    }
+                    const { items } = await client.listIntegrationConfigs(resolvedAppId, integration.integrationId);
+                    blockConfigs.push(...items);
                 }
                 catch {
                     // Non-fatal — see above.
                 }
             }
-            const testCaseLookupMaps = { configIdToName, promptIdToKey };
+            const testCaseLookupMaps = testCaseLookupMapsForPull({
+                prompts: promptDetails,
+                configs: blockConfigs,
+            });
             // #2731 B4 — pull is one of the two moments local and server provably
             // agree, so it stamps the semantic baseline beside the byte hash (push
             // stamps the other one, from the entity the server returned). The
@@ -8411,6 +8569,7 @@ export function registerConfigSyncCommands(sync) {
             const testCaseEntities = {};
             const priorTestCaseEntities = priorEntities.testCases;
             let totalTestCases = 0;
+            let unwrittenTestCases = 0;
             for (const [blockType, blocks] of [
                 [
                     "prompt",
@@ -8440,7 +8599,7 @@ export function registerConfigSyncCommands(sync) {
                     })),
                 ],
             ]) {
-                const { count } = await pullTestCasesForBlocks({
+                const { count, unwritten } = await pullTestCasesForBlocks({
                     client,
                     appId: resolvedAppId,
                     configDir,
@@ -8452,6 +8611,14 @@ export function registerConfigSyncCommands(sync) {
                     logger: (message) => info(message),
                 });
                 totalTestCases += count;
+                unwrittenTestCases += unwritten.length;
+            }
+            // #3998 — a case pull could not name a reference for is not written, so
+            // its pin is never lost; the count is repeated here so it is not missed
+            // among the per-block lines. Exit status is unchanged, as for every
+            // other partial fetch this command reports.
+            if (unwrittenTestCases > 0) {
+                warn(`${unwrittenTestCases} test case(s) not written — references could not be resolved; see above`);
             }
             // Build ruleSetId → name map for database types and group type configs
             const ruleSets = selectPull("rule-set", Array.isArray(ruleSetsResult) ? ruleSetsResult : [], (rs) => ruleSetFileKey(rs));
@@ -8969,6 +9136,9 @@ export function registerConfigSyncCommands(sync) {
             keyValue("Functions", pulledFunctionsCount);
             keyValue("Email Templates", emailTemplates.length);
             keyValue("Test Cases", totalTestCases);
+            if (unwrittenTestCases > 0) {
+                keyValue("Test Cases not written", unwrittenTestCases);
+            }
             keyValue("Database Types", databaseTypesWithOps.length);
             keyValue("Rule Sets", ruleSets.length);
             keyValue("Group Type Configs", groupTypeConfigs.length);
@@ -17263,28 +17433,28 @@ What a push guarantees (two stages):
         let unchangedCount = 0;
         // ---- database-type-configs/ pass ----
         if (dbFiles.length > 0) {
-            // Hydrate ruleSetIdToName from local sync state so files that
-            // reference a rule set via the legacy `ruleSetId = "01..."` form
-            // round-trip with the correct `ruleSetName`. Without this, any user
-            // who runs migrate-toml against a file with a rule-set assignment
-            // would silently lose that reference (review feedback r3246633010).
-            //
-            // Files that use the modern key-based `ruleSetName = "..."` form
-            // don't need the map at all — `parseDatabaseTypeToml` stores the
-            // value in `typeConfig._ruleSetName` and the serializer now prefers
-            // that. The map is only load-bearing for the legacy ID-based form.
-            const ruleSetIdToName = new Map();
-            const migrateSyncState = loadSyncState(configDir);
-            if (migrateSyncState?.entities?.ruleSets) {
-                for (const [fileKey, entry] of Object.entries(migrateSyncState.entities.ruleSets)) {
-                    if (entry && typeof entry === "object" && "id" in entry && entry.id) {
-                        // fileKey is the sanitized rule-set name (see config pull at
-                        // sync.ts:1385). It's the same shape the server returned and
-                        // matches what a TOML file's ruleSetName field would carry.
-                        ruleSetIdToName.set(entry.id, fileKey);
-                    }
-                }
+            // #3997 — refuse a tree carrying a retired key (the id-based
+            // `ruleSetId`) with the message `config push` gives, before anything is
+            // rewritten. This is a separate pass, not a check inside the loop below:
+            // that loop writes each file and saves sync state before it parses the
+            // next, so an in-loop abort would leave earlier files rewritten. Every
+            // offending file is reported, so the author fixes the tree once.
+            const retiredKeyErrors = [];
+            for (const file of dbFiles) {
+                const message = configUnknownKeyError(`database-type-configs/${file}`, parseTomlFile(join(dbTypesDir, file)), DATABASE_TYPE_TABLE);
+                if (message)
+                    retiredKeyErrors.push(message);
             }
+            if (retiredKeyErrors.length > 0) {
+                for (const message of retiredKeyErrors)
+                    error(`  ${message}`);
+                error(`Aborting migrate-toml: ${retiredKeyErrors.length} database-type ` +
+                    "file(s) carry a retired or unrecognized key; nothing was rewritten.");
+                process.exit(1);
+            }
+            // The parser yields the rule-set reference only as `_ruleSetName`,
+            // which the serializer prefers, so there is no id to map to a name.
+            const ruleSetIdToName = new Map();
             for (const file of dbFiles) {
                 const filePath = join(dbTypesDir, file);
                 const rawBefore = readFileSync(filePath, "utf-8");