F12.2 — Soft delete
| State | Closed |
| Parent | E12 |
| Iteration | Release 3 |
| Start Date | 2026-10-04 |
| Closed Date | 2026-10-04 |
| Predecessors | F12.15 |
| Source | Owner request, 2026-10-04 |
Stories: 7 Closed
| Story | State | Depends on |
|---|---|---|
S12.2.1 — Decision: soft delete is a delete_time column in AIP-164's shape |
Closed (2026-10-04) | — |
| S12.2.2 — Check for maintained libraries | Closed (2026-10-04) | — |
| S12.2.3 — Shared rules and the conformance area | Closed (2026-10-04) | — |
| S12.2.4 — ORM support | Closed (2026-10-04) | — |
| S12.2.5 — Django binding | Closed (2026-10-04) | — |
| S12.2.6 — FastAPI binding | Closed (2026-10-04) | — |
| S12.2.7 — Documentation and release notes | Closed (2026-10-04) | — |
Soft delete in Google AIP-164's shape, on both stacks and both ORM packages. A
DELETE on a resource that offers soft delete sets its deleteTime instead of
removing it. POST {resource}:undelete reverses it, and showDeleted=true
brings deleted resources back into a list. The API conventions list AIP-164 as
"not adopted (deferred)"; this feature adopts it.
Context
Outcome: the owner scheduled this feature for release 3 on 2026-10-04, ahead of its original trigger. Taken up before the model-vocabulary idea, it settled that idea's status-based soft-delete question.
Design
Outcome: soft delete shipped on both stacks and both ORM packages
(2026-10-04), with hard delete and purge out of scope. The
API conventions §21 own the
wire rules and case ids; the
Django models guide, the
rn-forge-sqlalchemy guide and
the FastAPI soft-delete guide
show the bindings, and the
soft-delete reference lists
the shared symbols.
Why a delete_time column, not a status
Outcome: ADR-0010 records the decision and its reasons.
New conformance cases
Outcome: the soft-delete area's cases are in CASES, documented in the
conformance reference.
S12.2.1 — Decision: soft delete is a delete_time column in AIP-164's shape
State: Closed (2026-10-04)
Acceptance:
docs/adr/ADR-0010.mdrecords the decision in Why adelete_timecolumn, with status-based soft delete under Alternatives considered. It is listed indocs/adr/index.md.- The model-vocabulary idea's Soft delete section is rewritten to point at ADR-0010, and its summary row no longer lists status-based soft delete. The sentence about the conflict with F12.2 is gone.
- The owner accepts the ADR.
S12.2.2 — Check for maintained libraries
State: Closed (2026-10-04)
Acceptance: django-safedelete and sqlalchemy-easy-softdelete are each
checked against ADR-0001: release recency, typing,
support for the current Django or SQLAlchemy major, and whether they can give
the wire rules above without global query hooks. The outcome is recorded under
Considered and rejected, or the library is adopted behind the package's extras
and the design is amended before S12.2.4 starts.
S12.2.3 — Shared rules and the conformance area
State: Closed (2026-10-04)
Acceptance:
rn_forge.webexportsResourceDeleted,ResourceNotDeleted,SHOW_DELETED_PARAMandrequire_live. Both exceptions are registered indefault_registry()throughDomainConflict, andtests/covers their rendered bodies.ConformanceAreagainssoft-delete. The cases in New conformance cases are added toCASESin S12.2.6: every driver runs every case, so they land once both stacks serve them.
S12.2.4 — ORM support
State: Closed (2026-10-04)
Acceptance:
rn_forge.django.modelsexportsSoftDeleteModelMixinandSoftDeleteQuerySet. Tests coversoft_deleteandundeletesettingdelete_timeandupdated_by, a version bump on a versioned model,.live()and.deleted(), and an unfiltered default manager.rn_forge.sqlalchemyexportsSoftDeleteMixin,live,soft_deleteandundelete. Tests cover the same behavior on SQLite, and on PostgreSQL under thepostgresmarker.
S12.2.5 — Django binding
State: Closed (2026-10-04)
Acceptance:
rn_forge.django.drf.viewsexportsSoftDeleteMixin, andBatchDeleteMixindeletes throughperform_destroy.- The Django conformance fixture serves
/conformance/notesfrom aSoftDeleteMixinviewset, and thesoft-deletecases pass on it once S12.2.6 adds them. The existingtransfer.batch-delete-*cases still pass. tests/drf/coverssoft_delete_requires_if_match(428), aPUTon a deleted resource (409), andshowDeletedvalues other thantrueand1excluding deleted rows.- The drf-spectacular schema names the undelete operation
notesUndelete, documentsshowDeletedon the list, and documentsDELETEas 200 with the resource.
S12.2.6 — FastAPI binding
State: Closed (2026-10-04)
Acceptance:
rn_forge.fastapiexportsSoftDeleteStore,soft_delete_routerandshow_deleted_param.CASESgains thesoft-deletecases. The ASGI example (asgi_app.py), the Django conformance fixture from S12.2.5, the FastAPI conformance fixture and the scaffold drivers serve/conformance/notes, and everysoft-deletecase passes on each. The FastAPI fixture serves it through these symbols over an in-memory store. Thern-forge-sqlalchemyconformance driver serves the same routes over SQLite withSoftDeleteMixin, and passes them too.tests/coversrequire_if_match=True(428), adependencies=guard, and the store never being asked to write after a failed precondition.- The OpenAPI document has
notesUndeleteand a 200DELETEresponse, and both list their problem responses.
S12.2.7 — Documentation and release notes
State: Closed (2026-10-04)
Acceptance:
- The API conventions gain a Soft delete section that states the wire rules
and names each case id. §10 notes that a soft-deleting resource's
DELETEis 200. §18 listsdeleteTimeamong the standard fields. §19 no longer lists AIP-164 as not adopted. - The model conventions guide, the Django models guide and the
rn-forge-sqlalchemyguide describe the mixins. The FastAPI guide shows a SQLAlchemySoftDeleteStorebuilt onliveandsoft_delete. CHANGELOG.mdentries exist forrn-forge-web,rn-forge-django,rn-forge-fastapiandrn-forge-sqlalchemy.- The root and package sites build under
--strict, and the scaffold suite passes.
Acceptance
set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
test -f docs/adr/ADR-0010.md && grep -q 'ADR-0010' docs/adr/index.md # S12.2.1
absent 'conflicts with this section' docs/specs/ideas/index.md # S12.2.1
for sym in ResourceDeleted ResourceNotDeleted SHOW_DELETED_PARAM require_live; do
grep -q "\"$sym\"" packages/rn-forge-web/src/rn_forge/web/__init__.py # S12.2.3
done
grep -q '"soft-delete"' packages/rn-forge-web/src/rn_forge/web/conformance/types.py # S12.2.3
(cd packages/rn-forge-web && uv run pytest -q) # S12.2.3
grep -q 'class SoftDeleteModelMixin' -r packages/rn-forge-django/src/rn_forge/django/models # S12.2.4
grep -q 'class SoftDeleteMixin' packages/rn-forge-sqlalchemy/src/rn_forge/sqlalchemy/models.py # S12.2.4
(cd packages/rn-forge-sqlalchemy && uv run pytest -q) # S12.2.4, S12.2.6
grep -q 'class SoftDeleteMixin' -r packages/rn-forge-django/src/rn_forge/django/drf/views # S12.2.5
grep -q 'perform_destroy' packages/rn-forge-django/src/rn_forge/django/drf/transfer.py # S12.2.5
(cd packages/rn-forge-django && uv run pytest -q tests/drf tests/models tests/test_conformance.py) # S12.2.4, S12.2.5
grep -q 'def soft_delete_router' -r packages/rn-forge-fastapi/src/rn_forge/fastapi # S12.2.6
(cd packages/rn-forge-fastapi && uv run pytest -q -m 'not scaffold') # S12.2.6
absent 'pytest.skip' packages/rn-forge-django/tests/test_conformance.py packages/rn-forge-fastapi/tests/test_conformance.py # S12.2.5, S12.2.6
uv run pyright # S12.2.3–S12.2.6
uv run lint-imports # S12.2.3–S12.2.6
absent 'AIP-164 soft delete \(deferred\)' packages/rn-forge-web/docs/guides/api-conventions.md # S12.2.7
for pkg in web django fastapi sqlalchemy; do
grep -qi 'soft delete\|soft-delete' "packages/rn-forge-$pkg/CHANGELOG.md" # S12.2.7
(cd "packages/rn-forge-$pkg" && uv run --group docs mkdocs build --strict -q --site-dir "$(mktemp -d)") # S12.2.7
done
uv run pytest -q -m scaffold # S12.2.7
Not scripted: the owner's acceptance of ADR-0010 (S12.2.1).
Considered and rejected
- Status-based soft delete (
status = DELETED), from the model-vocabulary idea. It cannot produce AIP-164'sdeleteTimeonce the resource is written again, and:undeleteis such a write. It also mixes lifecycle state with retention. - A default manager or global session hook that hides deleted rows. A get must return a deleted resource (AIP-164), and a hidden row breaks related-object lookups and the Django admin in ways that are hard to see. Visibility is decided in the view or the query, where the action is known.
DELETEanswering 204, as §10 does for a hard delete. AIP-164 returns the resource, and the client needs the newdeleteTimeandETag. Answering 204 would cost every client a second request.:batchDeletereturning the soft-deleted resources, as AIP-235 allows. It would give the method two response shapes depending on the resource. It stays 204, and a client that needs the result lists withshowDeleted=true.- A purge route or
expireTime. Purging is a retention decision with its own authorization. Nothing in the kit schedules it, so the kit does not advertise an expiry. django-safedelete1.5.0 (checked 2026-10-04). It is maintained: 1.5.0 was released 2026-08-17 and its tox matrix covers Django 4.2 to 6.1. It ships nopy.typedmarker and its classifiers stop at Python 3.8, so strict pyright sees untyped code. It hides deleted rows through its default manager (DELETED_INVISIBLE), which ADR-0010 rejects. Itssave()undeletes a soft-deleted row unlesskeep_deleted=True, so an ordinaryPUTwould undelete, where the wire rules answer 409. It adds cascade policies anddeleted_by_cascadethat the design does not use.soft_deleteandundeleteas a few lines on a nullable field are cheaper than overriding that much of the library.sqlalchemy-easy-softdelete0.9.1 (checked 2026-10-04). It is maintained (released 2026-06-16), typed (Typing :: Typed,py.typed), and supports Python 3.10 to 3.14. It installs a hook that rewrites every select on tables carrying its mixin, which ADR-0010 rejects, andGETof a deleted resource would needinclude_deletedon each query. Its SQLAlchemy range is>=1.4,<2.1, narrower than the package'ssqlalchemy>=2.0. It provides no version bump and noupdated_by, so the wire rules would still need our own helpers.