Storage-object deposit model: the registered deposit extension

[johnf]

Summary

Adds the storage-object deposit model as a registered extension (deposit) — the API's first write pathway. Spec bumped to 0.3.0 (openapi.yaml + CHANGELOG.md) with a new docs subcategory (docs/extensions/deposit/).

This supersedes the v1 read–write discussion paper's entity-granular writes, which the Technology Committee pushed back on because one crate spans many entities. Charted and decided on the wayfinder map Map: Storage-object deposit model.

The model

• A storage object is the real thing on disk: an RO-Crate plus all files it references. It is the sole write pathway — no entity CRUD, no standalone file endpoints.
• Deposit is a session: POST /deposits (create) or POST /storage-object/{id}/deposits (update) → stage crate and files (PUT /deposit/{id}/crate, PUT /deposit/{id}/file/{fileId}, inline or presigned) → POST /deposit/{id}/finalise (sync 200 or async 202; validation failure returns the deposit to open).
• The backend materialises catalog entities from the storage object via implementation-specific rules (PARADISEC: one item + files; LDaCA: exploded collections/subcollections), including many-to-one merges. Entities are projections; linkage is bidirectional (storageObjectIds on Entity, entityIds on StorageObject, optional storageObjectId on File).
• Updates use crate-as-manifest carry-forward: stage only changed files; at finalise each file entity resolves staged → carried-forward-by-@id → permitted-dangling. Last finalise wins as a unit, with an optional stale-finalise 409.
• Reads: minimal GET /storage-objects, lean GET /storage-object/{id}, GET /storage-object/{id}/crate returning the deposited crate verbatim; /entity/{id}/rocrate re-specced as implementation-defined provenance (stored or virtualised) but always a valid RO-Crate.
• Deletion: plain DELETE /storage-object/{id} (implementation-defined 409-with-reason), constrained DELETE /entity/{id} for contributor-less entities only, one 410/404 tombstone policy per implementation with a Tombstone schema.
• Discovery: the whole surface is one extension keyed in capabilities.extensions.deposit — required idMinting, fileUpload, tombstonePolicy; optional depositTtlSeconds, maxFileSizeBytes. Auth is a new coarse OAuth2 write scope.

Docs

An "Extension: deposit" sidebar subcategory: the extension guide (model, materialisation worked examples, capability field guidance, both visibility patterns) plus three flow pages — Depositing, Updating a Storage Object, and Deletion & Lifecycle. Extension registry table and capability examples updated.

Key decisions

• Session lifecycle and endpoint shapes
• Finalise semantics
• Update and versioning flow
• Storage-object deletion
• Storage-object read surface
• Capabilities and discovery

Open points for the committee

• Entity lifecycle on re-deposit (implementation-defined pruning) and the update-deposit concurrency model — on the agenda for the tech meeting of Thursday 2026-07-23.
• Conformance placement of deposit (mandatory / core-but-optional / extension — drafted as an extension) — being socialised on Slack.

Verification

pnpm lint (tsc, Biome, Redocly) and the full Docusaurus build (onBrokenLinks: 'throw') pass.