Detector score cache

The cache is Skryba's record of detector probabilities: the scores table of its fleet database. It prevents a repeated score for identical text from billing the same detector endpoint and revision again, on any machine that reaches the same database.

Location

The schema skryba, or the one SKRYBA_DATABASE_SCHEMA names. There is no cache file.

Schema

CREATE TABLE skryba.scores (
  detector TEXT NOT NULL,
  text_hash TEXT NOT NULL,
  probability DOUBLE PRECISION NOT NULL,
  created_at BIGINT NOT NULL DEFAULT extract(epoch FROM now())::BIGINT,
  PRIMARY KEY (detector, text_hash)
);

text_hash is lowercase hexadecimal SHA-256 over the exact UTF-8 input. Whitespace changes therefore create a different entry.

The detector key is a cache namespace, not only the short provider name:

<name>:<revision>:<endpoint>

Changing provider revision or endpoint cannot reuse the old response accidentally.

Lifecycle

1. Connect to the fleet database and create scores if absent.
2. Before an HTTP request, look up (cache_namespace, sha256(text)).
3. A hit returns the probability with cached: true and skips rate limiting and HTTP.
4. A miss is requested, parsed, normalized, and upserted with a fresh created_at; the result says cached: false.

There is no expiration or automatic pruning. Deleting rows from scores discards cached scores; do this only when deliberately accepting re-billing.

Invariants and failures

• Cache writes occur only after a successful provider response and valid probability extraction.
• A failed or malformed response is never cached.
• Concurrent detectors share one database connection; each read and write is one statement.
• Creation failures begin creating the detector score cache in stado://database/skryba/<SCHEMA>.
• Read and write failures begin reading a cached <DETECTOR> score from … and caching a <DETECTOR> score in ….

Within one candidate group the cache cannot help: the group is scored concurrently, so every request is in flight before the first result is written and all of them miss. Identical candidate texts are therefore collapsed before they leave — one measurement, shared by every position holding that text — rather than left to a cache that cannot see them yet.

The scoring walkthrough captures the same score first with cached: false, then with cached: true. The local-generator walkthrough captures the group collapse: 16 candidates, 9 distinct texts, 9 requests.