Organisation Erasure: Post-Window Disposal

What changed

SpeyBooks can now erase an organisation and all of its records, deliberately and irreversibly, and only after that organisation’s seven-year custodial window has closed. The erasure leaves a disposal record that outlives the data it removes, so the fact and timing of a disposal stay provable after the organisation is gone. The hard-delete route disabled in an earlier release stays disabled, and now points the caller at this sanctioned routine.

Why it matters

Erasing a company’s accounting records is the most destructive thing this system does, and the one it has to get right. Too early, and you destroy records the company is legally required to keep. Carelessly, and you leave orphaned data behind, or no proof the disposal ever happened. This release makes erasure a gated, recoverable, and provable act rather than a delete.

Your records are held for a full seven years, measured from your last closed accounting period. That is SpeyBooks’ custodial commitment, a year above the six years HMRC requires of you, held on your behalf. SpeyBooks will not dispose of them a day before that window closes, and that holds even against an administrator. There is no path that erases an organisation while its window is open, and an organisation that has never closed a period cannot be erased at all, because an irreversible act does not proceed on a window it cannot prove has passed.

With the deactivation shipped in 5.81.0, this closes the organisation lifecycle from both ends. Deactivate to lock an organisation out while keeping every record; erase only once the custodial window has run its course. The two are the same commitment seen from each side: SpeyBooks holds your records on your behalf for exactly as long as it must, and no longer.

How it is enforced

The window is decided in one place, on the database clock. The seven-year window is computed from your latest closed accounting period, with the arithmetic and the closed comparison run inside the database against its own clock, so the verdict cannot drift on an application server’s time. An organisation with no closed period produces an indeterminate window, never a silently closed one, and is refused. The same component will decide closure for the scheduled purge that follows later, so both answer the question identically.

The act runs in two committed phases, not one. The first phase records the disposal and the organisation’s terminal audit chain head, and commits, before anything is removed. The second authorises and carries out the delete, and every dependent record, across forty-nine linked tables, is removed in a single cascade. Splitting the act in two is what makes it recoverable: if it is interrupted after the record is written but before the delete completes, a re-run finds the durable record and resumes at the delete. There is no half-erased state, and no disposal recorded twice.

The delete is guarded at the data layer, not in the calling code. A database-level control refuses any organisation delete that is not explicitly authorised for that exact organisation, and only for the life of a single transaction. The one delete that succeeds is the one the routine sanctions, for the one organisation it sanctions; a stray or mistaken delete from any other path is refused by the database itself. Enforcing the rule below the application is deliberate, so that code written later cannot forget it. (Enforced at the data layer, migration 119.)

The disposal record survives the disposal. Every erasure leaves a record carrying the organisation’s terminal audit chain head and the lawful basis and timing of the disposal. The record holds no link back to the organisation, so it survives the cascade that removes everything else. Anyone holding a prior export of their data can confirm it hashes forward to that head, so a disposal stays verifiable after the organisation no longer exists.

How it is proven

Every guarantee above ships with an executable check that runs on each deploy, against the live database rather than a mock. Nine anchors cover the within-window and no-period refusals and that they write nothing, the post-window disposal and its single surviving record, recovery from an interrupted run, the already-erased response, and the guard refusing an unauthorised delete and passing an authorised one. The suite commits for real rather than rolling back, because the recovery property only exists if the first phase is durable across a failure of the second.

The release went out with all sixteen pipeline phases green and zero violations: 294 executable checks in total, the surface-money and schema-coverage and provenance gates all clean, the documentation regenerated to 212 endpoints, and the service reloaded healthy. No database migration and no manual step were required; the schema this routine stands on landed in an earlier release.

A within-window request is refused before anything is touched, and tells the operator when disposal becomes available:

curl -X POST https://api.speybooks.com/v1/admin/orgs/org_8f2a.../erase \
  -H "Authorization: Bearer $TOKEN"

{
  "success": false,
  "error": {
    "code": "RETENTION_WINDOW_OPEN",
    "message": "Erasure refused. The organisation's records are within the seven-year retention window, which closes on 2031-03-31. SpeyBooks holds these records on the customer's behalf until then. To lock the organisation out now, deactivate it instead."
  }
}

Operational impact

The API surface goes from 211 to 212 endpoints. The erase action is staff-only, under Admin, and writes an administrative audit entry on every outcome, refusal as well as success. A successful erasure disposes of every dependent record in one cascade and leaves its disposal record behind. There are no breaking changes.

Deferred

The external timestamp proof on the disposal record, an OpenTimestamps receipt, is deferred to its own release; until then the audit chain head stands as the verifiable anchor, and existing records will be backfilled when it ships. A scheduled equivalent that disposes automatically at window close is planned, gated on a VAT Capital Goods Scheme determination, and stays disarmed until that is settled.