Compile a Cache-Key Atlas From Source Prefixes; Hand-Write TTL, Invalidation, and PII

Cache-key documentation fails when a compiler lists prefixes while TTL, invalidation, and PII stay unsigned. Generated inventories can stay complete across refactors, but they cannot decide retention, blast radius, or customer data class. This workflow compiles a prefix atlas from source, then fails the docs build until a human overlay signs every risk cell. Treat model drafts as grouping notes and cluster labels, never as production cache policy you can ship.

Why prefix lists rot without a signed overlay

Most production services accumulate Redis, Memcached, or local LRU keys without a single owned catalog. Engineers copy string templates into new modules, then operations discover a flush command only during an incident review. A generated atlas keeps the prefix set honest when identifiers move, but honesty about strings is not honesty about data lifetime.

A compiler can see prefixes such as user:profile: and session:v2: in the tree with high recall. It cannot know whether a profile blob includes email, or whether a session key may be deleted by user request. Those answers live in product policy, legal review, and on-call ownership, which source constants do not encode.

What the compiler and a model may draft

The mechanical lane should emit only facts that a parser can defend from the repository. Allowed outputs include prefix literals, file locations, setter and deleter symbols, plus optional clustering suggestions from nearby comments. Optional notes may group prefixes by package, but grouping is a draft, not an approved domain model.

Teams that already use MonkeyCode can run the extractor on the free server option and request overlay notes from free model access.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Free model access is useful for clustering similar prefixes and proposing short descriptions from nearby comments. The free server option is useful for running the extractor as a scheduled job without mixing that run into production cache nodes. Neither output should write TTL seconds, PII class, or invalidation owners into the signed overlay automatically.

What a human must own before merge

Every prefix row needs four signed cells before the documentation site is allowed to publish. Those cells are default TTL, invalidation triggers, PII class, and the on-call owner who may flush the keyspace. If any cell is empty, the docs build should fail with a stable identifier, not a warning that busy reviewers will skip.

Do not let a model fill those cells from nearby comments or from similar keys in another service. Comments drift, and similarity is not a legal basis for retention or for customer deletion behavior. Human signature means a reviewed overlay file in source control, not a chat transcript attached to a pull request.

Artifact: extract prefixes, then require an overlay

The following Python example is a labeled, unexecuted extractor for demonstration of the compile lane. It walks a tree for string prefixes that look like cache templates, then writes a JSON atlas the overlay must cover. Adjust the regex to your client library before you treat the output as complete.

#!/usr/bin/env python3
"""Labeled example: compile cache prefix candidates from source strings."""
from __future__ import annotations

import json
import re
import sys
from pathlib import Path

PREFIX_RE = re.compile(
    r"""(?x)
    (?P<quote>['"])
    (?P<prefix>
        [a-z][a-z0-9_]{1,32}:
        (?:[a-z0-9_]{1,32}:){0,3}
    )
    (?P=quote)
    """
)

SKIP_PARTS = {".git", "node_modules", "vendor", "dist", "__pycache__"}
CODE_SUFFIXES = {".py", ".go", ".ts", ".js", ".rb", ".java"}

def iter_files(root: Path):
    for path in root.rglob("*"):
        if not path.is_file() or path.suffix not in CODE_SUFFIXES:
            continue
        if any(part in SKIP_PARTS for part in path.parts):
            continue
        yield path

def extract(root: Path) -> list[dict]:
    found: dict[str, dict] = {}
    for path in iter_files(root):
        text = path.read_text(encoding="utf-8", errors="replace")
        for match in PREFIX_RE.finditer(text):
            prefix = match.group("prefix")
            rel = str(path.relative_to(root))
            row = found.setdefault(
                prefix,
                {"prefix": prefix, "files": [], "count": 0},
            )
            row["count"] += 1
            if rel not in row["files"]:
                row["files"].append(rel)
    return sorted(found.values(), key=lambda r: r["prefix"])

def main() -> int:
    root = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
    atlas = extract(root)
    Path("cache_prefix_atlas.json").write_text(
        json.dumps({"prefixes": atlas}, indent=2) + "\n",
        encoding="utf-8",
    )
    print(f"wrote {len(atlas)} prefixes")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

The overlay is a separate YAML file that humans edit and that reviewers must sign. The example below shows required cells and the only values the gate will accept for PII class. Keep risk cells out of the generator even when a model proposes confident wording for TTL.

# cache_prefix_overlay.yaml — human-owned; do not generate the risk cells
prefixes:
  "user:profile:":
    ttl: "15m"
    invalidation:
      - "user profile write"
      - "account deletion"
    pii_class: "direct_identifier"
    flush_owner: "identity-oncall"
    notes: "Contains display name and email hash; never store raw password."
  "session:v2:":
    ttl: "12h"
    invalidation:
      - "logout"
      - "password reset"
    pii_class: "session_token"
    flush_owner: "identity-oncall"
    notes: "Opaque token only; payload lives in the session store schema."
  "catalog:rendered:":
    ttl: "5m"
    invalidation:
      - "catalog publish"
    pii_class: "none"
    flush_owner: "catalog-oncall"
    notes: "Public HTML fragment; safe to flush globally."

Numbered workflow the docs job should run

