feat(intelligence): add snapshot impact query

[hardikuppal04]

Summary

Adds a bounded, evidence-backed impact query over a single sealed ri.v1 snapshot. It lets an authenticated repository owner ask both “what depends on this node?” and “what does this node depend on?” without reading a working tree or a parallel parser.

Linked issue

Closes #173

Roadmap alignment

• Roadmap §23 workstream this advances: snapshot-graph evolution and impact reads (the W3 intelligence lane described by feat(intelligence): impact / blast-radius query over the snapshot graph #173 and its linked work).
• §28 market-fit criterion this moves toward: evidence-backed change-impact decisions over inherited services.
• Accepted evidence it is real (test/usage/repo state, not intent): persisted sealed-snapshot traversal is covered by API, authorization, cycle, duplicate-heavy cap, migration, OpenAPI, and full-backend tests. Partner-repository usefulness validation remains part of the separate evolution spike work.

What changed

• Added GET /intelligence/v1/snapshots/{snapshot_id}/impact with owner-scoped authentication, validated nodeKey and depth 1..10, and separate dependent/dependency results.
• Implemented deterministic breadth-first traversal of stored, resolved imports and depends_on edges only. Every returned hop includes the existing edge evidence and derivation.
• Bounded each direction to 100 reached nodes and exposes limitReached so an incomplete response is never presented as exhaustive. The SQL query selects one canonical edge per reached node before applying that cap.
• Added directional snapshot-edge indexes and an Alembic migration, with upgrade/downgrade coverage.
• Added API, OpenAPI, migration, and documentation coverage; updated README limitations to distinguish one-snapshot impact from unavailable cross-revision comparison/churn/trend analysis.

Acceptance criteria completed

• Known nodes return direct and transitive dependents/dependencies at requested depths with stored provenance.
• Cycles terminate; depth is capped; unknown nodes, missing snapshots, and cross-owner snapshots return the standard owner-safe errors.
• Backend coverage includes direct/transitive traversal, cycles, depth boundaries, authentication, owner scoping, structural-edge exclusion, deterministic repeat reads, and the duplicate-heavy result-cap regression.
• OpenAPI response inventory and Repository Intelligence documentation are updated.

Testing performed

# Post-hardening focused API/OpenAPI/migration checks
C:\Users\uppal\PARTHA\PARTHA\apps\backend\.venv\Scripts\python.exe -m pytest tests/test_intelligence_query_api.py tests/test_openapi_contract.py tests/test_migrations.py --basetemp C:\Users\uppal\PARTHA\PARTHA-173-impact-query\.pytest-173-focused-hardened
28 passed, 111 warnings

# Post-hardening full backend suite, run from this worktree with the repository's existing backend virtual environment
C:\Users\uppal\PARTHA\PARTHA\apps\backend\.venv\Scripts\python.exe -m pytest --basetemp C:\Users\uppal\PARTHA\PARTHA-173-impact-query\.pytest-173-final-venv
708 passed, 5 skipped, 930 warnings

# Earlier targeted neighbouring checks
C:\Users\uppal\PARTHA\PARTHA\apps\backend\.venv\Scripts\python.exe -m pytest tests/test_snapshot_persistence.py tests/intelligence/test_resolution.py
43 passed, 1 warning

# Repository Intelligence benchmark
C:\Users\uppal\PARTHA\PARTHA\apps\backend\.venv\Scripts\python.exe tests/benchmark/run.py --report-dir <workspace-local temporary directory>
Passed: 23 fixtures; citation/extraction validity, determinism, parity, precision, and recall passed

# Frontend checks
npm.cmd run lint:frontend
Passed
npm.cmd --prefix apps/frontend run test
176/176 passed
npm.cmd run build:frontend
Passed

# Docker checks
npm.cmd run docker:config
Not run successfully: Docker is not installed in this local environment.

# Note
npm.cmd run test:backend was attempted in the new worktree, but its wrapper could not find pytest because this worktree has no local apps/backend/.venv. The same suite was then run successfully above using the repository's existing backend virtual environment while the working directory remained this branch's apps/backend directory.

Screenshots

Not applicable — this PR adds a backend read API and documentation only.

Security and data considerations

The route remains behind the existing authenticated intelligence router and resolves snapshots through the owner-scoped accessor; cross-owner and missing snapshots are both 404. Inputs have length/depth bounds, traversal has a per-direction result limit, and it returns persisted snapshot facts and existing provenance only. No source-file reads, credentials, secrets, logs of repository contents, or runtime dependency changes are introduced. The migration adds only read-performance indexes and is covered in both directions.

Dependencies and blocked work

None. This is independent of snapshot-to-snapshot comparison (#172) and the two-revision evolution spike (#219).

Scope changes or remaining work

The API intentionally reports only one sealed snapshot's resolved import/dependency facts. It does not infer unresolved relationships, compare revisions, detect churn, or provide historical trends. limitReached explicitly signals when the bounded response is not exhaustive.

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
• This PR advances a §23 workstream toward a §28 market-fit criterion (Roadmap alignment filled)
• 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]

Approved. Solid implementation of #173: bounded, cycle-safe, provenance-backed impact query over persisted ri.v1 edges, owner-scoped, with migration + tests. Matches the agreed contract.