Blackholes#

A blackhole permanently removes or replaces historical values for one field of one entity. Ordinary patches change current state and preserve earlier facts. A blackhole changes those earlier facts in the database and its configured backup lineages.

One explicit target#

The target identifies a numeric entity ID, a field, and an action. purge removes the historical values. replace substitutes one supplied value for the affected assertions. Existing retractions remain retractions. Transactions retain their identities, and facts after the approved cutoff remain unchanged.

The current interface accepts one entity and field per operation. It does not accept a query-selected group, stored mutation, or replacement expression. The reference identifies protected fields and entities that the operation rejects. These restrictions preserve audit and recovery information.

Preview fixes the proposed scope#

A preview examines history without changing it. It gives a cutoff, effect counts, digests, and a preview identity tied to the LSP connection. Additional pages use that identity. The preview expires after five minutes.

Show the target and effects to the user before execution. Execution requires the same connection, the preview identity, an actor, a reason, and the explicit confirmation text. Stardust calculates the effects again before it changes history. Any intervening commit changes the cutoff and rejects execution with a conflict, including a commit to another entity. A conflict requires a new preview and approval.

Recovery belongs to the mount#

Execution holds other writes while it changes history. The operation updates affected indexes so queries agree with the rewritten facts. It also replaces configured backup lineages so restore does not reintroduce the removed values.

A complete result means the operation finished. A recovering result means the mount owns the remaining backup recovery. Inspect runtime backup status before further action. Cancellation or disconnection cannot undo changes that already committed.

The audit preserves the decision#

The audit entity records the operation without the removed values. The execution result gives its numeric ID as auditEntity. Use stardust/entityPath to find its complete path under data/entities. This record connects the approved action to the history change.

A removed backup definition, an independent database copy, or an external snapshot can remain outside Stardust's control. The operation cannot promise removal from those copies. Operators must manage them separately when the same removal is necessary.

The shared Blackholes reference gives the exact request fields, results, and recovery errors. Backups explains how the mount preserves and restores ordinary history.