logseq/docs/adr/0009-hybrid-schema-deletion.md

ADR 0009: Hybrid Delete Semantics for Schema Entities

Date: 2026-03-18 Status: Accepted

Context

delete-blocks and page deletion now recycle entities instead of hard deleting them.

That works well for ordinary content because users can restore deleted blocks and pages from Recycle, and active UI/search can treat recycled content as hidden state.

It does not work as well for DB-schema entities. Tag pages, property pages, and closed-value blocks continue to exist after deletion and can leak into active semantics such as:

• class/property enumeration
• closed-value lookup and scoped choices
• bidirectional/property-derived views
• sync repair logic when schema roots disappear but dependents still reference them

At the same time, sync still needs to remain robust when :db/retractEntity appears again for this subset of entities and for their descendants.

Decision

1. Adopt hybrid delete semantics:
   • recycle ordinary blocks and ordinary content pages
   • hard retract tag/class pages, property pages, and closed-value blocks
2. When deleting a schema root page, retract the schema page tree rather than moving it to Recycle.
3. When deleting a closed-value block, retract the choice entity directly.
4. Keep raw entity access unchanged; deleted schema entities should disappear by DB state, not by UI-only filtering.
5. Keep recycle-aware behavior for content entities:
   • deleted-state page route for recycled content
   • deleted styling for recycled references/embeds
   • search/index filtering for recycled content and descendants
6. Make sync robust for missing content locations:
   • if a content node loses :block/parent or :block/page during sync application, move it to Recycle rather than leaving it structurally invalid
7. Preserve valid :db/retractEntity handling in sync sanitize/rebase/apply for schema deletions.

Consequences

• Positive:
  • Schema entities return to true disappearance semantics, which matches how most schema helpers already reason about deletion.
  • Content keeps recycle/restore UX.
  • Sync has a deterministic repair rule for orphaned content blocks.
• Negative:
  • Delete semantics are now mixed by entity kind, so the rule must remain centralized in the outliner/domain layer.
  • Some old recycled schema entities may still need active-use filtering until users delete them under the new semantics.
  • Sync logic is slightly more complex because it must accept both recycle and hard-retract flows.

Verification

• Model/helper coverage:
  • bb dev:test -v frontend.db.db-based-model-test/get-all-classes-filters-recycled-test
  • bb dev:test -v frontend.db.db-based-model-test/get-all-properties-filters-recycled-test
• Sync repair coverage:
  • bb dev:test -v frontend.worker.db-sync-test/missing-parent-after-remote-retract-moves-child-to-recycle-test
• Additional targeted coverage to keep or extend:
  • page/property/closed-value delete semantics
  • bidirectional helper behavior with deleted or recycled entities
  • search index invalidation for recycled content