@osqd/bothandlerjs 0.6.0 → 0.7.0

package/dist/stores/redis.d.ts

@@ -9,7 +9,6 @@ import type { Clock } from "../internal/clock.js";
  */
 export interface RedisLike {
     incr(key: string): Promise<number>;
-    pexpire(key: string, ms: number): Promise<unknown>;
     /**
      * `SET key value PX ttl [NX]`.
      *
@@ -51,6 +50,30 @@ export declare class RedisStore implements BotHandlerStore {
     private readonly prefix;
     private readonly clock;
     constructor(client: RedisLike, options?: RedisStoreOptions);
+    /**
+     * Counts one request into the fixed window `key` is bucketed by.
+     *
+     * This used to be `INCR`, then `PEXPIRE` when the count came back as 1 — which is
+     * correct only if the process survives long enough to send the second command. A
+     * deploy, an OOM kill or a dropped connection in between left a counter key behind
+     * with no expiry at all, and nothing would ever clean it up: the next request falls
+     * into the next bucket, under a different key, so the orphan is never touched again.
+     * One per unlucky restart is nothing; the point is that it accumulates forever, in a
+     * Redis the operator may well be running with `noeviction`.
+     *
+     * So the expiry is armed by the command that *creates* the key rather than by a
+     * follow-up. `SET … PX … NX` writes the seed only if nothing is there, always with a
+     * lifetime, and does nothing at all once the bucket exists — so it neither costs a
+     * count nor re-arms a window under load. The `INCR` is issued without waiting for its
+     * reply, so both commands are on the wire together and this stays one round trip.
+     * Ordering holds because a Redis client writes commands to its connection in call
+     * order and Redis executes them in arrival order, which means the key has a lifetime
+     * from the instant it exists.
+     *
+     * Not a Lua script, which would make it a single command: `eval` is the one thing
+     * `ioredis` and `node-redis` spell differently enough that this interface could not
+     * describe both, and staying client-agnostic is worth more than the last round trip.
+     */
     increment(key: string, windowMs: number): Promise<number>;
     consumeOnce(key: string, ttlMs: number): Promise<boolean>;
     get(key: string): Promise<string | undefined>;

package/dist/types.d.ts

@@ -7,6 +7,7 @@
  * detection is a solved problem: probabilistic signals exist, they are useful, and
  * they are structurally barred from reaching a terminal action.
  */
+import type { MarkerObservation } from "./probe/index.js";
 /** What kind of client we believe we are talking to. */
 export type BotClass = 
 /** Positive evidence of a person driving a real browser. */
@@ -92,6 +93,15 @@ export interface Evidence {
     deterministicBasis?: string | undefined;
     /** Structured detail for logs and dashboards. Must be JSON-serialisable. */
     metadata?: Record<string, unknown> | undefined;
+    /**
+     * Set when this came from a detector named in {@link BotHandlerConfig.shadowDetectors}.
+     *
+     * It is a label rather than a mechanism: shadowed evidence never reaches scoring at
+     * all, because it is kept in {@link Assessment.shadowEvidence} rather than filtered out
+     * of {@link Assessment.evidence} later. The flag is here so that anything rendering the
+     * two lists together can say which is which.
+     */
+    shadow?: true | undefined;
 }
 /**
  * Every verdict and class, in a fixed order.
@@ -128,6 +138,21 @@ export interface RequestFacts {
     method: string;
     /** Path only, no query string. Always begins with `/`. */
     path: string;
+    /**
+     * The target as the client actually spelled it, present only when that is not how
+     * `path` reads.
+     *
+     * `path` is normalised — decoded once, backslashes and doubled slashes collapsed, dot
+     * segments resolved — because a rule scoped to `/admin` has to hold against `/%61dmin`
+     * and `/./admin` too. That normalisation is also the only thing that makes an evasive
+     * target look ordinary: `/%2e%2e%2f%2e%2e%2fapp/config.yml` becomes `/app/config.yml`.
+     * This is where the difference is kept, so `target-integrity` can read it.
+     *
+     * Absent on the overwhelming majority of requests, which is the whole reason it is
+     * cheap: its presence already means the target was spelled unusually, though not
+     * necessarily suspiciously — a trailing slash is enough.
+     */
+    rawPath?: string | undefined;
     /** Decoded query parameters. Null-prototype so `?__proto__=x` is visible, not swallowed. */
     query: Record<string, string>;
     /** Lowercased header names to values. Multi-value headers are joined with `, `. */
@@ -214,6 +239,13 @@ export interface ActorSnapshot {
         count: number;
         span: number;
     } | undefined;
+    /**
+     * A name somebody gave this actor. Never read by detection.
+     *
+     * An address is not a memory: whoever worked out that one belongs to a partner's price
+     * feed should be able to write it where the next person will see it.
+     */
+    label?: string | undefined;
     /** First and last sighting, ms since epoch. */
     firstSeen: number;
     lastSeen: number;
@@ -255,6 +287,36 @@ export interface Assessment {
     evidence: Evidence[];
     /** Every human-pointing observation. These rebut and dampen the score. */
     humanEvidence: Evidence[];
+    /**
+     * What the shadowed detectors said, in both directions, and what none of it did.
+     *
+     * A detector listed in {@link BotHandlerConfig.shadowDetectors} runs exactly as it
+     * otherwise would and its findings land here instead of in `evidence` — so they are
+     * counted, charted and readable, and they took no part in the verdict, the score, the
+     * class, the identity, or any rule. Not "weighted at zero": kept out of the arithmetic
+     * altogether, because a `certain` finding does not go through the arithmetic and a
+     * weight of zero would not have stopped it.
+     *
+     * This is how a new detector, or a threshold nobody is sure of yet, is answered with a
+     * week of your own traffic rather than with an argument.
+     */
+    shadowEvidence: Evidence[];
+    /**
+     * What this assessment would have been had the shadowed detectors been counted.
+     *
+     * Present only when a shadowed detector actually found something, which is what keeps
+     * the second pass off the hot path for the requests it would say nothing about.
+     *
+     * "It fired 312 times" is not the question anybody has. The question is what turning it
+     * on would *do*, and the only honest form of that is the verdict this request would
+     * have received — including, and especially, when it is a person.
+     */
+    shadowVerdict?: {
+        verdict: Verdict;
+        botClass: BotClass;
+        score: number;
+        certain: boolean;
+    } | undefined;
     actor: ActorSnapshot;
     /**
      * Set when detection was skipped rather than performed. `undefined` means every
@@ -268,6 +330,14 @@ export interface Assessment {
     /** Detectors that threw or timed out. Detection continues without them. */
     failures: DetectorFailure[];
     facts: RequestFacts;
+    /**
+     * What the marker cookie on this request turned out to be, when the probe is on.
+     *
+     * An input rather than a conclusion, kept here for the same reason `facts` is: the
+     * action path needs it to decide whether this response should carry a new marker, and
+     * recomputing it would mean verifying the same HMAC twice on every request.
+     */
+    marker?: MarkerObservation | undefined;
 }
 /** Why an assessment skipped detection. */
 export type BypassReason = 

package/docs/course/05-detectors.md

@@ -1,6 +1,6 @@
 # Lesson 5 — The detectors
 
-**Goal:** know what each of the twenty detectors reads, what it costs, and what it is
+**Goal:** know what each of the detectors reads, what it costs, and what it is
 allowed to conclude — then turn one off and watch the score move.
 
 ← [Course](index.md) · Prev: [The guard](04-the-guard.md) · Next: [Identity and verification](06-identity.md)
@@ -36,7 +36,7 @@ browsing-coherence     cheap  always
 crawler-verification   io     confirming
 ```
 
-**Sixteen of twenty ship on by default.** The other four —
+**Twenty-two ship on by default.** The others —
 `identity-rotation`, `tls-fingerprint`, `clearance`, `client-signals` — each need something
 from you, and you will switch three of them on later in the course.
 
@@ -61,7 +61,7 @@ fails closed is an outage with extra steps.
 
 | Detector | Ceiling | Reads |
 | -------- | ------- | ----- |
-| `self-identified` | `certain` | 161 signatures, 389 tokens, in one Aho–Corasick pass. Also catches unrecognised crawlers that name a contact URL, and bare client tokens with no browser preamble |
+| `self-identified` | `certain` | 205 signatures, 389 tokens, in one Aho–Corasick pass. Also catches unrecognised crawlers that name a contact URL, and bare client tokens with no browser preamble |
 | `crawler-verification` | `certain` | Forward-confirmed reverse DNS, or published address ranges. **Confirms and refutes** |
 
 ### Single-request consistency
@@ -84,8 +84,9 @@ fails closed is an outage with extra steps.
 | `crawl-breadth` | `weak` | Distinct paths against total requests: reading a site against enumerating it |
 | `parameter-sweep` | `weak` | Distinct query strings against the paths they sit on. Catches the collection that leaves the path unchanged — `?page=1..200` |
 | `session-integrity` | `moderate` | A "browser" that never carries a cookie |
+| `blended-identity` | `strong` | The *set* of identities one actor claimed: two scanners, or two crawlers that cannot both be true |
 | `id-enumeration` | `moderate` | A contiguous run of numeric ids under one path shape — walking `/user/1..n` rather than following links |
-| `probe-volume` | `moderate` | The share of an actor's requests answered 404. Needs `recordOutcome`; the Node adapter wires it up |
+| `probe-volume` | `moderate` | The share of an actor's requests answered 404. Needs `recordOutcome`; every bundled adapter wires it up |
 | `transport-coherence` | `moderate` | The HTTP version and the verbs across a visit: a "Chrome" on HTTP/1.0, a visit made only of HEAD |
 | `identity-rotation` | `moderate` | One actor, several User-Agents. **Off by default** — under an IP actor key this fires on every corporate NAT |
 | `browsing-coherence` | `moderate` | The only detector arguing *for* the client. Human-pointing, so it discounts |
@@ -167,7 +168,7 @@ IP-based actor key.
 
 ## What you learned
 
-- Sixteen of twenty detectors are on by default; the rest need something from you
+- Twenty-one detectors are on by default; the rest need something from you — a marker probe, a challenge, a site baseline, or data only you have
 - `cost` and `stage` decide when a detector runs, and confirming work is skipped when
   nothing claimed an identity
 - A failing detector is dropped, never the request

package/docs/course/06-identity.md

@@ -9,7 +9,7 @@ a name alone is worth so little.
 
 ## A name is a claim, not a fact
 
-`self-identified` matches 161 signatures across search, AI, SEO, social, monitoring,
+`self-identified` matches 205 signatures across search, AI, SEO, social, monitoring,
 feeds, archives, security tooling, HTTP libraries and headless runtimes. When it fires you
 get an `identity` — `"googlebot"`, `"gptbot"` — and a `category`.
 

package/docs/course/16-proving-it.md

@@ -13,29 +13,35 @@ everything into a Serif you can defend.
 
 Three tools answer it, and they answer different halves.
 
-## `check` — against 526 shapes of real traffic
+## `check` — against 548 shapes of real traffic
 
 ```bash
 npx @osqd/bothandlerjs check --preset protect-content
 ```
 
 ```
-  protect-content against 522 shapes of real traffic
+  protect-content against 539 shapes of real traffic
 
-  human            181 cases   3 tag, 175 allow, 3 challenge
-  benign-bot       144 cases   6 allow, 86 tag, 48 block, 2 challenge, 2 rate-limit
-  declared-bot      32 cases   18 tag, 2 rate-limit, 3 allow, 9 block
-  unwanted-bot     105 cases   8 tag, 11 rate-limit, 3 block, 70 challenge, 13 allow
-  hostile           27 cases   6 challenge, 17 block, 4 allow
-  infrastructure    33 cases   7 allow, 12 tag, 14 challenge
+  human            184 cases   178 allow, 3 tag, 3 challenge
+  benign-bot       144 cases   86 tag, 48 block, 6 allow, 2 challenge, 2 rate-limit
+  declared-bot      32 cases   18 tag, 9 block, 3 allow, 2 rate-limit
+  unwanted-bot     109 cases   71 challenge, 16 allow, 11 rate-limit, 8 tag, 3 block
+  hostile           37 cases   20 block, 9 allow, 7 challenge, 1 tag
+  infrastructure    33 cases   14 challenge, 12 tag, 7 allow
 
   No case marked as a person was denied service.
 ```
 
+The corpus holds 548 cases and this run reports 539, which is not a discrepancy: a case
+naming a capability the configuration under test does not provide is *skipped* rather than
+failed. The nine here need a marker probe or a site baseline, and judging a marker case
+against a configuration that issues no markers would be a verdict about nothing. Turn those
+sources on and the same command reports all 548.
+
 **It exits non-zero if any case marked `human` is denied**, which is what makes it a CI step
 rather than a report.
 
-The corpus is 526 cases with provenance: 182 of them people — 30 browser profiles, 40 in-app
+The corpus is 548 cases with provenance: 186 of them people — 30 browser profiles, 40 in-app
 WebViews, Tor, screen readers, IE11, a car's infotainment screen, corporate proxies, CGNAT,
 an author signing in at `/wp-login.php`. Header order is reproduced rather than invented, and
 DNS is controlled rather than mocked away, so *"the operator's DNS disproves this"* and

package/docs/course/index.md

@@ -58,7 +58,7 @@ lesson 11.
 
 | | | |
 |-|-|-|
-| 5 | [The detectors](05-detectors.md) | All twenty: what each reads, what each costs, what each may conclude. |
+| 5 | [The detectors](05-detectors.md) | All twenty-two: what each reads, what each costs, what each may conclude. |
 | 6 | [Identity and verification](06-identity.md) | Recognising a crawler by name — and proving or refuting the claim. |
 | 7 | [Actors and behaviour](07-actors.md) | Who "the same client" is, and what watching one over time tells you. |
 | 8 | [Traps](08-traps.md) | The one detector that needs no statistics, and how to lay one properly. |

package/docs/design/decisions.md

@@ -187,7 +187,7 @@ type checker catches something.
 
 ## The corpus is a published entry point, not a test fixture
 
-**The decision.** `@osqd/bothandlerjs/corpus` ships `runCorpus` and all 526 cases.
+**The decision.** `@osqd/bothandlerjs/corpus` ships `runCorpus` and all 548 cases.
 
 **Why.** The claims in this documentation are only worth anything if you can check them
 against *your* configuration. A corpus locked inside the test suite proves things about the

package/docs/detection/correlation.md

@@ -0,0 +1,284 @@
+# Correlating a client's own requests
+
+Most of this library reads one request. A smaller and more valuable part reads a
+*series* — what an actor has done across many requests — because the tells that matter
+most are not visible in any single one. A wordlist scan is a hundred ordinary-looking
+404s. A scrape is a thousand ordinary-looking page loads. Nothing in any one of those
+requests is remarkable; the shape of all of them together is.
+
+This page is about the join: what makes two requests "the same client", and what each
+kind of join is worth.
+
+## The problem with joining on an address
+
+Every cross-request detector needs to decide which requests belong together, and until
+recently there was only one way to decide it — the **actor key**, derived from the
+client address. It is available on every request, it costs nothing, and it is wrong in
+both directions:
+
+- **It merges people who are unrelated.** An office, a school, a household and a mobile
+  carrier all put many people behind one address. Anything inferred about "the actor" is
+  really about a crowd.
+- **It splits a client that is one thing.** A scraper on a rotating proxy pool is a new
+  actor every few requests, and a phone changing networks is a new actor several times a
+  day.
+
+Both errors have teeth. The first is how a library ends up denying somebody for a
+stranger's behaviour. The second is how a scraper walks straight past every per-actor
+threshold by changing address more often than the threshold counts.
+
+One detector was left unwritten for exactly this reason. `identityRotationDetector` —
+the client that arrives as Chrome, then as curl, then as Googlebot — fires on any
+address fronting several browsers, which describes every corporate network on the
+internet. It ships, but it is not installed by default, and the note in
+`defaultDetectors()` says why: it is only safe once your actor key is narrower than an
+address.
+
+## The marker
+
+A marker is a signed cookie this server issues and reads back. It is off by default.
+
+```ts
+new BotHandler({
+  probe: { secrets: [process.env.MARKER_SECRET] },
+});
+```
+
+Two requests carrying the same marker came from the same client. Not the same address,
+not the same network — the same browser profile, because the marker holds an HMAC only
+this server can produce and only that client received. That single fact is what makes
+the rest of this page possible, and it is what turns "a client at this address claimed
+two identities" into "this client claimed two identities".
+
+It contains a random id, a validity window, and three short hashes standing for the
+identity claimed when it was issued. It carries no identifier of a person, is
+first-party, is `HttpOnly`, and expires on its own. Like every token here it is **signed
+and not encrypted**, so nothing secret may go in one.
+
+### What it costs
+
+Verifying a marker is an HMAC, and a session presents the same cookie on every request,
+so successful verifications are cached — with expiry re-checked on each hit, and failures
+never cached, since caching those would let anyone fill the cache with unique junk. The
+probe costs roughly 5% of an assessment with a marker held, and nothing at all when the
+client holds none.
+
+Network fan-out is sketched into 128 bits per marker rather than remembered as a set of
+addresses, which measured at 55.6 MB with both caps full. The estimate carries a few
+percent of error either way — 16 real networks read as 17 — so `marker-fanout`'s threshold
+is a soft boundary. With everything full the probe holds well under a megabyte.
+
+A `Set-Cookie` makes a response uncacheable by most shared caches, so the probe issues a
+marker **only when the client is not already holding a valid one** — for an ordinary
+visitor, the first request of a session and no other. That is also why the marker is not
+reissued to refresh it, and why verified crawlers are never issued one at all: Googlebot
+keeps no cookies, so a marker sent to it is a header that never comes back.
+
+### Secrets
+
+`secrets` is required, and deliberately has no default. A secret generated at startup
+would read every marker minted by another replica — or by this one before a restart — as
+*forged*, turning the strongest signal here into a machine for accusing ordinary
+visitors. The first secret signs and all of them verify, so rotation is a prepend
+followed by a removal one marker lifetime later.
+
+Rotation does not disturb anything. The identity hashes inside a marker are derived under
+a fixed salt rather than under the signing secret, precisely so that prepending a key
+does not silently re-describe every visitor as a different browser.
+
+## What the marker makes visible
+
+| Detector | Ceiling | Reads |
+| --- | --- | --- |
+| `identity-drift` | `strong` | The identity claimed now against the one claimed when the marker was issued |
+| `marker-integrity` | `strong` | A marker presented with a signature this server could not have produced |
+| `marker-fanout` | `moderate` | Distinct networks one marker has been presented from |
+| `marker-persistence` | `moderate` | A client that sends cookies but never returns the one this server set |
+| `challenge-reaction` | `strong` | What a client did in the seconds after it was challenged |
+| `challenge-integrity` | `moderate` | Solutions replayed, or returned faster than the puzzle allows |
+
+All of them are installed automatically when `probe` is configured and are absent
+otherwise, because a marker nobody issued is a marker nobody can fail to return.
+
+### Identity drift, and why the parts are weighed separately
+
+A **browser family** that changes — Chrome to curl, Firefox to Googlebot — has no benign
+reading. Software does not change what it is, so one of the two claims is false and the
+evidence is `strong`.
+
+A **platform** that changes does have a benign reading, and a common one: "Request
+desktop site" on a phone rewrites the User-Agent to claim a desktop, and the person doing
+it is a person. A language changes when somebody changes their language. Those are
+reported at `moderate` and named as the soft case in the summary, or turned off:
+
+```ts
+identityDriftDetector({ reportSoftDrift: false });
+```
+
+### Not returning the marker, and who that describes
+
+`marker-persistence` deliberately says nothing about a client that sends **no** cookies at
+all. That client is `session-integrity`'s business, and it already reports it at a weight
+chosen for the people who produce it — people who block cookies. Having both speak is one
+observation counted twice, landing on exactly that population: measured on the corpus, the
+overlapping version took the `cookies-blocked` case from 21 to 38 and put +24 on five
+ordinary browsing sessions.
+
+So this asks the narrower question only a marker can answer — the client is demonstrably
+keeping cookies, and ours is not among them — and the two share an evidence `family`, so
+even where both apply the stronger stands rather than the two summing.
+
+### Reaction beats observation
+
+`challenge-reaction` is the strongest idea here, and the reason is structural. Every
+other detector reads traffic that would have happened anyway and argues backwards from
+it. This one reads a response to a stimulus **we chose**: we decided when the challenge
+went out, so a client that changes what it claims to be within seconds of receiving one
+is reacting to it. There was no reason to look at that moment except that we created it.
+
+It reports two things — a changed identity, and never answering at all across repeated
+asks. The first is `strong` when a marker ties the two requests together and `moderate`
+when only the address does, because that is genuinely how much less an address-based join
+is worth. The second is capped at `moderate` forever: a person with JavaScript disabled
+produces it every time, and they are a person.
+
+## Comparing a client with everybody else
+
+The marker answers "is this the same client". A different set of questions needs the
+opposite comparison — not this client against itself, but this client against the rest of
+your traffic. It is also off by default:
+
+```ts
+new BotHandler({
+  site: { warmupRequests: 5000 },
+});
+```
+
+| Detector | Ceiling | Reads |
+| --- | --- | --- |
+| `distributed-walk` | `moderate` | A numeric range walked across many clients, none of which walks enough of it alone |
+| `path-novelty` | `moderate` | A client whose requests are almost all for paths nobody else has asked for |
+| `miss-baseline` | `moderate` | This client's miss rate against the site's own |
+| `path-campaign` | `moderate` | A path the site never served that many unrelated clients suddenly want |
+
+### Warmup is the whole safety story
+
+Nothing is reported until `warmupRequests` have been observed, and that number is the most
+important setting here. A baseline is a claim about what is normal, and a claim drawn from
+four hundred requests is not one: on a quiet site at three in the morning *every* path is
+one nobody else has asked for, because nothing has been asked for. A profile consulted
+early does not merely fail — it fails confidently, about everybody. The failure mode of the
+whole module is silence, which is the correct direction for something whose mistakes land
+on all your visitors at once.
+
+The same reasoning caps every detector here at `moderate`. A baseline is wrong exactly when
+a site is most unusual: the day of a redesign, the hour a campaign lands, the migration
+that leaves half the URLs missing.
+
+### What each one is really for
+
+`distributed-walk` addresses the one threat per-actor thresholds miss **by construction**.
+Split an id range across five hundred addresses at one request a minute each and every
+actor is unremarkable, `id-enumeration` never fires for anybody, and the range is still
+walked end to end. It is only visible in the union. What separates it from a busy shop is
+that enumeration *covers* a contiguous range and visits each id about once, while real
+readers cluster on popular items and return to them — so coverage and the revisit ratio
+must both agree, and either alone would report an ordinary catalogue.
+
+`path-novelty` is a self-maintaining wordlist. A wordlist is a list of paths that exist on
+*some* sites; on yours most of them do not exist and nobody has ever asked for them. It
+catches the scanner whose list is newer than the one this library ships.
+
+`path-campaign` is its inverse, and catches what it misses. A freshly disclosed
+vulnerability looks like one URL nobody had ever requested being requested by hundreds of
+unrelated clients within the hour — each of them making a single request, which is nothing
+at all on its own. The miss rate is **required** rather than optional here, because many
+clients arriving at once on a brand-new URL is also exactly what a successful launch looks
+like. What separates them is whether the site had anything to serve.
+
+**The known cost of `path-campaign`** is a broken link. Somebody shares a URL with a typo
+and thousands of real people follow it within the hour, which from the server is a path
+the site has never served, requested by many unrelated clients, answered `not found` every
+time — the firing shape exactly. Those people are reported at `moderate` and never
+refused; the corpus carries the case (`broken-link-shared-widely`) and holds it to the
+never-deny guarantee under every shipped preset.
+
+**`distributed-walk` needs both of its bounds.** The revisit ratio is checked from above
+*and* below, and the lower bound is what makes it usable on a real site. Ids spread across
+a six-figure catalogue coarsen the bitmap until one bucket stands for hundreds of ids;
+ordinary browsing then touches nearly every bucket, so coverage reads 1.0 and the
+estimated id count runs far ahead of the requests that were actually made. Requiring the
+visits to account for the ids claimed is what rejects an estimate that has left the
+evidence behind — measured on a simulated shop, sixty long-tail shoppers were reported
+before that bound existed and none after.
+
+`miss-baseline` is `probe-volume` done relative. A fixed 80% threshold reports everybody on
+a site mid-migration and stays silent on a tidy one where a client missing a third of the
+time is remarkable.
+
+### What it costs
+
+Everything is bounded, and the bounds are the interesting part, because a client picks its
+own paths and therefore picks how much there is to remember. Walk ids are held as a
+**1024-bit map over the range rather than as a set of numbers**: a set measured at 45 MB
+for a table anybody could fill on purpose by requesting `/anything/1`, while the bitmap is
+128 bytes however wide the range grows, coarsening rather than growing. With every table at
+its cap the profile holds about 17 MB, nearly all of it the path table, and costs roughly
+3% of an assessment.
+
+The state is kept in process like the rest of the behavioural series, so across replicas
+each sees its own share of the traffic. That understates every count here, and understating
+costs a missed detection rather than an accusation.
+
+### What the assessment carries
+
+An `Assessment` exposes `marker`: the reading, the drift, and the identity shape. It is
+there because the action path needs it to decide whether a response should carry a new
+marker, and because it is genuinely useful to an operator looking at one request.
+
+What leaves the machine is less than that. Notification sinks receive a **redacted** copy:
+`redactEvent` runs on the way out and is on by default, and it drops `facts.cookies`,
+strips the credential headers — `cookie`, `authorization`, `x-api-key` among them — masks
+the address and the actor key to a `/24`, and masks query values. A marker is reduced the
+same way: what a sink sees is whether one was presented, whether it verified, whether the
+identity moved, and how many networks it has come from. The claims inside it, the marker id
+included, do not go. They are the decoded contents of a cookie, and the rule about cookies
+already covered them.
+
+The unredacted assessment is what your own process holds — `handle()` returns it, and the
+dashboard renders it for an operator who is already inside your perimeter. Turning
+redaction off (`notifications: { redaction: false }`) is the one way to send more than the
+above, and it is worth knowing what you are choosing when you do.
+
+## What this deliberately does not do
+
+**It does not link two clients by how alike they look.** Joining strangers on a shared
+fingerprint and letting one's verdict raise the other's is guilt by association, and when
+the link is wrong it denies a person for a stranger's behaviour. Every join here is the
+same actor, or the same marker — something this server issued — and never a statistical
+resemblance between two clients.
+
+The site detectors are the one place evidence about *other* traffic reaches a verdict, and
+they are shaped by that. Each one describes a pattern the client in front of you genuinely
+took part in — it requested that path, it walked that range — rather than importing
+somebody else's verdict, and each is capped where it cannot deny anybody alone.
+
+**It does not build a profile.** The marker holds no identifier of a person, is not
+readable across sites, and expires. Nothing here is retained to describe a visitor; it is
+retained to describe a *series of requests*, and it ages out with the series.
+
+**It does not reach `certain`.** Nothing on this page can. `certain` means no benign
+explanation exists, and every signal here joins two requests — with the join itself being
+the thing that could be wrong. A tampered marker comes closest and still stops at
+`strong`, because a middlebox can mangle a cookie in transit and that is not the client's
+fault.
+
+## Related
+
+- [Shadow mode](shadow-mode.md) — run any of these against your own traffic for a week
+  before it is allowed to decide anything. Several of them fire at `moderate` on real
+  people by design, and whether the thresholds are right *here* is not a thing this
+  library can know.
+- [Detectors](detectors.md) — the full catalogue and what each one is worth.
+- [The client IP](../integration/client-ip.md) — why the actor key is what it is.
+- [Writing a detector](writing-a-detector.md) — including what a detector may see.