docs(f3): a row lock the shipped database does not take

[lessevv]

F3-R11 required a recovery code to be "matched and consumed atomically under a row lock".

SQLite has no row lock. Laravel's SQLiteGrammar::compileLock() returns '', so the call that appeared to satisfy the requirement emits no SQL:

SQL emitted: select * from "users" where "id" = ?
contains FOR UPDATE: NO

The requirement named a mechanism the shipped database does not implement, and the implementation's lockForUpdate() was decorative.

Why that was worth changing rather than leaving

F3-R13 requires a constant mismatch cost, which the implementation delivers as a fixed ten bcrypt comparisons per attempt — 3.5 seconds, measured at rounds 12 on this hardware.

The connection runs transaction_mode = IMMEDIATE, which takes the database-wide write lock at BEGIN, and both shells serve one request at a time. A transaction held across that hashing therefore freezes the entire application for three and a half seconds — from an endpoint that needs no credential to reach.

So the decorative lock was hiding a real constraint: the expensive comparison must not happen inside the consuming transaction.

What it says now

A recovery code MUST be matched and consumed atomically: a redemption MUST spend exactly one code, and a code already spent MUST NOT be spendable again however many attempts are in flight. The hashing that decides the match MUST NOT be held inside the consuming transaction.

The property, not a mechanism. Atomicity is carried by a compare-and-set — a single UPDATE … WHERE id = ? AND used_at IS NULL whose affected-row count is the answer — which needs no row lock and cannot be interleaved.

A new section, A row lock the shipped database does not take, records the measurement and the reasoning so the next reader does not reinstate the call.

Ordering

Filed before the implementing change, per GOV-R27. The beatrax PR that moves the hashing out of the transaction will cite F3-R11 and will not merge before this does.

Gates run locally: integrity.py clean, manifest_check.py clean (1 manifest, 373 goals), markdownlint-cli2 0 issues.

Spec: F3-R11, F3-R13, GOV-R27

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud