feat(shadow)!: mismatchLogging content controls, value projection, and diff logging

[lan17]

Why

Shadow validation compares a cached value against the source of truth and emits a mismatch metric when they disagree. Until now the only way to see what disagreed was shadow.logMismatches: true, which logged the cache key plus the full JSON of both values — all or nothing. That's a problem for use cases whose values carry user data: one dynamic-config flip could put whole records into logs.

This PR splits the warning into parts you opt into individually at runtime, and adds two per-use-case hooks so values can be redacted (or summarized as a diff) before they ever reach the logger.

The new runtime config

ShadowConfig.logMismatches is gone. In its place:

shadow: {
  ramp: 5,
  mismatchLogging: {
    key: true,    // log which key mismatched
    value: false, // log the two compared values
    diff: true,   // log a structural diff of the two values
  },
}

Field	Adds to the warning	Cap
key	cacheKey — the logical DialCache URN	2 KiB
value	cachedValueJson + sourceValueJson	8 KiB each
diff	diffJson — which paths differ and how	8 KiB

Semantics worth knowing:

• Everything defaults to off. A warning is emitted only when at least one field is true, and it always carries cacheNamespace / useCase / keyType / outcome for routing, plus cachedValueAgeSeconds — how long the stale value had been readable when validation caught it (the same age the observeShadowValueAge metric records).
• Fields merge leaf-wise like the rest of shadow config, so dynamic config can turn value off mid-incident while keeping key on — no deploy needed.
• An invalid value for a known field (say value: "yes" from a bad config push) acts as false and records one config_resolution error; valid sibling fields keep logging. The cache result is never affected.
• Unknown own fields anywhere in key config are ignored while recognized fields still apply. Each observed config containing one or more unknown fields records one bounded error=config_unknown_field metric; field names and values never become labels. This includes legacy shadowRamp and shadow.logMismatches from mixed-version providers.
• DialCacheKeyConfig.disabled() sets all three to false, so the kill switch still kills logging.

Shaping what gets logged (code-level hooks)

Two optional hooks live next to shadowComparator on cached() / getOrLoad():

const getUser = dialcache.cached(fetchUser, {
  useCase: "GetUser",
  keyType: "user_id",
  cacheKey: (id) => id,

  // Runs once per side on a confirmed mismatch. Whatever it returns is what
  // `value: true` logs AND what the built-in diff compares — so sensitive
  // fields stripped here can't leak through either output.
  shadowMismatchLogValue: (user) => ({ id: user.id, updatedAt: user.updatedAt }),

  // Optional: replace the built-in diff entirely. Receives the RAW values.
  shadowMismatchLogDiff: (cached, source) => ({
    versions: [cached.version, source.version],
  }),
});

• No projector? value: true and diff: true log the raw values, same material as the old behavior. Define the projector for any use case whose values can carry sensitive fields before enabling those flags.
• Hooks fail closed. A projector throw or promise-like result logs null for that side (and a null built-in diff) — it never falls back to raw values. A diff-hook throw or promise-like result logs diffJson: null. Promise-like settlements are consumed but never awaited, so an accidentally async callback cannot leak an unhandled rejection or silently create a second hook contract.
• Hooks run only after terminal mismatch confirmation, inside detached shadow work — never on the request path. Same discipline as the comparator: synchronous, bounded, non-mutating.

What a warning looks like

DialCache shadow validation mismatch {
  cacheNamespace: "urn",
  useCase: "GetUser",
  keyType: "user_id",
  outcome: "mismatch",
  cachedValueAgeSeconds: 5243.7,
  cacheKey: "{urn:user_id:123}#GetUser",
  diffJson: '[{"type":"CHANGE","path":["updatedAt"],"value":"2026-08-14T01:02:03.000Z","oldValue":"2026-08-13T22:10:00.000Z"}]'
}

The built-in diff

No new dependencies: the built-in diff is a small own-key differ over the native-JSON forms of both sides — each side is rendered once and the value fields and diff derive from the same snapshot, so toJSON redaction and serializer normalization bound the diff exactly as they bound value logging. Entries are { type: "CREATE" | "REMOVE" | "CHANGE", path, value, oldValue }, oriented cached → source (oldValue is what Redis had). A side with no JSON rendering (top-level undefined, cycles, bigint, or a thrown or promise-like hook result) fails the diff closed to null.

• The diff is computed over the loggable forms: both sides render to native JSON first, so toJSON redaction and serializer normalization bound the diff exactly as they bound value logging — no leaking fields toJSON hides, and no phantom entries when a deserialized ISO string meets a live Date of the same instant.
• Roots of the same container kind diff recursively; primitives and mixed object/array roots collapse to a single root-level change entry.
• diffJson: "[]" means the loggable inputs held no visible difference — with a projector, that reads as "the difference is inside fields you chose not to log", which is itself a useful signal.
• Known noise, documented and pinned by tests: arrays compare by index (a shift reports every later index), and the diff shows structural differences even in fields a custom comparator ignores. It's debugging evidence, not the comparator's verdict.

