Make a ref guard deletion, on every path into the record

[korivi-CraftOS]

The hole

An app that refuses to delete a client who still has invoices has guarded one way in: its own UI, through its own operation. The generic record route is the other:

a2app <app> data clients delete c_acme     → 200 OK

The row is gone and every invoice still points at it. The delete reported success.

The author cannot close this themselves — record deletion is adapter code, which toolkit-sync owns and overwrites — so the only move available was to write the hole down as a known limitation.

The fix

The check moves to where both doors pass through. Nothing new is asked of the app: a ref or list<ref> already names the entity it points at, and that is the entire declaration needed.

a2app <app> data clients delete c_acme
→ 409 record_referenced
  Cannot delete clients "c_acme": a record still references it (invoices.client).
  referencedBy: [{ entity: "invoices", field: "client", ids: ["inv_1"] }]
  resolution:   Remove or repoint the referencing records first, or run an
                operation the app provides for this.

A refusal with no location is a wall, not an answer — so it names the entity, the field, the blocking records, and what would make the delete legal.

This changes behaviour, deliberately

A delete that used to succeed and orphan now returns 409. That is the fix, not a side effect of it. Orphaning silently is invisible at the moment it happens and surfaces later, somewhere else, as a record pointing at nothing.

An app that genuinely means for references to outlive the record says so in one word:

{ name: "client", type: "ref", entity: "clients", onDelete: "ignore" }

There is deliberately no cascade or detach. Both would let one delete write to records the caller never named — which an agent cannot approve up front and an audit log cannot explain afterwards. An app that wants that declares an operation, where it is named, described and approved like any other write.

Verified against a real app, not just unit tests

Scaffolded a fresh app from blueprint-react-node — the blueprint whose server.mjs the issue names — with exactly the model described: clients, and invoices with a ref to them, plus a delete-client operation carrying the app's own rule.

$ a2app ./billing data clients delete c_acme
✗ Cannot delete clients "c_acme": a record still references it (invoices.client).
exit=1

Before this change that command returned 200 and the invoice was left pointing at nothing.

And nothing was half-done:

client:  {"id":"c_acme","name":"Acme Corp"}
invoice: {"id":"inv_1","total":4200,"client":"c_acme"}

The rest of the flow is unaffected: the app's own delete-client operation still behaves as it did (approval gate intact), and once the invoice is removed the client deletes normally.

Scope — all three adapters

Adapter	Status
adapter-core (TypeScript)	✅ fixed, verified against a running app
FastAPI blueprint (Python)	✅ fixed, covered by the adapter self-test
PocketBase blueprint	✅ fixed — but not runtime-verified, see below

PocketBase

It serves records natively and guards writes by hooking the request. Create and update were hooked; delete never was. onRecordDeleteRequest now refuses the same case and returns the same record_referenced shape, so an agent meets one answer whatever stack it is talking to.

It fails open on its own errors, deliberately. This hook cannot be executed here — the blueprint's install step prints "download the pocketbase binary", so there is no runtime in CI and the gate only parses the file. Untestable code that failed closed could brick every delete in an app; failing open means the worst case is the behaviour that already existed. It still needs a run against a real PocketBase before anyone calls it verified.

The part that can be tested was moved out of the hook: referencingFields lives in the shared rules file and is covered by the gate's self-test. Only the query is PocketBase's.

A second bug, found on the way

The PocketBase adapter duplicates mapFields/normalize inline — the header explains why (pooled Goja handlers cannot close over file scope) — and the copies had drifted. The describe handler's copy carries a relation's target entity; the identity handler's copy did not, and that is the copy schemaVersion is computed from.

So retargeting a ref at a different collection changed what describe published without moving the fingerprint, and a client caching against it kept a describe pointing the ref at the old collection. The fingerprint's own contract names that case explicitly. Both copies now carry the target.

Original scope note (superseded)

expand

two of three adapters

Adapter	Owns its delete path?	Status
adapter-core (TypeScript)	yes	✅ fixed
FastAPI blueprint (Python)	yes — identical hole	✅ fixed
PocketBase blueprint	serves records natively	❌ still open

PocketBase is not fixed. Its hooks cover onRecordCreateRequest and onRecordUpdateRequest but not delete, so the same hole is open there and the fix belongs in an onRecordDeleteRequest hook. I did not write it: that file is system-owned and hash-locked, there is no PocketBase runtime in CI to execute it against, and a guard that errs toward refusing would break every delete in the app. It needs someone who can run it.

Each adapter scans by paging rather than pushing a filter down — filter grammar is per-backend, and a policy that silently did nothing against one of them would be worse than no policy. Only entities that actually declare a restricting ref are read, and the scan reports examples rather than every blocking row.

Verification

Conformance had no DELETE coverage at all — part of why this survived. It now has 7 checks, self-contained so they depend on neither seed data nor ordering: the refusal, what it names, that the record is still there afterwards, that removing the reference removes the block, and that a missing record is still 404 rather than 409.

The new adapter-core unit test fails 17 ways against the previous behaviour, including the one that matters:

a referenced client is not deleted    expected: 409   actual: 200
the client is still there             expected: 200   actual: 404   ← it was deleted

The Python self-test covers the same scan and runs inside the scaffolded app (✓ python syntax + adapter self-test).

	Before	After
Conformance	57/60	64/67
pnpm -r build / typecheck	clean	clean
Python SDK	pass	pass

Note on the 3 failing conformance checks

blueprint-base, blueprint-python-fastapi and blueprint-pocketbase-react fail scaffold → canon → validate on main as well — verified against a clean checkout. The reason is unrelated to this change: those templates ship reference/requirements.md with 43 unfilled <REPLACE: …> placeholders, which validate rejects. blueprint-react-node passes.

Follow-up worth considering

describe does not publish onDelete, so an agent planning five deletes still learns about the constraint by being refused. Publishing it (and folding it into schemaFingerprint) would let the agent plan correctly the first time. Left out here to keep this focused on closing the hole.

[korivi-CraftOS]

Stacked on #7 so this PR shows a truthful green.

The red here was never this change: it was the three blueprint failures that have been red on main for five commits, which #7 fixes. Rather than leave a passing change looking broken, #7's branch is merged in — so CI now runs this fix against a suite that is green to begin with.

Total: 67/67 passed, 0 failed.

That is 60 from #7's corrected suite plus the 7 delete checks this PR adds.

Merge #7 first, and the extra commits disappear from this diff on their own, leaving only the delete guard. Nothing here needs to change.