Detection finding

A DetectionFinding is derived state referencing stable notebook/page IDs. Findings may span consecutive pages (e.g. a poem continuing across pages).

Finding object (v1)

Field

Required

Notes

finding_id

yes

UUID hex; stable across review edits

detector_id

yes

Detector identity

detector_version

yes

Detector version at detection time

notebook_id

yes

Canonical project.id

start_page_id

yes

Inclusive; project.pages order

end_page_id

yes

Inclusive

finding_type

yes

e.g. poetry, custom:dreams

confidence

yes

0–1

evidence

yes

{reason, snippets[]}; optional bounded window_raw

detector_data

no

Schema-specific (e.g. optional title; names detector: name, tag_slug, count, samples)

start_boundary

no

{page_id, char_start?, char_end?, line_hint?}

end_boundary

no

Same shape as start_boundary

prompt_provenance

yes

{prompt_id, version}

model_provenance

yes

{model_name, model_digest, input_mode}

input_fingerprint

yes

Hash of inputs used

created_at

yes

ISO-8601 UTC

updated_at

yes

ISO-8601 UTC

review_status

yes

unreviewed | approved | rejected

page_reviews

no

{page_id: "approved"|"rejected"} for per-page review of a multi-page span. Unlisted span pages are unreviewed. Omit when empty.

Index

The published artifact for (notebook_id, detector_id) contains a findings[] array. Individual findings are not separate authoritative files in v1.

Cross-page spans

  • One finding may have start_page_id != end_page_id.

  • Partial-page boundaries are optional hints for human review.

  • Aggregation merges overlapping window observations deterministically (see detection-run-storage.md).

  • Per-page Accept / Reject records page_reviews without changing the detector span. Rejected pages lose the finding tag; accepted pages keep it. Finding-level Accept remaining approves every span page that is not already rejected.

  • Finding-level review_status is derived: all span pages rejected → rejected; every span page reviewed and at least one accepted → approved; otherwise unreviewed.

Identity rules

  • Use page_id, notebook_id, finding_id — never filesystem paths or filenames as identity.

Review carry-forward

On a successful republish for the same detector, preserve approved / rejected and page_reviews when the new finding matches a prior published finding on span identity (finding_type, start_page_id, end_page_id, tag_slug). tag_slug is empty except for the names detector (per-name findings on one page). Unmatched new findings start as unreviewed. Prior reviews without a match are dropped with the old published set.