feat(provenance): persist document structure as document_blocks

[mrsibe]

What does this PR do?

Persists the document structure the loaders already extract, so every character of a document can be traced back to a page, a heading and a bounding box. This is the data layer the citation work (#67, #69–#73) will build on.

Why?

addDocumentFromFile() consumed only parseResult.content/title/mimeType/metadata and discarded parseResult.structure entirely. There was nowhere to record which page or heading a span of text came from, so a future citation could only ever be document-level. See #66 and the epic #82.

Related issue

Fixes #66

What changed?

• Schema + migration — new document_blocks table (additive migration 0014_naive_lifeguard.sql): id, document_id, kind, order, page, level, text, start_offset, end_offset, bbox, metadata; indexes on (document_id, order) and (document_id, page). No changes to chunks.
• src/main/services/blocks/documentBlocks.ts — buildDocumentBlocks() is a pure function from a parse result to ordered block drafts. It never re-cleans text: every block's text is content.slice(startOffset, endOffset), so documents.content.slice(start_offset, end_offset) === text holds by construction.
  • Paged (PDF/PPT): one block per page, page matching structure.pages, with the page's normalized bbox.
  • Structured (Markdown/DOCX): heading blocks (kind: 'heading', level) plus paragraph blocks for the body between headings. It only trusts a heading offset when the title actually appears there, so WebLoader's all-zero offsets fall back to flat blocks instead of becoming bogus headings.
  • Flat (text/URL/notes, or unusable offsets): paragraph-level blocks split on blank lines.
• KnowledgeService — persists blocks in both ingestion paths: addDocumentFromFile() (with structure) and addDocument() (text, URL and note, flat). Adds getDocumentBlocks(), and deletes a document's blocks explicitly rather than relying on a foreign-key cascade the connection does not enable.
• PdfLoader — records a page's normalized text bbox, mapping its text items through the existing viewport transform so the renderer does not need to know the scale.

chunks are untouched, so retrieval and search results are unchanged — this issue only adds data.

How was this tested?

• npm test — 100 tests pass (8 new in test/blocks.test.ts): the slice invariant for every block from every fixture, dense/ordered numbering, PDF page agreement, bbox normalization inside the unit square, DOCX/Markdown heading levels, the flat fallback, and the untrusted-offset fallback.
• npm run typecheck — clean.
• npm run build — clean; verified 0014_naive_lifeguard.sql and meta/0014_snapshot.json are copied into out/main/db/migrations.
• npm run check:design — clean.
• npx eslint on every changed file — clean.

Not run locally: build:unpack + smoke:packaged (no xvfb on this machine). CI runs both on all three platforms; runMigrations() there applies migration 0014 against a fresh database, which is the packaged check that matters for this change. A manual PDF import is the remaining manual step from the issue.

Screenshots / recordings

Not applicable — no UI change.

Checklist

• I have reviewed my own changes.
• npm run typecheck passes.
• npm run build passes.
• I have tested the affected user workflow. (manual PDF import not run here; covered by CI smoke + the new unit tests)
• I have not included unrelated changes.
• I have updated documentation when necessary.

Desktop / build changes

• Not applicable
• npm run build:unpack passes. (delegated to CI)
• npm run smoke:packaged passes. (delegated to CI)