specs/003-knowledge-delete-guardrails/data-model.md

# Data Model: Knowledge Source Deletion Guardrails

No new persisted entities or backend schema changes. This feature only adds client-side derived values computed from existing `orchestrationApi` types (`src/services/orchestrationApi.ts`).

## Existing entities reused (unchanged)

- **`ApiDocument`** (`orchestrationApi.ts:60`-ish): `{ id, filename, file_type, file_size, status, created_at, ... }` — a document knowledge source.
- **`DatabaseClient`**: `{ id, name, db_type, status, ... }` — a database knowledge source.
- **`DataBindItem`** (`orchestrationApi.ts:150`): `{ id, name, group_type: "document" | "database", type }` — a reference from an `Analysis` to a bound knowledge source.
- **`Analysis`** (`orchestrationApi.ts:157`): `{ id, analysis_title, objective, business_questions, status: "active" | "inactive" | string, data_bind: DataBindItem[], data_bind_version, ... }`. `status` is **not** modified by this feature (see Clarifications in spec.md).

## New client-side derived values (not persisted, not sent to the backend)

### `DeletionImpactSummary`

Computed at delete-intent time in `KnowledgeManagement.tsx`, before the confirmation dialog opens.

| Field | Type | Description |
|---|---|---|
| `sourceIds` | `string[]` | The knowledge source id(s) about to be deleted (one for single delete, many for "clear all"). |
| `affectedAnalyses` | `{ id: string; analysis_title: string }[]` | Analyses whose `data_bind` contains at least one of `sourceIds`, deduplicated by analysis id. Derived by fetching `listAnalyses()` and filtering `analysis.data_bind.some(item => sourceIds.includes(item.id))`. |

**Lifecycle**: Computed fresh each time a delete action is initiated; discarded when the dialog closes (confirm or cancel). Never persisted.

### Analysis usability flag (`isUnusable`)

**Reused, not newly computed**: `AnalysisShell.tsx` already maintains `staleSources: DataBindItem[]` (state at `AnalysisShell.tsx:80`, computed in the `useEffect` at `AnalysisShell.tsx:117-138`) by cross-referencing `activeAnalysis.data_bind` against live `getDocuments`/`getDatabaseClients` results — this is exactly the "unusable" derivation this feature needs, built for feature 002's stale-sources banner. This feature derives from it rather than re-implementing it:

```
isActiveAnalysisUnusable: boolean = staleSources.length > 0
```

- Any single missing bound source is sufficient to mark the whole analysis unusable (per spec Assumptions / Acceptance Scenario US3.6) — already true of `staleSources`'s existing filter logic.
- This is a pure, stateless derivation — not stored on the `Analysis` object returned by the API, and never written back via `updateAnalysis`/`UpdateAnalysisPayload`.
- Recomputed on-demand (page load / analysis selection), not via a live subscription (per research.md Unknown 3 and the plan's Constraints) — matching `staleSources`'s existing recompute trigger (the `activeAnalysis`-keyed effect).

**State transitions**: `isActiveAnalysisUnusable` has no explicit transition function in this feature — it is a pure function of current data. It can only become `true` when a bound source is deleted (User Story 1 → 3). Per clarification, this feature has **no** transition back to `false`: once `staleSources.length > 0`, the update-bound-data action (including the pre-existing "Update binding" control that would normally clear `staleSources`) is itself disabled by this feature (FR-011/FR-014), so there is no in-app path to restore usability.

## Validation rule: analysis name uniqueness

Enforced client-side in `NewAnalysisDialog.tsx` before calling `createAnalysis()`:

```
isDuplicateName(candidate: string, existing: Analysis[]): boolean =
  existing.some(a => a.analysis_title.trim().toLowerCase() === candidate.trim().toLowerCase())
```

- Requires the dialog to have access to the current analysis list (already loaded by the parent `AnalysisShell.tsx` as `analyses` state) — passed down as a new prop, or fetched via `listAnalyses()` if the dialog is opened without it in scope.
- This is a client-side guard only; per FR-007/FR-008 no backend contract change is assumed to exist, so this check does not guarantee uniqueness under concurrent creation from two sessions (acceptable per spec — no server-side uniqueness constraint was requested).