feat(sdk): a typed decision, and characteristics for who the caller is

[cport1]

Closes #730 and #731. First of the milestone-26 batch, and the foundational one — #734 (testing utilities) and the any burndown both build on it.

#730 — the decision

protect() returned { allowed, detection }, and all three adapters typed the value they hand to onBlocked as any. Integrating meant destructuring a blob and string-matching to find out which rule fired. Three things the SDK already knew had nowhere to go:

Which rules ran. The engine collapsed to one deciding rule plus a violations array. A filter() rule that never ran for want of IP enrichment and one that ran and passed both reported ALLOW — indistinguishable, and the first reads as "checked, and this IP is fine". Every rule now appears in results[]:

state	Meaning
RUN	Evaluated, conclusion counts
DRY_RUN	Evaluated, conclusion recorded but not enforced
NOT_RUN	Could not evaluate — a needed signal was absent
CACHED	Not evaluated; a prior decision was reused

A dry-run rule that matched reports conclusion: 'DENY' with state: 'DRY_RUN'. Reading its action verbatim would show it as ALLOW, which is the opposite of what the operator turned it on to see.

"Challenge this one." We ship a proof-of-work captcha in @webdecoy/client and the decision type could not express a challenge, so it was reachable only by wiring it up by hand. CHALLENGE is now a conclusion, produced when the server says challenge and the score cleared the threshold.

A stable id. 'rule_' + Date.now() is not unique under concurrency and correlates with nothing. Now a random dec_…, also stamped on detection.detection_id so the two join. Random rather than sequential because ids leave the process, and a counter leaks request volume to anyone who sees two.

Plus deniedBy('tripwire'), and ERROR as a distinct conclusion from DENY — both serve the request, but only one of them means "we never decided".

Compatibility. allowed is unchanged, including failing open on ERROR. onBlocked gets the decision as a trailing argument, so existing handlers are untouched; detection is now typed SDKDetectionResponse instead of any.

One trap worth noting: protect() used to do { ...result, edge }, which would silently strip the methods off a class. It now calls decision.withEdge(edge), and there's a test that would have caught the spread.

#731 — characteristics

rateLimit({ keyBy }) was the only way to change what a rule keyed on, and it was per-rule. Everything else was IP-only — the wrong subject for an authenticated API, and the wrong subject for us specifically, since the actor model exists precisely because IP is not identity.

const wd = new WebDecoy({
  characteristics: [(ctx) => ctx.headers['x-api-key']],
  rules: [rateLimit({ max: 100, window: 60 })],
});

A rule's own keyBy still wins. An absent characteristic falls back to the IP, not to an empty component — otherwise every unauthenticated request shares one bucket, so a limit meant for one tenant takes out anonymous traffic site-wide, and it's invisible until it happens. A characteristic that throws is treated the same way.

Decision caching

Deliberately narrow — server-derived DENY and CHALLENGE only:

• ALLOW is never cached. That's how a client that has since started misbehaving keeps sailing through, and it saves the cheap request — a low-risk one already returns without calling out.
• Rule outcomes are never cached. A rate limiter has to see every request to advance its window, and a cached tripwire hit would stop the violation being reported.

Bounded at 10k entries, oldest-first eviction, refreshed on overwrite so a repeatedly-denied key isn't evicted ahead of one nothing has touched.

Verification

21 new tests, 327 total, all passing. no-explicit-any budgets drop: express 14→12, nextjs 5→3, fastify 2→0. Build, lint and check:edge green.