feat(notes): add semantic embedding index and graph edges (TASK-13134)

[rmusser01]

Change summary

Required before merge: Human-authored change summary pending. Per repository policy, the requester must explain in their own words both what changed and why these implementation choices were made.

Summary

• What changed: Adds an opt-in, owner- and dataset-scoped Notes embedding lifecycle, bounded Jobs-backed indexing and recovery, ChromaDB/pgvector vector storage, and semantic Notes Graph edges across the WebUI and browser extension. Semantic edges include provenance and evidence, remain distinct from manual links, and can only become manual relationships through explicit user conversion.
• Why: Enable reproducible semantic relationship discovery in Notes while preserving user control, tenant isolation, bounded operations, deterministic lifecycle cleanup, and graceful feature-disable behavior.

Validation

• Tests added/updated for behavior changes
• Relevant unit/integration/property tests pass locally
• Docs updated for behavior, routes, configuration, operations, and WebUI/extension usage
• Fresh TASK-13134 backend matrix: 1,340 passed, 6 documented optional pgvector capability skips, 35 warnings
• SQLite and active PostgreSQL authorization, Jobs, lifecycle, publication, erasure, and recovery paths exercised
• Ruff and scoped formatting checks passed
• Bandit reported 0 findings in touched production paths
• git diff --check origin/dev...HEAD passed

UX Audit Checklist (v2 Stage 5)

The generic Stage 5 and Flashcards checklist is not applicable. This change has scoped Notes WebUI/browser-extension component, accessibility, localization, service, and E2E coverage.

Watchlists Accessibility Checklist (Group 09 Stage 5)

Not applicable; no Watchlists behavior changed.

Watchlists Scale Checklist (Group 10 Stage 5)

Not applicable; no Watchlists behavior changed.

Risk & Rollback

• Risk level: High. This is a cross-layer Notes feature with database schema, background jobs, vector backends, API, WebUI, extension, and operational behavior. The branch is also currently behind dev, so it must be rebased and revalidated before merge.
• Rollback plan: Revert the PR. Semantic indexing is opt-in and semantic edges are derived; disabling the feature prevents new semantic work, and rollback does not require converting or deleting canonical manual links.

Notes

• TASK-13134
• Worktree retained for PR review iterations.

---

Summary by cubic

Implements TASK-13134 by adding an opt-in, owner- and dataset-scoped semantic index for Notes. Indexing runs as bounded Jobs, stores vectors in ChromaDB or pgvector, and surfaces similar-content edges in the Notes Graph across WebUI and extension, which previously showed only manual and structural links. Semantic edges are hidden unless requested, remain distinct from manual links, and become manual links only through explicit user conversion.

Migration

• Adds notes.graph.semantic.manage to existing Notes-writing roles and notes.graph.semantic.read for graph readers.
• Adds schema v67 with semantic health sweep tables for SQLite and PostgreSQL; the Postgres CI shard runs pgvector and covers the new semantic worker tests.
• Enabling the index requires explicit consent; disabling it stops new semantic work and hides derived edges without changing manual links.
• The branch is behind dev and must be rebased and revalidated before merge.

