Refactor internal execution around explicit invocation and subsystem boundaries

[lan17]

Summary

Refactor DialCache's internal implementation to make the cache execution model easier to reason about and safer to extend, without changing the public API, Redis protocol, cache keys, metrics semantics, or runtime behavior.

The preferred direction is an internal invocation snapshot plus a small set of explicit subsystem boundaries. A wrapper / chain-of-responsibility structure similar to the earlier GCache design is worth evaluating for the ordered cache layers, provided it does not hide cross-layer invariants or add measurable hot-path overhead.

Motivation

DialCache currently coordinates most of the product in one central class:

• cached-definition registration and validation;
• key construction;
• runtime policy resolution;
• request-local memoization and single-flight;
• process-scoped single-flight;
• local and Redis traversal;
• fallback deadlines;
• local and remote publication rules;
• stale-on-error recovery;
• detached shadow admission and execution;
• invalidation;
• logging and metrics isolation;
• coalescing state and detached-flight state.

The implementation is careful, but each new feature now intersects several branches of the same state machine. Long argument lists and distributed publication rules make it increasingly difficult to prove that an internal change preserves:

• exactly one source invocation per admitted coalesced flight;
• request-local snapshot semantics;
• tracked versus untracked local-publication rules;
• fallback-error precedence;
• stale-recovery eligibility and snapshot ownership;
• shadow deadlines and capacity release;
• exact metric populations and labels;
• observer isolation;
• fail-open behavior.

The goal is not abstraction for its own sake. It is to make these invariants visible and localize future changes.

Proposed direction

1. Introduce one immutable internal invocation snapshot

Conceptually:

interface CacheInvocation<Value> {
  readonly definition: NormalizedCacheDefinition<Value>;
  readonly key: DialCacheKey;
  readonly policy: ResolvedCachePolicy;
  readonly fallback: () => Promise<Value>;
  readonly deadlines: ResolvedInvocationDeadlines;
  readonly labels: DefinitionMetricLabels;
}

The exact fields are implementation details. The important property is that definition identity, resolved policy, labels, and deadlines are captured once and passed through execution rather than reconstructed or reread across branches.

This should align with the layer-first configuration work in #144, but it must not block on the public config migration.

2. Separate the main internal responsibilities

A reasonable target module split is:

definition.ts       registration normalization and stable definition snapshots
policy.ts           static/default/runtime merge and resolved layer policy
invocation.ts       immutable invocation state and execution entry point
coalescing.ts       request-local and process flight ownership/accounting
lookup.ts           ordered cache traversal
publication.ts      local/remote publication decisions and fail-open writes
stale-recovery.ts   retained-candidate classification and recovery
shadow.ts           detached shadow state machine and capacity
observer.ts         safe logging/metrics dispatch

The names are illustrative. Avoid creating public strategy interfaces or exposing these modules from the package.

3. Evaluate wrappers for the ordered cache chain

The cache layers may fit a statically composed handler shape:

type CacheHandler<Value> = (
  invocation: CacheInvocation<Value>,
) => Promise<Value>;

const execute = withRequestLocal(
  withProcessCoalescing(
    withLocalCache(
      withRemoteCache(callFallback),
    ),
  ),
);

This is attractive when each wrapper owns one clear concern and delegates exactly once. Do not force stale recovery, shadow work, invalidation, or publication into generic middleware if doing so obscures their semantics. An explicit orchestrator plus focused subsystem objects is preferable to a clever but opaque pipeline.

4. Refactor incrementally

Suggested order:

1. Introduce normalized definition/invocation snapshots with no behavior change.
2. Extract coalescing state and operations.
3. Extract shadow execution, which is already a largely independent state machine.
4. Extract publication rules.
5. Evaluate whether the remaining lookup chain benefits from wrappers.

Avoid a single big-bang rewrite.

Constraints

• No public API or export changes.
• No Redis key, frame, watermark, command, routing, or adapter-contract changes.
• No cache serving, publication, invalidation, shadow, stale-recovery, deadline, or coalescing behavior changes.
• No new generic plugin or strategy system.
• No dependency addition solely for architecture.
• Preserve synchronous leader registration before user fallback work begins.
• Preserve exact request-local and process-flight accounting.
• Preserve metrics and logger failure isolation, including returned thenables.
• Preserve the ability to inspect exact coalescing state.
• Keep hot paths allocation-conscious; architecture changes need before/after measurements through Add a repeatable performance and scale benchmark suite #35.

Acceptance criteria

• One internal invocation snapshot carries normalized definition identity, resolved policy, deadlines, and stable metric metadata through execution.
• Definition normalization and runtime policy resolution have clear, separate ownership.
• Request-local and process coalescing state/logic no longer live interleaved with the full cache traversal.
• Shadow validation is isolated behind one focused internal boundary with unchanged admission, deadline, outcome, and release semantics.
• Local and remote publication decisions have one identifiable owner rather than being distributed across unrelated branches.
• The ordered lookup path is materially easier to follow, whether implemented through wrappers or an explicit orchestrator.
• Existing unit, integration, packed ESM/CJS, forced-GC, and liveness tests remain unchanged in meaning and pass.
• Focused characterization tests pin any behavior that must be moved before the refactor begins.
• Current-main benchmark baselines are recorded before the change; no material request-local/process-local hot-path regression is accepted without explicit justification.
• No public declarations, Redis bytes, metric names/labels, log contracts, or rollout behavior change.

Non-goals

• Public cache-layer plugins.
• User-defined middleware.
• Replacing the existing cache semantics.
• Combining this with config-schema, invalidation-coherence, write-behind, or circuit-breaker work.
• Optimizing code without measurements.

Related

• Add a repeatable performance and scale benchmark suite #35 — repeatable performance and scale benchmark suite.
• Establish a local-hit performance budget and remove avoidable hot-path work #43 — local-hit performance budget and hot-path work.
• Refactor cache config to group policy by layer #144 — layer-first public configuration shape.
• Rationalize the root export surface and scope-method vocabulary #24 — public export and vocabulary cleanup.