refactor(intelligence): bound architecture snapshot reads (#133)

[hardikuppal04]

Summary

Bounds Architecture's sealed-snapshot reads so a large repository does not hydrate unrelated snapshot facts or exceed database parameter limits while loading relationship evidence.

Linked issue

Closes #133

What changed

• Reads only relationship predicates rendered by Architecture, their endpoint nodes, evidence, relevant coverage paths, and the two resolution-diagnostic codes Architecture exposes.
• Batches both evidence-path and node/edge evidence-ID queries at 500 values per SQL query.
• Keeps the Architecture response shape, owner scope, sealed-snapshot selection, and evidence semantics unchanged.
• Adds regressions for irrelevant diagnostics and 501 relevant relationship edges, and updates the Repository Intelligence design documentation.

Acceptance criteria completed

• Architecture reads target only the relationship facts it renders rather than full snapshot node, observation, evidence, or diagnostic inventories. The query has explicit relationship and diagnostic allow-lists.
• Evidence queries remain bounded for large relevant relationship graphs. test_architecture_fact_query_batches_relevant_evidence_ids creates 501 relevant edges and 502 endpoint nodes, asserts complete results, and proves all node/edge evidence queries stay within the 500-ID bound.
• Unrelated diagnostics are not loaded or rendered. test_architecture_fact_query_excludes_irrelevant_large_snapshot_records persists 64 irrelevant parser diagnostics and verifies they are absent from both the query facts and the Architecture response.
• Architecture relationship, diagnostic, coverage, owner-scoping, and sealed-snapshot behavior remain correct. Existing Architecture relationship tests and the full backend suite pass.
• No filesystem reads, public pagination changes, migrations, consumer-specific storage, or hashing changes were introduced. The bounded query contract is documented in REPOSITORY_INTELLIGENCE.md.

Testing performed

C:\Users\uppal\PARTHA\PARTHA\apps\backend\.venv\Scripts\python.exe -m pytest -q --basetemp .test-tmp-regressions tests/test_architecture_relationships.py::test_architecture_fact_query_excludes_irrelevant_large_snapshot_records tests/test_architecture_relationships.py::test_architecture_fact_query_batches_relevant_evidence_ids
2 passed

C:\Users\uppal\PARTHA\PARTHA\apps\backend\.venv\Scripts\python.exe -m pytest -q --basetemp .test-tmp-review tests/test_architecture_relationships.py
5 passed

C:\Users\uppal\PARTHA\PARTHA\apps\backend\.venv\Scripts\python.exe -m pytest -q --basetemp .test-tmp-neighbour tests/test_intelligence_query_api.py tests/test_snapshot_persistence.py
Passed (existing Starlette/httpx deprecation warning)

C:\Users\uppal\PARTHA\PARTHA\apps\backend\.venv\Scripts\python.exe -m pytest -q --basetemp .test-tmp-full-review
664 passed, 5 skipped (exit 0; existing Starlette/httpx, tar extraction, and Alembic configuration deprecation warnings)

C:\Users\uppal\PARTHA\PARTHA\apps\backend\.venv\Scripts\python.exe -m pip check
No broken requirements found.

npm.cmd run test:backend
Could not run from this separate worktree because its local backend `.venv` is absent and the fallback system Python has no pytest. The controlled existing backend virtual-environment command above ran the same suite.

npm.cmd run docker:config
npm.cmd run docker:validate
Unavailable locally because Docker is not installed.

Screenshots

Not applicable; this is an internal backend read-bound and architecture documentation change.

Security and data considerations

Owner scoping and sealed-snapshot semantics are preserved. No authentication boundary, public API schema, migration, secret, logging, or untrusted-input behavior changes.

Dependencies and blocked work

None.

Scope changes or remaining work

None.

Contributor checklist

• This PR targets dev
• I claimed the issue and had it assigned or acknowledged before starting substantial work
• The branch was created from an up-to-date upstream/dev
• The branch is rebased on the latest upstream/dev
• This PR addresses one clearly scoped issue
• Every acceptance criterion I claim as complete is actually complete
• Relevant tests pass
• Documentation is updated for any user-visible change
• No secrets, credentials, local env files, or generated artifacts are included
• No unrelated files were changed
• Closing syntax (Closes) is used only because the issue is fully resolved
• Dependencies and follow-up work are linked

[parthrohit22]

Thanks for the focused change and the strong test/CI coverage. I’m requesting changes because the implementation does not yet fully satisfy #133’s bounded-read contract.

1. Diagnostics are still unbounded. architecture_facts() loads every diagnostic in the sealed snapshot, although Architecture only renders RI-RES-UNRESOLVED and RI-RES-AMBIGUOUS. Large parse-diagnostic inventories therefore remain fully hydrated. Please filter the query to the codes Architecture actually consumes.

2. Evidence loading is not batched. _evidence_for() sends every endpoint-node or relationship-edge ID through one IN (...) query. A large repository can exceed backend parameter limits. The current large-snapshot test creates many irrelevant records but only one relationship, so it does not exercise this failure mode.

Please batch or relationship-scope the evidence query and add regression coverage with enough relevant edges/endpoints to validate the bound.