Annotations: mark regions to steer AI detection

[martsokha]

Introduce annotations as regions on a document that reference data locations to steer the AI — e.g. mark an area as sensitive to force detection there, or exclude a region from analysis.

Distinct from the old annotations concept (issue #101), which was reworked into threads/comments. This is about spatial/data-location hints fed into detection, not discussion.

Scope to define:

• Data model: annotation = (document, region/locator, intent: include/exclude/hint, optional label).
• How annotations flow into a detection run (RequestContext / analysis input).
• CRUD API + how they attach to a document.
• Relationship to file annotations for detection steering (see Add file annotations to steer detection (inclusion/exclusion regions) #139, which overlaps — reconcile or supersede).

Note: #139 ("Add file annotations to steer detection (inclusion/exclusion regions)") covers similar ground — decide whether this subsumes it.

[martsokha]

Consolidating #139 into this issue

Closing #139 ("Add file annotations to steer detection (inclusion/exclusion regions)") as a duplicate of this one, and carrying its validated implementation notes forward here. #139 had a prototype built and removed pending the cardinality decision below.

Runtime hook

The engine exposes AnalyzerParams.annotations: AnyAnnotations — caller-supplied inclusion/exclusion regions:

• Inclusion — "there may be an entity here" → recognizers (esp. LLM) adjudicate. Carries location (text byte range {start, end, page?}) + optional label/name/confidence.
• Exclusion — "flag nothing here" → analyzer drops overlapping entities.
• Bagged per-modality: AnyAnnotations { text, tabular, image, audio }.

Detect currently passes AnyAnnotations::default() (empty), so the capability is unused.

Open question to resolve first: cardinality

Are annotations a durable property of the file (one set per file, auto-loaded at detect — corrections/facts about the doc) or a per-run detection-time input (inline on the detect request, like scope)? Or both (persistent per-file base + inline override). "Multiple named sets per file that detect picks between" is the awkward middle — a detection-time strategy pushed into file-scoped storage; A/B / conservative-vs-aggressive belongs on the run/pipeline layer.

Validated implementation shape (one-set-per-file model, from the removed prototype)

• Storage: 1 DB row/file + 1 encrypted blob/file. Row workspace_file_annotations { id, file_id UNIQUE, account_id, annotations_key, timestamps }; the AnyAnnotations bag crypto.encrypt_json'd into a dedicated AnnotationsBucket (no TTL), keyed by a deterministic AnnotationKey::from_parts(workspace_id, file_id) so replace overwrites in place.
• API: PUT/GET/DELETE /files/{fileId}/annotations — PUT full-replace/upsert; GET returns 200 {} when none; DELETE clears row + blob.
• Detect: load the file's annotations (degrade to empty + log if the blob is unloadable — steering is advisory) into AnalyzerParams.annotations.
• Auth: AnnotateFiles permission for PUT/DELETE, ViewFiles for GET.

Review findings to carry forward (all fixed in the prototype)

• Orphan-blob leak on re-PUT if using a random key → deterministic per-file key (AnnotationsBucket has no TTL, so random keys leak forever).
• GET returns 200 {} for "no annotations", not 404 — empty is valid for a full-replace resource.
• A missing blob (torn record) degrades detect to empty, not hard-fail — steering is advisory.

Notes

• Annotations reveal where PII is/isn't → encrypt at rest (workspace-keyed), like file bytes.
• Distinct from workspace_files.tags (classification → ScopeParams.tags) and the engine's label_catalog (entity types to emit).