Document Lifecycle

Aggregate Role

Document is the aggregate root for the ingestion slice.

It owns:

  • identity

  • workspace ownership

  • registration metadata

  • lifecycle status

  • degraded / failed flags

  • attached ParsedDocument

  • attached ChunkSet

It does not perform parsing, chunking, embedding, or indexing itself. Those actions are orchestrated by application services and their infrastructure collaborators.

Status Meanings

registered

  • a document has been accepted, stored, checksummed, and persisted

  • it is ready for parsing

parsing

  • parsing is in progress

parsed

  • canonical parsed content is attached

  • ready for chunking

chunking

  • chunk construction is in progress

chunked

  • chunk set is attached

  • ready for embedding/indexing

embedding

  • chunk embedding is in progress

indexing

  • OpenSearch indexing is in progress

indexed

  • chunk writes have completed successfully

  • finalization to ready or degraded still follows

ready

  • searchable happy-path terminal state

degraded

  • searchable terminal state with known quality loss or warning-driven fallback

failed

  • non-recovering terminal state in the current public API surface

archived

  • archived terminal state with one allowed exit to deleted

deleted

  • fully immutable terminal state

Allowed Transition Shape

Current happy path:

registered -> parsing -> parsed -> chunking -> chunked -> embedding -> indexing -> indexed -> ready

Current degraded tail:

... -> indexed -> degraded

Failure path:

  • any non-hard-terminal state can move to failed

Archive/delete:

  • ready or degraded -> archived

  • archived -> deleted

Reprocessing supported by the aggregate:

  • ready or degraded -> registered for reparse

  • ready or degraded -> parsed for rechunk

Important note:

  • the aggregate supports those reprocessing transitions

  • the current HTTP surface does not yet expose dedicated reparse/rechunk commands

Quality Signals

The final lifecycle state is not just “did the code run.”

The system also considers:

  • parser quality

  • chunk partiality

  • embedding warnings

  • indexing warnings

  • fewer indexed chunks than expected

That is why a document can legitimately end in degraded rather than ready.

Searchability

The aggregate considers a document searchable when:

  • it is ready, or

  • it is degraded, or

  • it is being reprocessed but still has a prior chunk set attached

This supports truthful lifecycle modeling without pretending every in-progress document is searchable.

Workspace Boundary Notes

Document does not own workspace policy, but it is bounded by Workspace.

That means:

  • active document operations require an active workspace member through the shared access filter

  • workspace archive blocks new active document operations

  • workspace delete closes the in-process workspace boundary before destructive cleanup starts

  • governance-driven workspace delete removes bounded documents before removing the workspace record