# 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