# Harden AI Analysis Path PRD

## Goal

Harden the existing elder AI analysis and knowledge retrieval MVP so the critical safety boundaries are covered by tests and the displayed evidence chain matches the citations actually used by the model output.

## Background

The current MVP already implements LangChain-backed elder AI analysis, pgvector-backed knowledge retrieval, permission-scoped resident context, persisted analysis history, and knowledge management UI.

Current evidence from repository inspection:

- AI service files live under `modules/ai/`.
- API routes live under `app/api/ai/`.
- AI tables and vector extension are in `modules/core/server/schema.ts` and `drizzle/0007_purple_puff_adder.sql`.
- Existing project verification passes: `pnpm lint`, `pnpm type-check`, and `pnpm test`.
- No AI-specific test file currently covers schema validation, permission scoping, history redaction, knowledge organization isolation, disabled knowledge exclusion, or provider failure behavior.
- `normalizeCitations` currently appends allowed citations that the model did not necessarily cite, weakening the evidence chain.

## Requirements

1. Add focused automated tests for AI validators, knowledge service behavior, analysis service behavior, and AI route authorization/response behavior.
2. Tighten citation handling so the persisted/rendered `citations` list is derived from citation IDs actually referenced by findings and recommendations.
3. Reject AI outputs whose finding or recommendation `citationIds` include IDs not present in the allowed context/knowledge citation set.
4. Keep failed analysis history sanitized: no full prompt, resident context, API key, or raw provider error.
5. Preserve the existing synchronous generation MVP behavior; do not introduce queues, streaming, background jobs, new dependencies, or a new vector store.
6. Improve user-facing failure text where configuration/vector generation failure would otherwise look like a generic save/generation failure.
7. Clarify `ai:manage` as a reserved/future governance permission instead of implying a currently implemented management surface.

## Acceptance Criteria

- `validateKnowledgeEntryInput`, `validateElderAiAnalysisOutput`, and `parseDataScopes` have direct unit coverage for valid and invalid edge cases.
- Knowledge tests cover writable scope failures, disabled entry exclusion, platform/current-organization visibility, other-organization exclusion, and embedding failure behavior without hitting a real provider.
- Analysis tests cover missing config, provider error, schema validation failure, retrieval degradation, and history redaction without hitting a real provider.
- AI route tests cover missing `ai:read`, missing `elder:read`, missing `knowledge:read`, missing `knowledge:manage`, invalid request body, service failure status propagation, and success audit behavior.
- Citation normalization no longer appends unused allowed citations.
- Any unknown citation ID in findings/recommendations causes a structured schema validation failure and failed history record.
- Knowledge UI and AI analysis dialog keep sensitive details out of failure messages while making configuration/vector-generation failures understandable.
- `ai:manage` permission description no longer overpromises current UI/API capability.
- `pnpm lint`, `pnpm type-check`, `pnpm test`, and `pnpm build` pass.

## Out of Scope

- Async generation jobs.
- Streaming AI responses.
- AI usage billing/rate limiting.
- AI configuration UI.
- File upload/OCR/web crawling knowledge ingestion.
- AI-generated business record drafts or one-click mutations.