Table.create() existence check not enforced at commit — concurrent creates silently become last-write-wins (and the with-id form is undocumented)

[heskew]

Summary

Table.create() implements insert-if-absent semantics — an explicit-primary-key create throws ClientError('Record already exists', 409) — but the existence check is enforced only against the pre-staging snapshot, not at commit time. Under concurrency, two create()s of the same key can both report success, with the loser silently degrading to a last-write-wins put. Separately, this form of create() is undocumented (the docs describe only the auto-generated-id form), so users can't discover the primitive at all.

Trace (implementation gap)

1. resources/Table.ts (create, ~line 1783): explicit-id create does primaryStore.getSync(id) → throws 409 if a record exists → stages the write via _writeUpdate(id, record, true). The 409 check happens only here, pre-staging.
2. The staged write's commit closure (_writeUpdate, ~line 1896) uses optimistic locking: on storage-level write-write conflict (ERR_BUSY from the RocksDB optimistic transaction, or the LMDB ifVersion equivalent), resources/DatabaseTransaction.ts (~line 364) increments retries and re-runs save() → operation.commit(txnTime, freshEntry, retry=true, txn) with the entry re-read fresh.
3. On retry, the commit closure re-stamps timestamps and proceeds as a normal put — nothing re-applies the create-specific "reject if exists" semantic, even though existingEntry.value is now populated by the winning create.

Net: concurrent create(sameKey) → both pass getSync (both absent at read time) → both stage → loser conflicts, retries, overwrites → both callers resolve successfully. The 409 only fires when the winner's write is already committed before the loser's getSync — i.e. sequential presentations.

The fix appears well-scoped: the conflict-detection, fresh-entry re-read, and retry flag machinery all exist — a create-typed write's retry path could throw the same 409 when existingEntry?.value is present instead of proceeding.

Documentation gap

reference/resources/resource-api.md documents create(record) as only "Creates a new record with an auto-generated primary key … Do not include a primary key in the record argument." The explicit-id, 409-on-exists form is implemented but undocumented — which reads as "Harper has no insert-if-absent primitive." If the with-id form is intended API, it should be documented (including its concurrency semantics once decided); if not, create() should reject explicit ids rather than half-support them.

Motivating use case

The oauth plugin's RFC 7523 client-assertion replay guard (jti single-use enforcement; HarperFast/oauth#165, discussion with @kriszyp) needs per-node atomic insert-if-absent. create() + catch-409 is the natural shape and the plugin is adopting it — today it narrows the race window (staging→commit instead of an awaited get→put), and it becomes fully correct per-node automatically if the retry path enforces the 409. Cross-node behavior under async replication is understood and out of scope here.

Asks

1. Decide whether explicit-id create() is blessed API (@kriszyp).
2. If yes: enforce the 409 at commit time (retry path) so create() is a true per-node insert-if-absent, and document the with-id form + its concurrency semantics.
3. If no: make create() reject explicit primary keys, and document what (if anything) is the supported insert-if-absent primitive.

🤖 Filed by Claude (Fable 5) on Nathan's behalf, from the oauth#165 review discussion.

[heskew]

Sharper framing after a design pass — the original text reads as presuming the fix; the honest split is:

Cross-node: by design. Replication is coordination-free LWW convergence; a cluster-wide unique-insert guarantee is structurally out of scope. Whatever contract is chosen, docs should state create() is convergent, not constraint-enforcing, across nodes.

Same-node: implementable in a Harper way, if wanted. The conflict is already detected (optimistic-txn ERR_BUSY / ifVersion), the retry path already runs the commit closure in JS with the fresh entry, and the caller's promise resolves post-commit — so failing the losing local create with the same 409 adds no coordination, no JS-during-write-txn, no cost off the conflict path. Critical seam: replication-applied creates must never throw — sourceApply transactions already retry uncapped and must never drop a write; local-origin enforcement has to stay on its side of that existing distinction.

So the real decision (ask 1) is the contract: per-node-atomic + cross-node-convergent (retry path enforces 409 for local creates), or advisory-everywhere (docs-only fix stating the existence check is best-effort under concurrency). The oauth jti replay guard works under either — it catches the 409 and treats absence-of-409 as the documented residual race — but the first contract makes it airtight per node.