1. Compile the atlas from the current commit so renamed prefixes cannot hide inside stale Markdown pages. Store the atlas JSON as a build artifact, and never treat that file as the published contract page.
2. Load the human overlay and join on prefix string equality, not on fuzzy model similarity. Missing keys, extra keys, and empty risk cells must remain hard errors in the documentation job.
3. Allow a model to propose cluster labels and one-line descriptions into a scratch file that never merges. Reviewers may copy wording from that scratch file, but they must paste it into the overlay themselves.
4. Render the joined table into documentation only after the gate passes, including TTL, invalidation, PII class, and flush owner. Publish only the rendered table, and never publish the raw model scratch file as documentation.
5. Fail pull requests that add a setter for an unsigned prefix, even when the Markdown file was not touched. Cache policy is a code change, not a writing task that documentation authors can finish later.

A small join gate keeps the overlay rule mechanical and prevents undocumented prefixes from reaching the docs site. The following Python listing is also a labeled example, not a production-hardened linter for every language. Copy it into the documentation job image only after you add tests for missing and stale keys.

#!/usr/bin/env python3
"""Labeled example: fail if atlas prefixes lack a signed overlay row."""
from __future__ import annotations

import json
import sys
from pathlib import Path

import yaml  # PyYAML; install in the docs job image

ALLOWED_PII = {
    "none",
    "indirect",
    "direct_identifier",
    "session_token",
    "secret",
}
REQUIRED = ("ttl", "invalidation", "pii_class", "flush_owner")

def load_overlay(path: Path) -> dict:
    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
    return data.get("prefixes") or {}

def main() -> int:
    atlas = json.loads(Path("cache_prefix_atlas.json").read_text(encoding="utf-8"))
    overlay = load_overlay(Path("cache_prefix_overlay.yaml"))
    errors: list[str] = []
    atlas_keys = {row["prefix"] for row in atlas["prefixes"]}
    overlay_keys = set(overlay)

    for prefix in sorted(atlas_keys - overlay_keys):
        errors.append(f"UNSIGNED_PREFIX {prefix}")
    for prefix in sorted(overlay_keys - atlas_keys):
        errors.append(f"STALE_OVERLAY {prefix}")

    for prefix in sorted(atlas_keys & overlay_keys):
        row = overlay[prefix] or {}
        for field in REQUIRED:
            if not row.get(field):
                errors.append(f"EMPTY_CELL {prefix}.{field}")
        pii = row.get("pii_class")
        if pii and pii not in ALLOWED_PII:
            errors.append(f"BAD_PII_CLASS {prefix}={pii}")
        inv = row.get("invalidation")
        if inv is not None and not isinstance(inv, list):
            errors.append(f"INVALIDATION_NOT_LIST {prefix}")

    if errors:
        print("cache overlay gate failed:")
        for item in errors:
            print(f"  - {item}")
        return 1
    print(f"signed {len(atlas_keys)} cache prefixes")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

Wire both scripts into the documentation pipeline and keep the working directory at the repository root. The commands below assume the repository root remains the current directory during local and CI runs. Do not run the extractor against production cache nodes, because this job only reads source files.

python3 tools/extract_cache_prefixes.py .
python3 tools/gate_cache_overlay.py

Decision table for the signed cells

Use a small matrix so reviewers do not invent one-off PII labels per pull request. The table is a policy aid, not a substitute for legal review on regulated datasets. Extend the allowed PII set in code and in this table together, never in only one place.

TTL is not a security control when the value is a secret or a session token. Short expiry reduces window size, but revocation still needs an explicit delete path that operators can run. If the overlay lists a secret class with only TTL and no invalidation event, the gate should be extended to reject that pair.

Limitations

Regex extraction undercounts dynamic prefixes that are built from several fragments or from helper functions. AST-aware extractors for one language will miss the other languages in a polyglot repository, which is why the gate also flags stale overlay rows. Neither the atlas nor a model draft can prove that production clusters actually use the same prefix set as the commit.

False positives appear when URL paths or metric names share a colon-delimited shape with cache keys. Maintain a deny list of known non-cache prefixes rather than asking a model to guess intent from the identifier alone. Human reviewers still need to open the setter when PII class is not obvious from the template string.

This method does not measure hit ratio, stampede behavior, or the correctness of cache-aside logic. Those operational properties belong in service dashboards and load tests, not in a documentation overlay file. Do not treat a green overlay gate as evidence that eviction policy is safe under failover.

Who should not use this approach

Do not adopt this split if the team cannot name a flush owner for each prefix family. An unsigned atlas is worse than no page, because it implies completeness the incident channel cannot use. Skip the model drafting lane entirely when the repository contains unpublished customer payloads in comments or in fixture files.

Small apps with a handful of keys and one datastore may maintain a single hand-written table without an extractor. The compiler earns its keep when prefixes sprawl across packages and when refactors silently drop documentation rows. Regulated workloads still need counsel to confirm PII class; the overlay is an engineering control, not a legal opinion.

Keep the atlas generated, keep the risk cells human, and keep the docs job failing closed. If MonkeyCode is already available in your org, run the extractor on one service before expanding the signed overlay. A single service overlay will expose whether your prefixes are templates, metrics, or routes before you scale the gate.