^{Written for commit ef8cd59. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Team

Run ID: cf653b67-f65b-456d-b732-12cff3332211

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

Add tenant-scoped Notes semantic index and graph relationships

✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

AI Description

• Adds opt-in, tenant-scoped semantic indexing using ChromaDB or pgvector.
• Projects evidence-backed semantic edges without altering canonical manual relationships.
• Adds management UX, lifecycle workers, cleanup, documentation, and comprehensive tests.

Diagram

graph TD
  UI["Notes UI"] --> API["Semantic API"] --> Jobs["Jobs worker"] --> Provider["Embedding provider"]
  Jobs --> Ledger[("Semantic ledger")] --> Projector["Graph projector"] --> API
  Jobs --> Vectors[("Vector storage")] --> Projector

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Compute similarities on demand

• ➕ Avoids generation, work-ledger, and cleanup persistence
• ➕ Simplifies index lifecycle operations
• ➖ Repeats provider cost and latency for graph queries
• ➖ Cannot provide stable, reproducible generation evidence
• ➖ Scales poorly for large Notes datasets

2. Materialize semantic edges

• ➕ Makes graph reads simpler and faster
• ➕ Avoids query-time vector projection
• ➖ Creates substantial stale-edge maintenance
• ➖ Risks conflating derived evidence with canonical relationships
• ➖ Requires rewriting edges after every note or model change

3. Dedicated semantic indexing service

• ➕ Isolates provider and vector workloads operationally
• ➕ Allows independent scaling and deployment
• ➖ Adds distributed transactions and another authorization boundary
• ➖ Complicates erasure, tenant isolation, and local deployments
• ➖ Requires a larger operational footprint

Recommendation: Keep the PR's Jobs-backed, generation-fenced projection model. It preserves user control and canonical manual links while supporting bounded recovery and two deployment-friendly vector backends; on-demand computation and materialized edges weaken reproducibility or lifecycle correctness, while a separate service is disproportionate for the current architecture.

Files changed (146) +46056 / -316

Enhancement (54) +13572 / -166

option.jsonLocalize semantic graph controls +145/-1

Localize semantic graph controls

• Adds English strings for semantic lifecycle states, consent disclosures, evidence, actions, and errors.

apps/packages/ui/src/assets/locale/en/option.json

NotesGraphCanvas.tsxRender and select semantic graph edges +111/-17

Render and select semantic graph edges

• Adds semantic edge styling, labels, selection, and accessibility behavior to the graph canvas.

apps/packages/ui/src/components/Notes/NotesGraphCanvas.tsx

NotesGraphInspector.tsxAdd semantic index management and evidence UI +681/-15

Add semantic index management and evidence UI

• Adds consent disclosures, lifecycle actions, progress, semantic edge details, and explicit manual-link conversion.

apps/packages/ui/src/components/Notes/NotesGraphInspector.tsx

NotesGraphRelationshipsView.tsxPresent semantic relationship evidence +300/-12

Present semantic relationship evidence

• Groups semantic relationships separately and renders similarity, excerpts, provenance, and conversion controls.

apps/packages/ui/src/components/Notes/NotesGraphRelationshipsView.tsx

NotesGraphToolbar.tsxAdd semantic query controls +105/-0

Add semantic query controls

• Introduces accessible controls for semantic visibility, similarity threshold, and result count.

apps/packages/ui/src/components/Notes/NotesGraphToolbar.tsx

NotesGraphWorkspace.tsxWire semantic controls into the graph workspace +60/-2

Wire semantic controls into the graph workspace

• Connects semantic lifecycle state, toolbar controls, edge selection, and manual conversion to the workspace.

apps/packages/ui/src/components/Notes/NotesGraphWorkspace.tsx

useNotesGraphWorkspace.tsxOrchestrate semantic graph queries and conversion +270/-10

Orchestrate semantic graph queries and conversion

• Adds first-page semantic querying, bounded controls, safe ordinary-graph fallback, and idempotent manual conversion.

apps/packages/ui/src/components/Notes/hooks/useNotesGraphWorkspace.tsx

useNotesSemanticIndex.tsxAdd semantic-index lifecycle hook +454/-0

Add semantic-index lifecycle hook

• Implements scoped capability and status queries, run polling, lifecycle mutations, and conflict reconciliation.

apps/packages/ui/src/components/Notes/hooks/useNotesSemanticIndex.tsx

notes-manager-utils.tsAdd semantic graph utility labels +61/-0

Add semantic graph utility labels

• Adds note-ID normalization and semantic edge labeling helpers for the Notes manager.

apps/packages/ui/src/components/Notes/notes-manager-utils.ts

option.jsonPublish extension semantic localization +435/-0

Publish extension semantic localization

• Adds browser-extension locale entries for semantic graph management and relationship evidence.

apps/packages/ui/src/public/_locales/en/option.json

note-graph-suggestions.tsExtend the graph client for semantic edges +304/-23

Extend the graph client for semantic edges

• Adds strict semantic status, evidence, query-control, and manual-conversion request contracts.

apps/packages/ui/src/services/note-graph-suggestions.ts

note-semantic-index.tsAdd the semantic-index API client +512/-0

Add the semantic-index API client

• Implements validated lifecycle and run requests with stable typed errors and idempotency keys.

apps/packages/ui/src/services/note-semantic-index.ts

notes_graph.pyProject semantic edges through the Notes graph API +311/-52

Project semantic edges through the Notes graph API

• Adds opt-in semantic query controls, projection, typed errors, rate limits, evidence, and verified manual conversion.

tldw_Server_API/app/api/v1/endpoints/notes_graph.py

notes_semantic_index.pyAdd semantic-index management endpoints +445/-0

Add semantic-index management endpoints

• Exposes capabilities, status, enable, disable, rebuild, retry, run lookup, and cancellation under Notes Graph.

tldw_Server_API/app/api/v1/endpoints/notes_semantic_index.py

content.pyMount semantic routes in the content API +7/-0

Mount semantic routes in the content API

• Registers the nested semantic-index router in the content route group.

tldw_Server_API/app/api/v1/router_groups/content.py

minimal.pyMount semantic routes in the minimal API +7/-0

Mount semantic routes in the minimal API

• Registers the nested semantic-index router in the minimal route group.

tldw_Server_API/app/api/v1/router_groups/minimal.py

notes_graph.pyDefine semantic graph schemas +215/-4

Define semantic graph schemas

• Adds semantic edge evidence, status, query controls, conversion input, and response authorization fields.

tldw_Server_API/app/api/v1/schemas/notes_graph.py

notes_semantic_index.pyDefine semantic lifecycle schemas +171/-0

Define semantic lifecycle schemas

• Adds strict request and response models for capabilities, status, mutations, runs, and typed errors.

tldw_Server_API/app/api/v1/schemas/notes_semantic_index.py

users_repo.pySupport bounded user enumeration +25/-0

Support bounded user enumeration

• Adds paginated user listing needed by semantic maintenance and health sweeps.

tldw_Server_API/app/core/AuthNZ/repos/users_repo.py

ChaChaNotes_DB.pyAdd semantic persistence migrations +653/-3

Add semantic persistence migrations

• Advances SQLite and PostgreSQL schemas through v67 with tenant-scoped configurations, generations, manifests, work, cleanup ledgers, and receipts.

tldw_Server_API/app/core/DB_Management/ChaChaNotes_DB.py

__init__.pyExport semantic persistence types +22/-0

Export semantic persistence types

• Exposes semantic models and store components from the ChaCha persistence package.

tldw_Server_API/app/core/DB_Management/chacha/init.py

note_semantic_models.pyDefine semantic persistence records +294/-0

Define semantic persistence records

• Adds typed states and records for configurations, generations, notes, chunks, work, cleanup, health, and receipts.

tldw_Server_API/app/core/DB_Management/chacha/note_semantic_models.py

note_semantic_store.pyImplement the semantic authority ledger +5190/-0

Implement the semantic authority ledger

• Implements fenced, owner-scoped lifecycle, CAS publication, work claiming, cleanup, projection, observability, and erasure persistence.

tldw_Server_API/app/core/DB_Management/chacha/note_semantic_store.py

note_store.pyIntegrate Notes lifecycle with semantic indexing +194/-6

Integrate Notes lifecycle with semantic indexing

• Marks enabled semantic generations dirty or tombstoned transactionally when canonical Notes change through local or Sync paths.

tldw_Server_API/app/core/DB_Management/chacha/note_store.py

manager.pyAdd semantic Jobs support +95/-0

Add semantic Jobs support

• Extends JobManager with semantic health sweep and owner-scoped operation support.

tldw_Server_API/app/core/Jobs/manager.py

notes_semantic_health.pyDefine semantic health checkpoints +90/-0

Define semantic health checkpoints

• Adds bounded validation and aggregation contracts for persisted semantic health sweeps.

tldw_Server_API/app/core/Jobs/notes_semantic_health.py

embeddings_adapter_registry.pyExpose embedding adapter availability +5/-0

Expose embedding adapter availability

• Adds registry capability needed to fail closed when a configured semantic provider lacks an executable adapter.

tldw_Server_API/app/core/LLM_Calls/embeddings_adapter_registry.py

payload_utils.pyPreserve semantic embedding payload fields +4/-1

Preserve semantic embedding payload fields

• Allows the embedding payload path to retain dimensions and related semantic execution fields.

tldw_Server_API/app/core/LLM_Calls/payload_utils.py

google_embeddings_adapter.pyHarden Google embedding batches +74/-5

Harden Google embedding batches

• Adds native multi-input execution, output ordering, dimensions, and strict response handling for semantic indexing.

tldw_Server_API/app/core/LLM_Calls/providers/google_embeddings_adapter.py

huggingface_embeddings_adapter.pyHarden HuggingFace embedding batches +10/-2

Harden HuggingFace embedding batches

• Supports bounded batched semantic requests and stricter response validation.

tldw_Server_API/app/core/LLM_Calls/providers/huggingface_embeddings_adapter.py

openai_embeddings_adapter.pyHarden OpenAI embedding batches +15/-3

Harden OpenAI embedding batches

• Preserves indexed batch ordering and validates single and multi-input semantic responses.

tldw_Server_API/app/core/LLM_Calls/providers/openai_embeddings_adapter.py

formatters.pyFormat semantic graph metadata +8/-1

Format semantic graph metadata

• Carries semantic status, evidence, and authorization metadata through graph formatter output.

tldw_Server_API/app/core/Notes_Graph/formatters.py

graph_cache.pyCache semantic graph projections safely +281/-0

Cache semantic graph projections safely

• Adds semantic query identities and revision-aware cache entries without mixing them with ordinary graph results.

tldw_Server_API/app/core/Notes_Graph/graph_cache.py

graph_service.pyPrepare graph service for semantic composition +178/-9

Prepare graph service for semantic composition

• Adds semantic cursor binding and bounded candidate retrieval used by the asynchronous projector.

tldw_Server_API/app/core/Notes_Graph/graph_service.py

semantic_api.pyImplement semantic lifecycle coordination +1141/-0

Implement semantic lifecycle coordination

• Coordinates capability disclosure, consent, status, idempotent Jobs admission, cancellation, disablement, and runtime construction.

tldw_Server_API/app/core/Notes_Graph/semantic_api.py

semantic_capabilities.pyDefine fail-closed semantic capabilities +384/-0

Define fail-closed semantic capabilities

• Builds deterministic provider, endpoint, storage, dimension, disclosure, compatibility, and availability contracts.

tldw_Server_API/app/core/Notes_Graph/semantic_capabilities.py

semantic_content.pyCreate deterministic Note chunks +315/-0

Create deterministic Note chunks

• Normalizes Notes, enforces content bounds, fingerprints content, creates opaque chunk IDs, and reconstructs evidence excerpts.

tldw_Server_API/app/core/Notes_Graph/semantic_content.py

semantic_embeddings.pyImplement pinned embedding execution +0/-0

Implement pinned embedding execution

• Adds consent-bound provider execution, dimension probing, bounded batching, validation, accounting, and run-local deduplication.

tldw_Server_API/app/core/Notes_Graph/semantic_embeddings.py

semantic_endpoint.pyCanonicalize semantic provider origins +0/-0

Canonicalize semantic provider origins

• Adds strict sanitization and comparison of HTTP origins used in capability and execution fences.

tldw_Server_API/app/core/Notes_Graph/semantic_endpoint.py

semantic_erasure.pyAdd fail-closed semantic erasure +0/-0

Add fail-closed semantic erasure

• Fences indexing, drains and confirms vector cleanup, then atomically removes semantic state and canonical Notes.

tldw_Server_API/app/core/Notes_Graph/semantic_erasure.py

semantic_indexing.pyOrchestrate bounded semantic generations +0/-0

Orchestrate bounded semantic generations

• Builds and maintains generation snapshots with versioned reads, run budgets, retries, publication fences, and activation checks.

tldw_Server_API/app/core/Notes_Graph/semantic_indexing.py

semantic_jobs.pyDefine receipt-backed semantic Jobs +0/-0

Define receipt-backed semantic Jobs

• Adds content-free Jobs payloads, idempotent admission, owner scoping, cancellation, recovery, and result validation.

tldw_Server_API/app/core/Notes_Graph/semantic_jobs.py

semantic_observability.pyAdd bounded semantic observability +0/-0

Add bounded semantic observability

• Defines low-cardinality metrics, health aggregation, and content-free audit events for lifecycle and query operations.

tldw_Server_API/app/core/Notes_Graph/semantic_observability.py

semantic_projector.pyProject verified semantic graph edges +0/-0

Project verified semantic graph edges

• Queries active-generation vectors, ranks note matches, reconstructs bounded evidence, and composes edges under graph caps.

tldw_Server_API/app/core/Notes_Graph/semantic_projector.py

semantic_publication.pyFence cross-store semantic publication +0/-0

Fence cross-store semantic publication

• Orders vector writes before manifest CAS, validates generation activation, and durably coordinates obsolete-vector cleanup.

tldw_Server_API/app/core/Notes_Graph/semantic_publication.py

semantic_scoring.pyRank semantic Note matches +0/-0

Rank semantic Note matches

• Converts cosine distances into bounded similarities and deterministically ranks passage evidence at Note level.

tldw_Server_API/app/core/Notes_Graph/semantic_scoring.py

semantic_vectors.pyAdd the semantic vector facade +0/-0

Add the semantic vector facade

• Validates generation authority, dimensions, vectors, query budgets, backend results, and confirmed cleanup.

tldw_Server_API/app/core/Notes_Graph/semantic_vectors.py

semantic_vectors_chroma.pyImplement vector-only ChromaDB storage +0/-0

Implement vector-only ChromaDB storage

• Uses opaque cosine collections for vector upsert, fetch, query, deletion, and confirmed generation cleanup.

tldw_Server_API/app/core/Notes_Graph/semantic_vectors_chroma.py

semantic_vectors_pg.pyImplement forced-RLS pgvector storage +0/-0

Implement forced-RLS pgvector storage

• Creates validated dimension-specific HNSW tables and performs tenant-scoped vector operations with bounded scans.

tldw_Server_API/app/core/Notes_Graph/semantic_vectors_pg.py

introspection.pyIntrospect conditional semantic rate limits +0/-0

Introspect conditional semantic rate limits

• Supports endpoints declaring multiple possible rate-limit resources for privilege route verification.

tldw_Server_API/app/core/PrivilegeMaps/introspection.py

notes.pyPropagate dataset scope into semantic lifecycle +0/-0

Propagate dataset scope into semantic lifecycle

• Passes Sync dataset identity to Note upsert and tombstone operations so semantic work remains correctly scoped.

tldw_Server_API/app/core/Sync/v2/materializers/notes.py

http_client.pyMake redirect behavior configurable +0/-0

Make redirect behavior configurable

• Adds an explicit follow-redirects option used to prevent semantic provider origin changes.

tldw_Server_API/app/core/http_client.py

main.pyRegister semantic API metadata and revise diagnostics +0/-0

Register semantic API metadata and revise diagnostics

• Adds semantic-index OpenAPI metadata and also revises logging, metrics access, health, and readiness behavior.

tldw_Server_API/app/main.py

admin_data_subject_requests_service.pyIntegrate semantic cleanup with Notes erasure +0/-0

Integrate semantic cleanup with Notes erasure

• Routes Notes data-subject erasure through the semantic coordinator before deleting canonical owner data.

tldw_Server_API/app/services/admin_data_subject_requests_service.py

Tests (69) +29163 / -130

notes-ux.spec.tsExtend extension Notes semantic UX coverage +395/-70

Extend extension Notes semantic UX coverage

• Exercises semantic management, graph controls, evidence, conversion, localization, and responsive behavior in the extension.

apps/extension/tests/e2e/notes-ux.spec.ts

NotesGraphCanvas.graph-view.test.tsxTest semantic graph canvas behavior +273/-5

Test semantic graph canvas behavior

• Covers semantic edge rendering, labels, selection, and graph-view interactions.

apps/packages/ui/src/components/Notes/tests/NotesGraphCanvas.graph-view.test.tsx

NotesGraphInspector.semantic.integration.test.tsxTest semantic inspector integration +270/-0

Test semantic inspector integration

• Validates the inspector's integration with lifecycle controllers and graph relationships.

apps/packages/ui/src/components/Notes/tests/NotesGraphInspector.semantic.integration.test.tsx

NotesGraphInspector.semantic.test.tsxTest semantic inspector states and actions +1148/-0

Test semantic inspector states and actions

• Covers disclosures, lifecycle states, permissions, errors, confirmations, evidence, and focus behavior.

apps/packages/ui/src/components/Notes/tests/NotesGraphInspector.semantic.test.tsx

NotesGraphRelationshipsView.accessibility.test.tsxTest semantic relationship accessibility +324/-3

Test semantic relationship accessibility

• Extends relationship accessibility tests for evidence and manual-conversion controls.

apps/packages/ui/src/components/Notes/tests/NotesGraphRelationshipsView.accessibility.test.tsx

NotesGraphToolbar.i18n.test.tsxTest toolbar localization +89/-0

Test toolbar localization

• Verifies semantic graph controls use localized labels and announcements.

apps/packages/ui/src/components/Notes/tests/NotesGraphToolbar.i18n.test.tsx

NotesGraphWorkspace.axe.test.tsxAudit semantic workspace accessibility +61/-3

Audit semantic workspace accessibility

• Extends axe coverage to the semantic graph workspace.

apps/packages/ui/src/components/Notes/tests/NotesGraphWorkspace.axe.test.tsx

NotesGraphWorkspace.loading-i18n.test.tsxTest localized semantic loading states +12/-0

Test localized semantic loading states

• Verifies loading feedback remains localized when semantic graph data is requested.

apps/packages/ui/src/components/Notes/tests/NotesGraphWorkspace.loading-i18n.test.tsx

NotesGraphWorkspace.responsive.test.tsxTest responsive semantic graph layout +14/-1

Test responsive semantic graph layout

• Extends responsive workspace coverage for the added semantic controls and inspector content.

apps/packages/ui/src/components/Notes/tests/NotesGraphWorkspace.responsive.test.tsx

NotesGraphWorkspace.view-mode.test.tsxTest semantic graph view modes +12/-0

Test semantic graph view modes

• Verifies semantic controls behave correctly across graph workspace view modes.

apps/packages/ui/src/components/Notes/tests/NotesGraphWorkspace.view-mode.test.tsx

semantic-capability-drift-api.jsonAdd capability-drift API fixture +38/-0

Add capability-drift API fixture

• Provides deterministic capability and status responses for semantic configuration-drift tests.

apps/packages/ui/src/components/Notes/tests/fixtures/semantic-capability-drift-api.json

useNotesGraphWorkspace.test.tsxTest semantic graph workspace orchestration +945/-5

Test semantic graph workspace orchestration

• Covers opt-in queries, pagination, controls, fallback graphs, authorization, and manual conversion.

apps/packages/ui/src/components/Notes/tests/useNotesGraphWorkspace.test.tsx

useNotesSemanticIndex.test.tsxTest semantic lifecycle hook +588/-0

Test semantic lifecycle hook

• Covers scoped queries, polling, lifecycle mutations, conflicts, permissions, offline behavior, and cache reconciliation.

apps/packages/ui/src/components/Notes/tests/useNotesSemanticIndex.test.tsx

notes-semantic-fallback.test.tsTest semantic localization fallbacks +64/-0

Test semantic localization fallbacks

• Verifies required semantic strings resolve safely through localization fallback behavior.

apps/packages/ui/src/i18n/tests/notes-semantic-fallback.test.ts

note-graph-suggestions.test.tsTest semantic graph client contracts +231/-0

Test semantic graph client contracts

• Covers semantic response validation, query parameters, evidence bounds, and manual conversion.

apps/packages/ui/src/services/tldw/tests/note-graph-suggestions.test.ts

note-semantic-index.test.tsTest semantic-index API client +445/-0

Test semantic-index API client

• Validates lifecycle requests, response schemas, disclosure consistency, and error translation.

apps/packages/ui/src/services/tldw/tests/note-semantic-index.test.ts

notes-semantic-graph.spec.tsAdd WebUI semantic graph E2E coverage +678/-0

Add WebUI semantic graph E2E coverage

• Exercises consent, indexing states, graph controls, evidence inspection, conversion, errors, and accessibility.

apps/tldw-frontend/e2e/workflows/notes-semantic-graph.spec.ts

test_admin_data_subject_requests_service.pyTest semantic-aware Notes erasure +0/-0

Test semantic-aware Notes erasure

• Covers successful cleanup, unavailable backends, missing stores, and failure propagation in data-subject requests.

tldw_Server_API/tests/Admin/test_admin_data_subject_requests_service.py

test_authnz_users_repo_postgres.pyTest PostgreSQL user pagination +0/-0

Test PostgreSQL user pagination

• Validates the bounded user listing used by semantic maintenance on PostgreSQL.

tldw_Server_API/tests/AuthNZ/integration/test_authnz_users_repo_postgres.py

test_notes_graph_semantic_permissions_postgres.pyTest semantic permissions on PostgreSQL +0/-0

Test semantic permissions on PostgreSQL

• Exercises semantic route authorization, role assignment, and tenant isolation against PostgreSQL.

tldw_Server_API/tests/AuthNZ/integration/test_notes_graph_semantic_permissions_postgres.py

test_authnz_users_repo_sqlite.pyTest SQLite user pagination +0/-0

Test SQLite user pagination

• Validates bounded semantic-maintenance user listing on SQLite.

tldw_Server_API/tests/AuthNZ_SQLite/test_authnz_users_repo_sqlite.py

test_notes_graph_semantic_permissions.pyTest semantic lifecycle permissions +0/-0

Test semantic lifecycle permissions

• Verifies read and manage permission requirements and stable denial behavior.

tldw_Server_API/tests/AuthNZ_Unit/test_notes_graph_semantic_permissions.py

test_notes_graph_suggestion_permissions.pyPreserve suggestion permissions with semantics +0/-0

Preserve suggestion permissions with semantics

• Confirms semantic authorization changes do not alter existing suggestion permission behavior.

tldw_Server_API/tests/AuthNZ_Unit/test_notes_graph_suggestion_permissions.py

test_chacha_migration_v64.pyUpdate the v64 migration expectation +1/-0

Update the v64 migration expectation

• Adjusts migration coverage for the schema versions introduced after v64.

tldw_Server_API/tests/DB_Management/test_chacha_migration_v64.py

test_chacha_semantic_migration.pyTest SQLite semantic schema migration +335/-0

Test SQLite semantic schema migration

• Validates semantic tables, constraints, indexes, rollback, and schema ownership on SQLite.

tldw_Server_API/tests/DB_Management/test_chacha_semantic_migration.py

test_chacha_semantic_migration_postgres.pyTest PostgreSQL semantic schema migration +1041/-0

Test PostgreSQL semantic schema migration

• Covers semantic relations, forced RLS, race handling, rollback, and tenant isolation on PostgreSQL.

tldw_Server_API/tests/DB_Management/test_chacha_semantic_migration_postgres.py

test_chacha_semantic_migration_v66.pyTest SQLite cleanup-ledger migration +200/-0

Test SQLite cleanup-ledger migration

• Validates the v66 obsolete-vector cleanup schema and migration behavior on SQLite.

tldw_Server_API/tests/DB_Management/test_chacha_semantic_migration_v66.py

test_chacha_semantic_migration_v66_postgres.pyTest PostgreSQL cleanup-ledger migration +571/-0

Test PostgreSQL cleanup-ledger migration

• Validates v66 cleanup persistence, constraints, RLS, and concurrent migration behavior.

tldw_Server_API/tests/DB_Management/test_chacha_semantic_migration_v66_postgres.py

test_chacha_semantic_migration_v67.pyTest SQLite semantic receipt migration +100/-0

Test SQLite semantic receipt migration

• Validates v67 model-revision and operation-receipt persistence on SQLite.

tldw_Server_API/tests/DB_Management/test_chacha_semantic_migration_v67.py

test_chacha_semantic_migration_v67_postgres.pyTest PostgreSQL semantic receipt migration +344/-0

Test PostgreSQL semantic receipt migration

• Validates v67 model authority, receipt tables, indexes, RLS, and race safety.

tldw_Server_API/tests/DB_Management/test_chacha_semantic_migration_v67_postgres.py

test_notes_semantic_policy.pyTest semantic embedding policy +862/-0

Test semantic embedding policy

• Covers provider allowlists, credentials, endpoint origins, capability drift, dimensions, and data boundaries.

tldw_Server_API/tests/Embeddings_isolated/test_notes_semantic_policy.py

test_jobs_migrations_postgres.pyTest PostgreSQL semantic Jobs migrations +117/-0

Test PostgreSQL semantic Jobs migrations

• Verifies semantic health and operation schema changes in the PostgreSQL Jobs database.

tldw_Server_API/tests/Jobs/test_jobs_migrations_postgres.py

test_jobs_migrations_sqlite.pyTest SQLite semantic Jobs migrations +300/-0

Test SQLite semantic Jobs migrations

• Verifies semantic health and operation schema changes in the SQLite Jobs database.

tldw_Server_API/tests/Jobs/test_jobs_migrations_sqlite.py

test_embeddings_google_native_http.pyTest Google semantic embedding batches +469/-15

Test Google semantic embedding batches

• Covers native HTTP batching, dimensions, ordering, accounting, and malformed responses.

tldw_Server_API/tests/LLM_Adapters/unit/test_embeddings_google_native_http.py

test_embeddings_huggingface_native_http.pyTest HuggingFace semantic embedding batches +116/-0

Test HuggingFace semantic embedding batches

• Validates bounded batched inputs and strict vector response handling.

tldw_Server_API/tests/LLM_Adapters/unit/test_embeddings_huggingface_native_http.py

test_openai_embeddings_adapter_batch_single.pyTest OpenAI batch and single embeddings +121/-18

Test OpenAI batch and single embeddings

• Covers indexed response ordering and validation for single and batched semantic requests.

tldw_Server_API/tests/LLM_Adapters/unit/test_openai_embeddings_adapter_batch_single.py

test_semantic_endpoints.pyTest semantic lifecycle endpoints +686/-0

Test semantic lifecycle endpoints

• Exercises route contracts, authorization, idempotency, conflicts, status, and cancellation.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_endpoints.py

test_semantic_erasure.pyTest semantic erasure integration +1430/-0

Test semantic erasure integration

• Covers fencing, cleanup confirmation, retries, timeouts, cancellation, SQLite, and PostgreSQL erasure paths.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_erasure.py

test_semantic_graph_endpoint.pyTest semantic graph endpoint integration +358/-0

Test semantic graph endpoint integration

• Validates opt-in projection, degradation, query controls, evidence, pagination, and rate limits.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_graph_endpoint.py

test_semantic_jobs.pyTest semantic Jobs integration +2503/-0

Test semantic Jobs integration

• Covers admission, execution, recovery, fencing, cancellation, retries, worker behavior, and content-free payloads.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_jobs.py

test_semantic_manual_conversion.pyTest semantic-to-manual conversion +511/-0

Test semantic-to-manual conversion

• Verifies pair and generation revalidation, authorization, idempotency, Sync coordination, and stale conflicts.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_manual_conversion.py

test_semantic_note_lifecycle.pyTest SQLite semantic Note lifecycle +259/-0

Test SQLite semantic Note lifecycle

• Ensures create, edit, restore, delete, and Sync mutations enqueue correct semantic work transactionally.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_note_lifecycle.py

test_semantic_note_lifecycle_postgres.pyTest PostgreSQL semantic Note lifecycle +278/-0

Test PostgreSQL semantic Note lifecycle

• Exercises transactional dirty and tombstone behavior with PostgreSQL tenant scoping.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_note_lifecycle_postgres.py

test_semantic_publication.pyTest semantic publication integration +4722/-0

Test semantic publication integration

• Extensively covers CAS publication, activation, cleanup ledgers, cancellation races, recovery, and cross-store failure handling.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_publication.py

test_semantic_route_order.pyTest nested semantic route ordering +72/-0

Test nested semantic route ordering

• Ensures static capability and run routes are not shadowed by graph path parameters.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_route_order.py

test_semantic_vectors_chroma.pyTest Chroma semantic vector storage +680/-0

Test Chroma semantic vector storage

• Validates vector-only collections, cosine enforcement, queries, malformed results, isolation, and confirmed deletion.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_vectors_chroma.py

test_semantic_vectors_pg.pyTest pgvector semantic storage +813/-0

Test pgvector semantic storage

• Validates extension requirements, fixed schemas, forced RLS, HNSW queries, dimensions, isolation, and cleanup.

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_vectors_pg.py

test_semantic_composition_invariants.pyProperty-test semantic graph composition +239/-0

Property-test semantic graph composition

• Checks deterministic precedence, deduplication, degree, node, and edge cap invariants.

tldw_Server_API/tests/Notes_Graph/property/test_semantic_composition_invariants.py

test_semantic_publication_invariants.pyProperty-test semantic publication +621/-0

Property-test semantic publication

• Checks generation, manifest, vector, cleanup, and fencing invariants across generated operation sequences.

tldw_Server_API/tests/Notes_Graph/property/test_semantic_publication_invariants.py

test_graph_cache.pyTest semantic graph caching +311/-7

Test semantic graph caching

• Covers semantic query identities, revision separation, invalidation, and ordinary-cache compatibility.

tldw_Server_API/tests/Notes_Graph/unit/test_graph_cache.py

test_graph_service.pyTest semantic graph service helpers +410/-3

Test semantic graph service helpers

• Validates semantic cursor bindings, candidate retrieval, and preservation of legacy graph defaults.

tldw_Server_API/tests/Notes_Graph/unit/test_graph_service.py

test_semantic_capabilities.pyTest semantic capability policy +646/-0

Test semantic capability policy

• Covers deterministic revisions, sanitized disclosures, fail-closed provider and storage checks, and dimensions.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_capabilities.py

test_semantic_content.pyTest deterministic semantic chunking +257/-0

Test deterministic semantic chunking

• Validates normalization, fingerprints, opaque IDs, limits, offsets, and excerpt reconstruction.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_content.py

test_semantic_embeddings.pyTest semantic embedding execution +1078/-0

Test semantic embedding execution

• Covers consent, pinned identity, batching, dimensions, validation, caching, accounting, retries, and cancellation.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_embeddings.py

test_semantic_graph_schema.pyTest semantic graph schemas +263/-0

Test semantic graph schemas

• Validates query controls, edge evidence, status bounds, conversion inputs, and legacy defaults.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_graph_schema.py

test_semantic_indexing.pyTest semantic generation indexing +1342/-0

Test semantic generation indexing

• Covers snapshots, convergence, budgets, note-local failures, dimension resolution, fencing, and activation.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_indexing.py

test_semantic_projector.pyTest semantic graph projection +1243/-0

Test semantic graph projection

• Covers capability gates, vector candidates, ranking, evidence, composition, caching, degradation, and conversion verification.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_projector.py

test_semantic_scoring.pyTest semantic scoring +132/-0

Test semantic scoring

• Validates cosine conversion, thresholds, deterministic Note ranking, and qualitative similarity bands.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_scoring.py

test_semantic_settings.pyTest bounded semantic settings +145/-0

Test bounded semantic settings

• Verifies defaults, hard maxima, cross-field constraints, and supported pgvector dimensions.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_settings.py

test_semantic_store.pyTest semantic persistence operations +0/-0

Test semantic persistence operations

• Covers lifecycle CAS, work claims, manifests, receipts, cleanup, health, and owner isolation.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_store.py

test_semantic_vectors.pyTest the semantic vector facade +0/-0

Test the semantic vector facade

• Validates bindings, vector values, dimensions, query budgets, backend results, and cleanup confirmation.

tldw_Server_API/tests/Notes_Graph/unit/test_semantic_vectors.py

vector_contract.pyAdd shared vector backend contracts +0/-0

Add shared vector backend contracts

• Defines reusable assertions for ChromaDB and pgvector semantic backend behavior.

tldw_Server_API/tests/Notes_Graph/vector_contract.py

test_privilege_introspection.pyTest semantic privilege introspection +0/-0

Test semantic privilege introspection

• Verifies conditional graph rate-limit resources and semantic routes appear in privilege registries.

tldw_Server_API/tests/Privileges/test_privilege_introspection.py

test_lifecycle_worker_catalog.pyTest semantic worker lifecycle registration +0/-0

Test semantic worker lifecycle registration

• Confirms semantic worker and maintenance services use the expected startup and shutdown phases.

tldw_Server_API/tests/Services/test_lifecycle_worker_catalog.py

test_notes_semantic_workers.pyTest semantic workers and maintenance +0/-0

Test semantic workers and maintenance

• Covers worker configuration, runtime execution, bounded maintenance, health sweeps, shutdown, and failures.

tldw_Server_API/tests/Services/test_notes_semantic_workers.py

test_openapi_contracts.pyTest semantic OpenAPI contracts +0/-0

Test semantic OpenAPI contracts

• Validates semantic tags, nested routes, schemas, errors, and operation metadata.

tldw_Server_API/tests/Services/test_openapi_contracts.py

test_startup_study_privilege_jobs_pollers.pyTest semantic service startup gates +0/-0

Test semantic service startup gates

• Verifies environment-controlled registration and invocation of semantic background services.

tldw_Server_API/tests/Services/test_startup_study_privilege_job

[Comment truncated to fit github's 65,536-char limit.]

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (1) 📜 Skill insights (0)

1. Metrics authorization removed ✓ Resolved 🐞 Bug ⛨ Security

Description

Both /metrics and /api/v1/metrics are now registered without RequirePermission(SYSTEM_LOGS).
Unauthenticated callers can retrieve application metrics that were previously restricted to
authorized operators.

Code

tldw_Server_API/app/main.py[R2938-2939]

+        app.add_api_route("/metrics", metrics, include_in_schema=False)
+        app.add_api_route(f"{API_V1_PREFIX}/metrics", api_metrics, methods=["GET"], tags=["monitoring"])

Evidence

The current normal and fallback registrations directly attach the metrics handlers without any
authentication or permission dependency; the related authorization imports are also absent.

tldw_Server_API/app/main.py[2935-2945]
tldw_Server_API/app/main.py[23-66]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The metrics routes were re-registered without their `SYSTEM_LOGS` authorization dependencies, exposing monitoring data publicly.

## Issue Context
Both the normal and route-gating fallback registrations need equivalent protection. Preserve the intended cache policy for the JSON diagnostics route as well.

## Fix Focus Areas
- tldw_Server_API/app/main.py[2935-2945]
- tldw_Server_API/app/main.py[23-66]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Comma-separated edge types rejected ✗ Dismissed 🐞 Bug ≡ Correctness

Description

The graph endpoint now binds NoteGraphRequest directly through Query() without normalizing
comma-separated edge_types. Documented requests such as edge_types=manual,semantic are validated
as one invalid EdgeType value and fail before reaching the handler.

Code

tldw_Server_API/app/api/v1/endpoints/notes_graph.py[R490-491]

async def get_notes_graph(
-    request: Request,
-    req: NoteGraphRequest = Depends(),
+    req: Annotated[NoteGraphRequest, Query()],

Evidence

The handler receives an already validated query model and contains no comma-splitting step.
EdgeType contains individual enum strings only, while the new semantic API documentation sends all
requested edge types in one comma-separated parameter.

tldw_Server_API/app/api/v1/endpoints/notes_graph.py[481-503]
tldw_Server_API/app/api/v1/schemas/notes_graph.py[26-32]
Docs/API/Notes_Semantic_Index.md[275-278]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Direct FastAPI query-model binding does not split comma-separated list values, breaking the documented graph API syntax.

## Issue Context
Support both repeated query parameters and comma-separated values, validating each resulting token as an `EdgeType` before constructing the request model.

## Fix Focus Areas
- tldw_Server_API/app/api/v1/endpoints/notes_graph.py[481-503]
- tldw_Server_API/app/api/v1/schemas/notes_graph.py[26-32]
- Docs/API/Notes_Semantic_Index.md[275-278]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Readiness exposes internal diagnostics ✓ Resolved 🐞 Bug ⛨ Security

Description

/ready and /health/ready are now explicitly public while returning database capacity, workflow
schema, engine workload, provider health, and resource-governor details. Any unauthenticated caller
can inspect sensitive operational state that was previously restricted to operators.

Code

tldw_Server_API/app/main.py[R3155-3156]

+        _add_public_control_plane_route("/ready", readiness_check)
+        _add_public_control_plane_route("/health/ready", readiness_alias)

Evidence

The route helper explicitly declares an empty security requirement and adds no authorization
dependency. The resulting public payload includes database connection and size metrics, schema
versions, workload counts, provider names and failure statistics, and resource-governor metadata.

tldw_Server_API/app/main.py[3088-3098]
tldw_Server_API/app/main.py[3101-3129]
tldw_Server_API/app/main.py[3145-3156]
tldw_Server_API/app/core/Chat/provider_manager.py[311-339]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Detailed readiness projections are exposed through routes explicitly marked as public and without authorization dependencies.

## Issue Context
Keep a minimal, content-free probe public if orchestration requires one, but require the operator permission for the detailed readiness response or remove internal fields from the public payload.

## Fix Focus Areas
- tldw_Server_API/app/main.py[3088-3098]
- tldw_Server_API/app/main.py[3101-3129]
- tldw_Server_API/app/main.py[3145-3156]
- tldw_Server_API/app/core/Chat/provider_manager.py[311-339]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View high (1)

4. Erasure uses closed database ✗ Dismissed 🐞 Bug ≡ Correctness

Description

_build_notes_semantic_erasure_coordinator closes its database before _erase_notes invokes
coordinator.erase(). Data-subject deletion therefore fails instead of erasing the user's semantic
index and canonical Notes data.

Code

tldw_Server_API/app/services/admin_data_subject_requests_service.py[R494-495]

+    finally:
+        db.close_connection()

Evidence

The builder returns a coordinator configured with db and then closes that same database in
finally. The caller invokes erase() only after the builder returns, while the coordinator stores
db.note_semantic_store for its erasure operations.

tldw_Server_API/app/services/admin_data_subject_requests_service.py[482-495]
tldw_Server_API/app/services/admin_data_subject_requests_service.py[523-534]
tldw_Server_API/app/core/Notes_Graph/semantic_erasure.py[190-201]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The DSR coordinator is returned after its underlying Notes database has already been closed, causing the subsequent erasure operation to fail.

## Issue Context
`SemanticErasureCoordinator` retains both the database and its semantic store and is configured to close the database itself on exit.

## Fix Focus Areas
- tldw_Server_API/app/services/admin_data_subject_requests_service.py[482-495]
- tldw_Server_API/app/services/admin_data_subject_requests_service.py[523-534]
- tldw_Server_API/app/core/Notes_Graph/semantic_erasure.py[190-201]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. SemanticStatusFacts lacks docstring ✓ Resolved 📘 Rule violation ✧ Quality

Description

The new public SemanticStatusFacts class begins directly with fields and has no class docstring.
Its responsibility and lifecycle or usage constraints are therefore undocumented.

Code

tldw_Server_API/app/core/Notes_Graph/semantic_api.py[R78-80]

+@dataclass(frozen=True, slots=True)
+class SemanticStatusFacts:
+    desired_state: str

Evidence

Rule 224214 requires every new class to have a non-empty docstring as its first body statement. The
first statement under SemanticStatusFacts is the desired_state field annotation.

Rule 224214: Require docstrings for all modules, classes, and functions
tldw_Server_API/app/core/Notes_Graph/semantic_api.py[78-90]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new `SemanticStatusFacts` dataclass has no class docstring.

## Issue Context
Add a meaningful docstring as the first class-body statement describing what facts the class represents and any important usage constraints.

## Fix Focus Areas
- tldw_Server_API/app/core/Notes_Graph/semantic_api.py[78-90]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Test asserts elapsed wall time ✓ Resolved 📘 Rule violation ▣ Testability

Description

The erasure test asserts a minimum real elapsed duration using time.monotonic(), making its
outcome dependent on scheduling and runtime timing. The existing returned_finished assertion
already verifies the intended quiescence behavior deterministically.

Code

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_erasure.py[1205]

+    assert time.monotonic() - started >= 0.25

Evidence

Rule 380653 prohibits tests from depending on real wall-clock timing or scheduler assumptions. This
test sleeps for fixed durations and asserts that at least 0.25 seconds elapsed, despite already
recording whether the backend finished before return.

Rule 380653: Tests must be deterministic and avoid non-deterministic sources
tldw_Server_API/tests/Notes_Graph/integration/test_semantic_erasure.py[1179-1206]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The test relies on real elapsed time to prove backend quiescence.

## Issue Context
Replace the duration assertion and real sleeps with controllable events, an injected clock, or another deterministic synchronization signal. Retain assertions on completion state and observable erasure behavior.

## Fix Focus Areas
- tldw_Server_API/tests/Notes_Graph/integration/test_semantic_erasure.py[1179-1206]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. Pgvector tests have extra markers ✗ Dismissed 📘 Rule violation ▣ Testability

Description

The module applies both integration and the unaccepted timeout marker to every test, while
asynchronous tests also add asyncio. Consequently, tests such as
test_pgvector_schema_and_reusable_contract do not have exactly one accepted classification marker.

Code

tldw_Server_API/tests/Notes_Graph/integration/test_semantic_vectors_pg.py[37]

+pytestmark = [pytest.mark.integration, pytest.mark.timeout(60)]

Evidence

Rule 380651 requires exactly one accepted marker for each test. The module-level list assigns
integration and timeout to every test, and the cited asynchronous test additionally has
pytest.mark.asyncio.

Rule 380651: Apply appropriate pytest markers to all tests
tldw_Server_API/tests/Notes_Graph/integration/test_semantic_vectors_pg.py[37-37]
tldw_Server_API/tests/Notes_Graph/integration/test_semantic_vectors_pg.py[138-139]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Tests in this module receive multiple pytest markers rather than exactly one accepted classification marker.

## Issue Context
Retain exactly one of `unit`, `integration`, `external_api`, or `local_llm_service` per test. Express timeout and asynchronous execution through the repository-approved configuration or documented mechanism that does not violate the marker policy.

## Fix Focus Areas
- tldw_Server_API/tests/Notes_Graph/integration/test_semantic_vectors_pg.py[37-37]
- tldw_Server_API/tests/Notes_Graph/integration/test_semantic_vectors_pg.py[138-139]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (6)

8. Readiness responses become cacheable ✓ Resolved 🐞 Bug ☼ Reliability

Description

The rewritten readiness handler returns success and failure responses without `Cache-Control:
no-store`. Proxies and clients may cache a stale 200 or 503 response, causing traffic to continue
reaching an unhealthy instance or keeping a recovered instance out of service.

Code

tldw_Server_API/app/main.py[3129]

+        return JSONResponse(body, status_code=(200 if ready else 503))

Evidence

The normal readiness return, shutdown return, and exception return construct JSONResponse objects
without cache-control headers; the liveness handler similarly returns a plain dictionary.

tldw_Server_API/app/main.py[3022-3030]
tldw_Server_API/app/main.py[3129-3137]
tldw_Server_API/app/main.py[2956-2984]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
All branches of the readiness handler now omit explicit cache-prevention headers, allowing health state to become stale in intermediary caches.

## Issue Context
Apply `Cache-Control: no-store` consistently to successful, draining, and dependency-failure responses. The public liveness response should retain the same policy.

## Fix Focus Areas
- tldw_Server_API/app/main.py[3022-3030]
- tldw_Server_API/app/main.py[3129-3137]
- tldw_Server_API/app/main.py[2956-2984]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

9. Configured log level ignored ✓ Resolved 🐞 Bug ◔ Observability

Description

Startup now hardcodes Loguru to DEBUG, ignoring the documented LOG_LEVEL setting. Production
deployments configured for INFO, WARNING, or ERROR will emit verbose debug logs, increasing
log volume and exposing debug-only operational details.

Code

tldw_Server_API/app/main.py[769]

+_log_level = "DEBUG"

Evidence

The startup configuration assigns the constant DEBUG, while the operations documentation defines
LOG_LEVEL as the application logging-level control.

tldw_Server_API/app/main.py[766-770]
Docs/Operations/Env_Vars.md[21-24]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The application logging sink is always configured at DEBUG and no longer honors `LOG_LEVEL`.

## Issue Context
Restore validated environment-based log-level normalization with a safe default rather than using a constant.

## Fix Focus Areas
- tldw_Server_API/app/main.py[766-770]
- Docs/Operations/Env_Vars.md[21-24]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

10. Endpoint performs conversion logic ✓ Resolved 📘 Rule violation ⌂ Architecture

Description

create_manual_link constructs semantic domain services, validates conversions, and overrides
relationship properties inside the route handler. This business workflow belongs in the core Notes
Graph feature module.

Code

tldw_Server_API/app/api/v1/endpoints/notes_graph.py[R768-771]

+            try:
+                await projector.validate_conversion(
+                    source_note_id=from_note_id,
+                    target_note_id=to_note_id,

Evidence

Rule 224213 requires business workflows and decisions to reside in core feature modules. The changed
endpoint constructs NoteGraphService and SemanticGraphProjector, calls domain validation, and
forces directed and weight values itself.

Rule 224213: Place new business logic in core feature modules, not in endpoints or schemas
tldw_Server_API/app/api/v1/endpoints/notes_graph.py[747-777]
tldw_Server_API/app/core/Notes_Graph/semantic_projector.py[301-309]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The API endpoint implements semantic conversion validation and state decisions instead of delegating them to the Notes Graph core layer.

## Issue Context
The endpoint should parse the request, invoke a core use case, and translate its result into an HTTP response. Service construction, conversion validation, and relationship-property decisions should be encapsulated in the core feature.

## Fix Focus Areas
- tldw_Server_API/app/api/v1/endpoints/notes_graph.py[747-777]
- tldw_Server_API/app/core/Notes_Graph/semantic_projector.py[301-309]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

11. SQLite connection remains open ✓ Resolved 📘 Rule violation ☼ Reliability

Description

The migration test creates an owned in-memory SQLite connection without a context manager or a
finally block that closes it. The handle remains open for the rest of the test process.

Code

tldw_Server_API/tests/AuthNZ_Unit/test_notes_graph_semantic_permissions.py[R64-66]

+def test_migration_096_grants_semantic_management_to_approved_roles() -> None:
+    conn = sqlite3.connect(":memory:")
+    _create_rbac_schema(conn)

Evidence

Rule 224222 requires an owned database handle to be managed in the same function or explicitly
closed in finally. The test opens conn at line 65 and uses it through its assertions without any
closing path.

Rule 224222: Use context managers for DB connections/transactions and close owned handles
tldw_Server_API/tests/AuthNZ_Unit/test_notes_graph_semantic_permissions.py[64-72]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The test-owned SQLite connection is never closed.

## Issue Context
Manage the connection with an appropriate closing context or close it in a `finally` block so cleanup also occurs when migration execution or assertions fail.

## Fix Focus Areas
- tldw_Server_API/tests/AuthNZ_Unit/test_notes_graph_semantic_permissions.py[64-72]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

12. SemanticAPIError defined locally ✓ Resolved 📘 Rule violation ⌂ Architecture

Description

The PR defines the custom SemanticAPIError exception in a Notes Graph feature module rather than
the centralized core exceptions module. This fragments the application's exception hierarchy and
import conventions.

Code

tldw_Server_API/app/core/Notes_Graph/semantic_api.py[R68-69]

+class SemanticAPIError(RuntimeError):
+    """Stable HTTP-facing semantic application error."""

Evidence

Rule 224217 requires new custom exceptions, including subclasses of built-in exceptions, to be
defined in /app/core/exceptions.py. SemanticAPIError is newly defined as a RuntimeError
subclass in app/core/Notes_Graph/semantic_api.py.

Rule 224217: Centralize custom exceptions in core module
tldw_Server_API/app/core/Notes_Graph/semantic_api.py[68-75]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`SemanticAPIError` is a custom application exception defined outside the centralized core exceptions module.

## Issue Context
Move the exception definition to `app/core/exceptions.py` and update semantic API imports and consumers accordingly. Review sibling semantic custom errors introduced by this feature for the same requirement.

## Fix Focus Areas
- tldw_Server_API/app/core/Notes_Graph/semantic_api.py[68-75]
- tldw_Server_API/app/core/exceptions.py[1-1]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

13. Audit warning lacks context 📘 Rule violation ◔ Observability

Description

The semantic conversion audit failure is logged without structured operation or correlation
identifiers, even though actor, dataset, source note, target note, and generation identifiers are
available. The warning also omits the exception stack trace.

Code

tldw_Server_API/app/api/v1/endpoints/notes_graph.py[R822-823]

+            except Exception:  # noqa: BLE001 - the link is already authoritative.
+                logger.warning("Notes semantic conversion audit emission failed")

Evidence

Rule 380623 requires error-condition warnings to include structured operation and correlation
context and requires exception logs to retain stack traces. The new broad catch emits only a static
warning despite relevant identifiers being in scope.

Rule 380623: Include contextual data in error logs with loguru
tldw_Server_API/app/api/v1/endpoints/notes_graph.py[812-823]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The semantic conversion audit failure warning lacks structured identifiers and exception information.

## Issue Context
The surrounding scope contains actor, dataset, source-note, target-note, and generation identifiers. Preserve the non-authoritative audit behavior while emitting an actionable Loguru exception record.

## Fix Focus Areas
- tldw_Server_API/app/api/v1/endpoints/notes_graph.py[812-823]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 74 rules

Review mode: ⚖️ Balanced

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