Record-scoped write authorization: per-record allowDelete on query deletes, per-element allow* on array puts

[kriszyp]

Write-side corollary to #1786 (Record-scoped allowRead): allowUpdate/allowCreate/allowDelete were enforced once per request on multi-record writes, so a record-scoped override was silently under-enforced on conditional deletes and array puts.

The model

When loadAsInstance !== false, this mirrors #1786's marker/deferral design with write-path semantics:

• Query-shaped delete with an application-overridden allowDelete (marker isDefaultAllowDelete) defers its entry check and is enforced once per matching record — FILTER semantics: denied (or throwing/rejecting — fail closed) rows are skipped, permitted rows deleted; limit/offset count allowed rows, mirroring the read guard filtering before the query limit.
• Array puts (REST collection PUT and direct instance put) with an overridden allowUpdate/allowCreate are authorized per element — create-vs-update chosen by that element's existence — with FAIL semantics: one denial throws AccessViolation, aborting the whole transaction (no partial batch).
• this binding: mutating allow* hooks stay on the resource (no RecordObject delegate); per-record evaluation binds this to a per-row resource instance with the record loaded, so this.ownerId and super.allow* composition both work (the SWR-instance idiom from allowStaleWhileRevalidate is never consulted for query-driven revalidation #1578).
• Async overrides participate: the write paths are async, so unlike the sync search traversal in Record-scoped allowRead: unified row-level read access control (#1422 gap 2) #1786, async allow* overrides are awaited per record (fail-closed).
• Default allowCreate consistently means INSERT: record creation and record-targeted publish both check INSERT RBAC; publish creates an audit/message entry and does not update the record. Framework-default array puts still keep their single collection-entry check.
• The deferred put check runs in the static put action against the resolved body, so a promise body can't bypass it and enforcement is framework-owned for every resource class. A subclass overriding delete() loses the enforcesCheckPermission marker → keeps today's entry check (warned once per class).

loadAsInstance === false

False mode retains the HarperDB 4.7 / Harper 5.1 request-scope behavior rather than adopting the per-record model above:

• array PUT calls allowUpdate once with the original whole batch, then starts writes only after a truthy grant
• query-shaped DELETE prepares the selecting projection ($id), calls allowRead once on the collection receiver, clears the framework permission marker, and scans without allowDelete or per-row rechecks
• record-targeted publish calls allowCreate once because it creates an audit/message entry
• false results, synchronous throws, and rejected promises fail closed before any write/event is staged

The loadAsInstance !== false behavior in this PR is unchanged by the compatibility follow-up.

Deliberate compatibility caveat: a false-mode array PUT uses one whole-batch allowUpdate, including all-insert and mixed insert/update batches. It does not apply instance mode's per-element create-vs-update distinction.

Deliberately out of scope: operations-API/SQL writes stay on operation-level RBAC (they never arm checkPermission; raw tables have no override surface).

Where to look

• resources/Resource.ts — the instance-mode write-deferral gate in the authorize wrapper and the per-element checks in the static put action.
• resources/Table.ts — record-scoped query delete/array put behavior plus the false-mode request gates.
• resources/DatabaseTransaction.ts / LMDBTransaction.ts — aborted transactions are terminally poisoned: addWrite()/save()/commit() reject, while successfully completed transactions retain their existing post-commit behavior; abort cascades across the multi-database chain.

Validation

• TypeScript build
• oxlint on changed production/tests
• Prettier and git diff --check
• focused authorization suite: 30 passing
• full core unit suite: 3,799 passing, 188 pending
• full resource unit suite: 1,285 passing, 14 pending; one unrelated caching-count failure after concurrent suite runs passed immediately in isolation
• prior integration suite: 1,552 passing, 0 assertion failures, 17 skipped; nonzero only because the optional real-Ollama fixture hit the existing Node ERR_IMPORT_ATTRIBUTE_MISSING startup issue and cancelled its six children

Review

Thorough review plus a final post-fix artifact pass found no remaining blockers or significant concerns. Review verified that the compatibility follow-up changes only the false-mode branch and caught the legacy ordering requirement that $id be visible to allowRead; that ordering is now covered by regression.

Remaining accepted limitations:

• Commit-retry TOCTOU (ownership changes between authorization and a conflict-retried commit) is a pre-existing gap across all single-record auth — follow-up issue to file, not widened here.
• Approximate-index (HNSW) conditional deletes filter after the bounded candidate set, and denied-heavy deletes with limit scan the full matching set — same class of limitation as the Record-scoped allowRead: unified row-level read access control (#1422 gap 2) #1786 read filter.

Docs: companion PR HarperFast/documentation#593 (extends the #1786 allowRead docs page with the write-side model).

Generated with GPT-5.6 Codex.

[gemini-code-assist]

Code Review

This pull request introduces record-scoped write authorization as a write-side corollary to record-scoped read authorization. It defers permission checks for collection-shaped writes (array PUTs and query-shaped DELETEs) to evaluate them per-record or per-element when application-overridden allowDelete, allowUpdate, or allowCreate hooks are present. Query-shaped deletes now utilize filter semantics (skipping denied rows), while array PUTs enforce fail-fast semantics (aborting the transaction on any denial). The feedback recommends improving the thenable check in Resource.ts by verifying that then is a function rather than just checking its truthiness.

[claude]

Reviewed; no blockers found. New push since the last review resolves the merge conflict and adds the false-mode (loadAsInstance === false) compatibility fixes (query-delete auth via allowRead, array-put auth via a single allowUpdate, publish auth via allowCreate instead of allowDelete) — all match documented legacy behavior and are covered by new tests.

[heskew]

Both notes are specific to tables that override an allow* hook — the default path is correct and covered by t8–t14. An override re-routes authorization through the per-element resource, and that's where the two issues live. Left inline.

_{🤖 Draft prepared with Claude (cross-model review pipeline); reviewed and posted by @heskew.}

[Ethan-Arrowood]

Please resolve the merge conflict and then re-request reviews. Thanks!

_{sent with Claude Opus 4.8}