Migration — breaking API, compatible runtime

Before	After
shadow: { logMismatches: true }	shadow: { mismatchLogging: { key: true, value: true } }
shadow: { logMismatches: false }	omit mismatchLogging (or set fields to false)

shadow.logMismatches is no longer read, but older default or runtime config carrying it does not break cache resolution. It is ignored like any unknown field, recognized fields still apply, and DialCache emits the bounded config_unknown_field signal. The old true value therefore does not enable mismatch logging; migrate to mismatchLogging to retain that behavior.

Review

A six-lane review (correctness, tests, simplicity, architecture, contracts, security, plus a two-stage holistic audit) ran against the feature; all 10 accepted findings are fixed in the follow-up commit: diff-input normalization (the toJSON/serializer asymmetries above), one cap owner for diffJson, own-property-only runtime shadow config reads (prototype pollution and Object.create-carried leaves can neither enable payload logging nor admit shadow work), documented-and-pinned config_error semantics for a malformed mismatchLogging group (matching the layer-map precedent), an exhaustive compile-checked leaf list, and removal of the dead emit-time fallback (every warning field now fails closed to null independently).

A follow-up correctness and simplicity review closed the async-hook rejection leak. A later compatibility pass made unknown key-config fields permissive across defaults and runtime overlays: normalization keeps only recognized fields, one bounded metric reports each affected config, and known malformed values retain their existing validation.

Testing

• pnpm typecheck · pnpm test (559 passing, ~97.7% coverage) · pnpm build · pnpm test:package (packed ESM + CJS consumers) · CI pnpm test:integration (all 139 Redis and cluster tests passing).
• Warning content per flag combination, projection on both sides, per-side projector throw or promise-like return → null, projection failure nulling the built-in diff, one projection per side feeding value + diff together, custom diff hook receiving raw values (and staying idle when diff is off), promise-like custom-diff results failing closed without unhandled rejection, hooks staying idle on superseded, per-leaf invalid runtime config, unknown fields at every key-config scope (including explicit undefined and both legacy shadow fields) being ignored with one bounded metric while recognized fields remain effective, leaf-wise merge, and clone/freeze.
• Diff edge behavior pinned: CREATE entries, nested Date → ISO strings, array-shift noise, mixed-kind nodes, unrenderable sides and cyclic inputs failing closed to null, own-member traversal, and single-render toJSON consistency.

🤖 Generated with Claude Code

BREAKING CHANGE: ShadowConfig.logMismatches was replaced by the shadow.mismatchLogging content group ({ key, value, diff }); the previous logMismatches: true behavior is mismatchLogging: { key: true, value: true }. Legacy logMismatches fields are ignored at runtime and emit config_unknown_field rather than failing cache resolution, but they no longer enable logging, so migrate config stores to retain that behavior.

[lan17]

Blocking review: I found six issues that should be addressed before merge. Five are attached inline.

The remaining release blocker is:

[P1] Add an exact BREAKING CHANGE: footer to the PR body. The migration heading is useful to human readers, but this repository's conventionalcommits release generator only recognizes the footer form called for in README.md. Because squash commits use the PR body, the generated release notes will otherwise omit the breaking-change section. That is especially risky here: stale shadow.logMismatches runtime config fails resolution and bypasses caching for each affected invocation, so operators need the config-before-code deployment order surfaced in release notes.

All seven checks are green, and I also ran the full local check successfully (typecheck, 551 tests, build/declarations, and packed ESM/CJS package validation). The exact-head CI integration run passed 139 Redis/Valkey tests. The targeted cases in the inline findings are not covered by those checks.

[lan17]

One blocking finding remains after the follow-up commit. The other five findings from the prior review are fixed, and the exact-head local/CI validation is green, but the prototype-data boundary for the built-in diff is still incomplete. Details are attached inline.

[lan17]

Correction to my previous review: I withdraw the remaining inherited-prototype blocker. It applied a hostile-intrinsics threat model that does not match this feature’s trusted-value boundary.

The current head now keeps the design deliberately simple: one native JSON snapshot per side, a private parsed JsonValue, own-member structural traversal, and ordinary bounded JSON serialization. The custom prototype-hardening code, tests, and claims have been removed.

The other five findings remain addressed. Full local validation passed (typecheck, 560 tests, build/declarations, and packed ESM/CJS package checks); Redis integration passed 137 tests with the two GLIDE Cluster cases skipped by the local Docker environment. All current GitHub checks pass. I have no remaining findings from this review.