AI debugging: invalidate the cache after a profile rename

Write a timeline that proves which value is stale

A report that “the name sometimes stays old” is not yet a useful repair request. Identify the record, the write that should change it, and the read path that returns the old value. For this illustrative directory, get returns a profile by ID and rename updates an existing profile. The next get through the same instance must return the new name.

Start with p1 named Ada. Read p1 to warm the cache, rename it to Grace, then read p1 again. Expect Ada on the first read and Grace on the second. Calling get for the first time only after rename cannot expose a stale warmed entry, so fixture order is part of the reproduction.

The scope is deliberately synchronous and local: one directory instance owns both Maps, all writes use rename, and records contain only string fields. Missing profiles return null and are not cached. Failed renames leave existing cache entries useful. Keep these rules visible before asking an assistant to propose expiration or a new caching library.

Separate a successful store write from a fresh cache read

The flawed factory below uses one Map as the store and another as the cache. Warming p1 puts a copied profile in the cache. rename replaces the store record, but get still returns the cached copy. Map.set updates the entry in the Map on which it is called; it does not update a second Map containing a related key. MDN: Map entries and methods

Run the example in Node as an .mjs file. The final assertion deliberately fails with Ada where Grace is expected. The successful rename assertion establishes that the write path returned true, but the stale result identifies a separate read-path failure. Both observations matter when evaluating an AI-generated explanation.

The record replacement also avoids an accidental repair by shared reference. Object spread creates a shallow copy, so the cached top-level name does not change merely because the store receives a different object. MDN: object spread and shallow copies This example has flat records; nested mutable values would need another ownership decision.

import assert from 'node:assert/strict';

function makeDirectoryProposed() {
  const store = new Map([['p1', { id: 'p1', name: 'Ada' }]]);
  const cache = new Map();
  return {
    get(id) {
      if (!cache.has(id)) {
        if (!store.has(id)) return null;
        cache.set(id, { ...store.get(id) });
      }
      return { ...cache.get(id) };
    },
    rename(id, name) {
      if (!store.has(id)) return false;
      store.set(id, { ...store.get(id), name });
      return true;
    },
  };
}

const stale = makeDirectoryProposed();
assert.equal(stale.get('p1').name, 'Ada');
assert.equal(stale.rename('p1', 'Grace'), true);
assert.equal(stale.get('p1').name, 'Grace');

Give AI the sequence and the owner of the cached value

Supply the factory, both public methods, and the failing sequence to the assistant. A focused request is: “Explain why get returns Ada after rename succeeds. Keep read-after-write freshness for this synchronous instance, preserve cache hits for other IDs, and retain null and false for missing records. Propose a change at the state owner and tests that observe origin reads.”

The owner matters because clearing a UI component's local state cannot remove a stale entry in this service cache. Likewise, changing the returned name only inside rename does not repair callers that read through get afterward. Trace the actual route used by the failing read before deciding which cache needs attention.

Ask for evidence that would falsify the diagnosis: an initial read that returns the wrong name before any write, or a rename that never reaches the store. Either observation would require a different investigation. A plausible cache story becomes useful only when the observed sequence distinguishes it from another explanation.

Delete the changed key after the store update succeeds

The repaired factory invalidates p1 after replacing its store record. The next get loads the updated record and warms the cache again. Map.delete removes the entry for the specified key, whereas clear removes every entry. MDN: Map entries and methods Choosing the named key preserves useful cached records for unaffected profiles.

The reads list records successful or missing origin lookups from get; rename does not add to it. Returning copies prevents callers from changing the flat cached record through a returned object. This instrumentation makes the expected state transitions inspectable without measuring elapsed time or inferring cache behavior from a fast response.

There is no asynchronous gap between the store update and deletion in this example. For a real database, invalidate after the transaction commits. A rejected write should not be reported as success. If writes can bypass this owner or a reader can repopulate stale data during an in-flight operation, this small repair needs a broader consistency design.

