fix: matching consumed the click, breaking reinstalls and repeat matches

[Newtdev]

Closes #17.

/match locked the winning click to the device while the candidate query only considered unmatched clicks — WHERE matched = 0 in PHP, eq(referralClicks.matched, false) in Node. A matched click therefore became invisible to everyone, including the device that had just matched it. lockToDevice()'s own docblock stated the original intent: "so it can never be matched twice." That intent was the bug.

The principle behind the fix

The SDK's job is to report what was actually clicked. Preventing a referral code from being redeemed twice belongs in whatever records signups and rewards — that layer knows what redemption means in a given product; the matcher does not. Making the click disappear was the SDK enforcing a policy that was never its own.

So matched now means "last matched by", not "used up".

Resolution

Removing the filter alone would have been wrong in one direction: a device whose fingerprint later stops clearing the threshold (its IP moved, say) would lose an attribution it had already been given.

existing binding	new candidate above threshold	result
no	yes	best candidate — unchanged
yes	no	keep the existing binding
yes	yes	whichever click is newer

Two constraints that are easy to get wrong:

• Compare by click time, not confidence. A stale click that happens to score higher is still the wrong answer. Attribution is last-click-wins.
• A newer click below the threshold must not take over, or an unrelated recent click could steal an attribution merely by being recent.

bindMatch() rather than a looser lockToDevice()

lockToDevice()'s matched = 0 predicate is a security guard on the /claim path (#21) — the deterministic tier's first real use of a click, where losing the race must reject rather than proceed. Matching has the opposite requirement, so it got its own method. Loosening the shared one would have quietly removed a claim-time guard while appearing to fix an unrelated matching bug.

Also fixed

A parity divergence found alongside: PHP filtered candidates on expires_at > UTC_TIMESTAMP(), Node had no expiry check at all. Harmless while expiry and the match window are the same duration, real the moment either is configured independently.

Ordering for a device's bindings keys on the click's created_at, not matched_at — the latter is written by UTC_TIMESTAMP() into a plain TIMESTAMP, both one-second resolution, so same-second locks tie and resolve in arbitrary storage order.

Verification

The scoring suite structurally could not catch this: the bug was never in scoring, it was in which rows the candidate query could see, and a pure-scoring suite has no database.

tests/run.php now carries a database-backed section — in-memory SQLite with UTC_TIMESTAMP() shimmed via sqliteCreateFunction(), so it still provisions and installs nothing:

• five reinstall cycles under five different device ids
• three repeat matches against two competing referrers
• takeover by a newer qualifying click
• refusal of takeover by a newer non-qualifying one
• an unrelated device still matching nothing

25 assertions pass under UTC, Africa/Lagos, America/New_York and Pacific/Chatham. Node: 37/37, typecheck and build clean on all three packages.

Counter-checked by reintroducing only the matched = 0 clause — 7 assertions fail and reproduce both reported symptoms exactly, including the ALICE01 → BOB0002 flip.

One caveat recorded in both the test comments and decisions #30: "a newer qualifying click takes over" passes even against the buggy code, since the old click is filtered out and the new one wins by default. It passes for the wrong reason there and is not load-bearing on its own.

Full writeup in docs/decisions.md #30.