# Engine API (Delta)

## ADDED Requirements

### Requirement: Note mutation endpoint

The engine SHALL provide a `PATCH /api/v1/notes/{id}` endpoint for updating existing notes in place. See the `note-mutation` spec for full details.

#### Scenario: Note update endpoint exists
- **WHEN** a client sends `PATCH /api/v1/notes/42` with body `{"text": "new content"}`
- **THEN** the engine SHALL process the update synchronously and return the updated document

---

### Requirement: Document updated_at tracking

The engine SHALL track when documents are modified via an `updated_at` column. This column SHALL be NULL for documents that have never been updated.

#### Scenario: New document has no updated_at
- **WHEN** a document is first ingested
- **THEN** `updated_at` SHALL be NULL and `created_at` SHALL be set to the ingestion timestamp

#### Scenario: Note update sets updated_at
- **WHEN** a note is updated via `PATCH /api/v1/notes/{id}`
- **THEN** `updated_at` SHALL be set to the current timestamp

#### Scenario: Tag change sets updated_at
- **WHEN** tags are modified via `PUT /api/v1/documents/{id}/tags`
- **THEN** `updated_at` SHALL be set to the current timestamp

#### Scenario: Schema migration for updated_at
- **WHEN** the engine starts against a v2 database without an `updated_at` column
- **THEN** the engine SHALL automatically add `ALTER TABLE documents ADD COLUMN updated_at TEXT` and all existing documents SHALL have `updated_at = NULL`

## MODIFIED Requirements

### Requirement: Document management

The engine SHALL provide endpoints to list, inspect, remove, and download original files for ingested documents.

#### Scenario: List documents
- **WHEN** a client sends `GET /api/v1/documents`
- **THEN** the engine SHALL return a JSON array of documents with id, title, doc_type, tags, chunk_count, created_at, and updated_at

#### Scenario: List documents with filters
- **WHEN** a client sends `GET /api/v1/documents?type=pdf&tags=manual`
- **THEN** the engine SHALL return only documents matching all specified filters

#### Scenario: List documents sorted by most recent
- **WHEN** a client requests documents sorted by date
- **THEN** the engine SHALL use `COALESCE(updated_at, created_at)` for ordering, so un-mutated documents sort by creation time and mutated documents sort by their last update

#### Scenario: Get document details
- **WHEN** a client sends `GET /api/v1/documents/{id}`
- **THEN** the engine SHALL return the full document record including all chunks, their text content, `updated_at`, and whether the original file is available (`has_file: true/false`)

#### Scenario: Download original file
- **WHEN** a client sends `GET /api/v1/documents/{id}/file`
- **THEN** the engine SHALL return the original file with appropriate Content-Type and `Content-Disposition: attachment; filename="{original_filename}"` headers, or HTTP 404 if the file is not available

#### Scenario: Remove a document
- **WHEN** a client sends `DELETE /api/v1/documents/{id}`
- **THEN** the engine SHALL delete the document, all its chunks, associated embeddings, tag associations, and the stored original file from disk, and return HTTP 200 with a confirmation

#### Scenario: Remove non-existent document
- **WHEN** a client sends `DELETE /api/v1/documents/{id}` with a non-existent ID
- **THEN** the engine SHALL return HTTP 404

### Requirement: Engine status and reindex

The engine SHALL provide status information and support re-embedding all chunks. The `version` field in the status response SHALL always be present and SHALL reflect the engine's release version as read from the `VERSION` file. This field is the contract used by clients for compatibility checking.

#### Scenario: Get engine status
- **WHEN** a client sends `GET /api/v1/status`
- **THEN** the engine SHALL return JSON with `version` (string, from VERSION file), model_name, embedding_dim, GPU device info, database stats (document count by type, total chunks, DB size), and queue stats (queued/processing job count)

#### Scenario: Trigger reindex
- **WHEN** a client sends `POST /api/v1/reindex`
- **THEN** the engine SHALL re-embed all existing chunks using the `enriched_text` column and the currently loaded model, and return progress information. This operation SHALL NOT block search queries.