function makeDirectory() {
  const store = new Map([
    ['p1', { id: 'p1', name: 'Ada' }],
    ['p2', { id: 'p2', name: 'Lin' }],
  ]);
  const cache = new Map();
  const reads = [];
  return {
    reads,
    get(id) {
      if (!cache.has(id)) {
        reads.push(id);
        if (!store.has(id)) return null;
        cache.set(id, { ...store.get(id) });
      }
      return { ...cache.get(id) };
    },
    rename(id, name) {
      if (!store.has(id)) return false;
      store.set(id, { ...store.get(id), name });
      cache.delete(id);
      return true;
    },
  };
}

Assert returned values and the exact reload sequence

Paste the repaired factory above the following checks in a Node .mjs file. Warm both profiles before renaming p1. A fresh p1 value proves that the changed entry no longer serves the old snapshot. The read list must contain one additional p1 lookup, while the p2 lookup remains a hit. A further p1 get should also hit its refreshed entry.

A failed rename of a missing ID must return false without discarding cached profiles. The separate cold instance checks rename before any warm read: deleting an absent cache key must be harmless. Finally, mutating a returned flat profile must not poison the next cached answer. These are different contracts from merely returning Grace once.

All these assertions passed during preparation. Removing the deletion makes the freshness assertion fail. Replacing the deletion with clear allows the value checks to pass but causes an extra p2 origin lookup, which the read-list assertion rejects. The second mutation explains why observing work matters as well as observing output.

import assert from 'node:assert/strict';

const directory = makeDirectory();
assert.equal(directory.get('p1').name, 'Ada');
assert.equal(directory.get('p2').name, 'Lin');
assert.deepEqual(directory.reads, ['p1', 'p2']);
assert.equal(directory.rename('p1', 'Grace'), true);
assert.equal(directory.get('p1').name, 'Grace');
assert.equal(directory.get('p2').name, 'Lin');
assert.equal(directory.get('p1').name, 'Grace');
assert.deepEqual(directory.reads, ['p1', 'p2', 'p1']);

assert.equal(directory.rename('missing', 'Nobody'), false);
assert.equal(directory.get('p1').name, 'Grace');
assert.equal(directory.get('p2').name, 'Lin');
assert.deepEqual(directory.reads, ['p1', 'p2', 'p1']);
const copy = directory.get('p1');
copy.name = 'Changed outside';
assert.equal(directory.get('p1').name, 'Grace');
assert.equal(directory.get('missing'), null);
assert.equal(directory.get('missing'), null);
assert.deepEqual(directory.reads, ['p1', 'p2', 'p1', 'missing', 'missing']);

const cold = makeDirectory();
assert.equal(cold.rename('p1', 'Grace'), true);
assert.equal(cold.get('p1').name, 'Grace');
assert.deepEqual(cold.reads, ['p1']);
console.log('Cache freshness and retention checks passed');

Review every cached view affected by the mutation

Keyed profile invalidation is sufficient here because there is exactly one cached view per profile ID. A real application may also cache a directory list, a name search, or a team roster. A rename can affect those views even when each individual profile cache is fresh. List the read paths that depend on the changed field before declaring the full application repaired.

The exercise intentionally avoids negative caching. Two reads of a missing ID therefore make two origin lookups. A system that caches missing results needs to invalidate those results when records are created. Do not copy the example's missing-record expectations into a repository with a different cache contract.

Expiration can limit how long stale data survives, but a timer alone does not meet this example's immediate next-read requirement. Updating the cached record directly is another possible design when the write result is authoritative. Compare those choices against the actual contract, record ownership, and failure behavior instead of treating deletion as a universal answer.

Common questions about AI-assisted cache debugging

Why does a test pass when it reads only after renaming? Its cache starts empty, so the first lookup loads the new store value. Warm the entry before the mutation to exercise the state that caused the report. Use the same service instance throughout the reproduction.

Can I clear every entry to make the bug disappear? That produces fresh values in this example, but it violates the stated requirement to retain unaffected hits. If the real product permits broad invalidation, evaluate its cost with real evidence rather than inventing a performance number.

Does returning an object spread make the whole record independent? Only at the top level. The examples use flat string fields. Nested objects retain shared references under a shallow copy, so deeper state needs its own copying or immutability policy. MDN: object spread and shallow copies

Does this fix multiple server processes? Each instance here owns a private cache. Another process would need an invalidation, versioning, or consistency mechanism appropriate to its shared storage. The local tests establish no cross-process guarantee, and adding one requires a separate reproducible scenario.