Browse Source
- Consolidate migrations: merge 002/003 into 001_initial with UNIQUE did constraint - Add foreign key: active_identity.activeDid REFERENCES accounts.did ON DELETE RESTRICT - Replace empty string defaults with NULL for proper empty state handling - Implement atomic smart deletion with auto-switch logic in IdentitySwitcherView - Add DAL methods: $getAllAccountDids, $getActiveDid, $setActiveDid, $pickNextAccountDid - Add migration bootstrapping to auto-select first account if none selected - Block deletion of last remaining account with user notification Refs: doc/active-pointer-smart-deletion-pattern.mdpull/188/head
Matthew Raymer
1 week ago
4 changed files with 540 additions and 38 deletions
@ -0,0 +1,370 @@ |
|||
# Engineering Directive v2 — Active Pointer + Smart Deletion Pattern (hardened) |
|||
|
|||
**Author**: Matthew Raymer |
|||
**Date**: 2025-01-27 |
|||
**Status**: 🎯 **ACTIVE** - Production-grade engineering directive for implementing smart deletion patterns |
|||
|
|||
## Overview |
|||
|
|||
This supersedes the previous draft and is **copy-pasteable** for any `<model>`. It keeps UX smooth, guarantees data integrity, and adds production-grade safeguards (bootstrapping, races, soft deletes, bulk ops, and testability). Built on your prior pattern. |
|||
|
|||
## 0) Objectives (non-negotiable) |
|||
|
|||
1. Exactly **one active `<model>`** pointer (or `NULL` during first-run). |
|||
2. **Block deletion** when it would leave **zero** `<models>`. |
|||
3. If deleting the **active** item, **atomically re-point** to a deterministic **next** item **before** delete. |
|||
4. Enforce with **app logic** + **FK `RESTRICT`** (and `ON UPDATE CASCADE` if `ref` can change). |
|||
|
|||
--- |
|||
|
|||
## 1) Schema / Migration (SQLite) |
|||
|
|||
```sql |
|||
-- <timestamp>__active_<model>.sql |
|||
PRAGMA foreign_keys = ON; |
|||
|
|||
-- Stable external key on <models> (e.g., did/slug/uuid) |
|||
-- ALTER TABLE <models> ADD COLUMN ref TEXT UNIQUE NOT NULL; -- if missing |
|||
|
|||
CREATE TABLE IF NOT EXISTS active_<model> ( |
|||
id INTEGER PRIMARY KEY CHECK (id = 1), |
|||
activeRef TEXT UNIQUE, -- allow NULL on first run |
|||
lastUpdated TEXT NOT NULL DEFAULT (datetime('now')), |
|||
FOREIGN KEY (activeRef) REFERENCES <models>(ref) |
|||
ON UPDATE CASCADE |
|||
ON DELETE RESTRICT |
|||
); |
|||
|
|||
-- Seed singleton row (idempotent) |
|||
INSERT INTO active_<model> (id, activeRef) |
|||
SELECT 1, NULL |
|||
WHERE NOT EXISTS (SELECT 1 FROM active_<model> WHERE id = 1); |
|||
``` |
|||
|
|||
**Rules** |
|||
|
|||
* **Never** default `activeRef` to `''`—use `NULL` for "no selection yet". |
|||
* Ensure `PRAGMA foreign_keys = ON` for **every connection**. |
|||
|
|||
--- |
|||
|
|||
## 2) Data Access API (TypeScript) |
|||
|
|||
```ts |
|||
// Required DAL |
|||
async function getAllRefs(): Promise<string[]> { /* SELECT ref FROM <models> ORDER BY created_at, ref */ } |
|||
async function getRefById(id: number): Promise<string> { /* SELECT ref FROM <models> WHERE id=? */ } |
|||
async function getActiveRef(): Promise<string|null> { /* SELECT activeRef FROM active_<model> WHERE id=1 */ } |
|||
async function setActiveRef(ref: string|null): Promise<void> { /* UPDATE active_<model> SET activeRef=?, lastUpdated=datetime('now') WHERE id=1 */ } |
|||
async function deleteById(id: number): Promise<void> { /* DELETE FROM <models> WHERE id=? */ } |
|||
async function countModels(): Promise<number> { /* SELECT COUNT(*) FROM <models> */ } |
|||
|
|||
// Deterministic "next" |
|||
function pickNextRef(all: string[], current?: string): string { |
|||
const sorted = [...all].sort(); |
|||
if (!current) return sorted[0]; |
|||
const i = sorted.indexOf(current); |
|||
return sorted[(i + 1) % sorted.length]; |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## 3) Smart Delete (Atomic, Race-safe) |
|||
|
|||
```ts |
|||
async function smartDeleteModelById(id: number, notify: (m: string) => void) { |
|||
await db.transaction(async trx => { |
|||
const total = await countModels(); |
|||
if (total <= 1) { |
|||
notify("Cannot delete the last item. Keep at least one."); |
|||
throw new Error("blocked:last-item"); |
|||
} |
|||
|
|||
const refToDelete = await getRefById(id); |
|||
const activeRef = await getActiveRef(); |
|||
|
|||
if (activeRef === refToDelete) { |
|||
const all = (await getAllRefs()).filter(r => r !== refToDelete); |
|||
const next = pickNextRef(all, refToDelete); |
|||
await setActiveRef(next); |
|||
notify(`Switched active to ${next} before deletion.`); |
|||
} |
|||
|
|||
await deleteById(id); // RESTRICT prevents orphaning if we forgot to switch |
|||
}); |
|||
|
|||
// Post-tx: emit events / refresh UI |
|||
} |
|||
``` |
|||
|
|||
--- |
|||
|
|||
## 4) Bootstrapping & Repair |
|||
|
|||
```ts |
|||
async function ensureActiveSelected() { |
|||
const active = await getActiveRef(); |
|||
const all = await getAllRefs(); |
|||
if (active === null && all.length > 0) { |
|||
await setActiveRef(pickNextRef(all)); // first stable choice |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Invoke after migrations and after bulk imports. |
|||
|
|||
--- |
|||
|
|||
## 5) Concurrency & Crash Safety |
|||
|
|||
* **Always** wrap "switch → delete" inside a **single transaction**. |
|||
* Treat any FK violation as a **logic regression**; surface telemetry (`fk:restrict`). |
|||
|
|||
--- |
|||
|
|||
## 6) Soft Deletes (if applicable) |
|||
|
|||
If `<models>` uses `deleted_at`: |
|||
|
|||
* Replace `DELETE` with `UPDATE <models> SET deleted_at = datetime('now') WHERE id=?`. |
|||
* Add a **partial uniqueness** strategy for `ref`: |
|||
|
|||
* SQLite workaround: make `ref` unique globally and never reuse; or maintain a shadow `refs` ledger to prevent reuse. |
|||
* Adjust `getAllRefs()` to filter `WHERE deleted_at IS NULL`. |
|||
|
|||
--- |
|||
|
|||
## 7) Bulk Ops & Imports |
|||
|
|||
* For batch deletes: |
|||
|
|||
1. Compute survivors. |
|||
2. If a batch would remove **all** survivors → **refuse**. |
|||
3. If the **active** is included, precompute a deterministic **new active** and set it **once** before deleting. |
|||
* After imports, run `ensureActiveSelected()`. |
|||
|
|||
--- |
|||
|
|||
## 8) Multi-Scope Actives (optional) |
|||
|
|||
To support **one active per workspace/tenant**: |
|||
|
|||
* Replace singleton with scoped pointer: |
|||
|
|||
```sql |
|||
CREATE TABLE active_<model> ( |
|||
scope TEXT NOT NULL, -- e.g., workspace_id |
|||
activeRef TEXT, |
|||
lastUpdated TEXT NOT NULL DEFAULT (datetime('now')), |
|||
PRIMARY KEY (scope), |
|||
FOREIGN KEY (activeRef) REFERENCES <models>(ref) ON UPDATE CASCADE ON DELETE RESTRICT |
|||
); |
|||
``` |
|||
* All APIs gain `scope` parameter; transactions remain unchanged in spirit. |
|||
|
|||
--- |
|||
|
|||
## 9) UX Contract |
|||
|
|||
* Delete confirmation must state: |
|||
|
|||
* Deleting the **active** item will **auto-switch**. |
|||
* Deleting the **last** item is **not allowed**. |
|||
* Keep list ordering aligned with `pickNextRef` strategy for predictability. |
|||
|
|||
--- |
|||
|
|||
## 10) Observability |
|||
|
|||
* Log categories: |
|||
|
|||
* `blocked:last-item` |
|||
* `fk:restrict` |
|||
* `repair:auto-selected-active` |
|||
* `active:switch:pre-delete` |
|||
* Emit metrics counters; attach `<model>` and (if used) `scope`. |
|||
|
|||
--- |
|||
|
|||
## 11) Test Matrix (must pass) |
|||
|
|||
1. **Non-active delete** (≥2): deleted; active unchanged. |
|||
2. **Active delete** (≥2): active switches deterministically, then delete succeeds. |
|||
3. **Last item delete** (==1): blocked with message. |
|||
4. **First-run**: 0 items → `activeRef` stays `NULL`; add first → `ensureActiveSelected()` selects it. |
|||
5. **Ref update** (if allowed): `activeRef` follows via `ON UPDATE CASCADE`. |
|||
6. **Soft delete** mode: filters respected; invariants preserved. |
|||
7. **Bulk delete** that includes active but not all: pre-switch then delete set. |
|||
8. **Foreign keys disabled** (fault injection): tests must fail to surface missing PRAGMA. |
|||
|
|||
--- |
|||
|
|||
## 12) Rollout & Rollback |
|||
|
|||
* **Feature-flag** the new deletion path. |
|||
* Migrations are **idempotent**; ship `ensureActiveSelected()` with them. |
|||
* Keep a pre-migration backup for `<models>` on first rollout. |
|||
* Rollback leaves `active_<model>` table harmlessly present. |
|||
|
|||
--- |
|||
|
|||
## 13) Replace-Me Cheatsheet |
|||
|
|||
* `<model>` → singular (e.g., `project`) |
|||
* `<models>` → plural table (e.g., `projects`) |
|||
* `ref` → stable external key (`did` | `slug` | `uuid`) |
|||
|
|||
--- |
|||
|
|||
**Outcome:** You get **predictable UX**, **atomic state changes**, and **hard integrity guarantees** across single- or multi-scope actives, with clear tests and telemetry to keep it honest. |
|||
|
|||
--- |
|||
|
|||
## TimeSafari Implementation Guide |
|||
|
|||
### Clean Implementation Path (Following Directive) |
|||
|
|||
If implementing this pattern from scratch or reverting to reapply the directive, follow this clean implementation: |
|||
|
|||
#### 1) Schema Implementation |
|||
|
|||
**Initial Migration (001_initial):** |
|||
```sql |
|||
-- Enable foreign key constraints for data integrity |
|||
PRAGMA foreign_keys = ON; |
|||
|
|||
-- Create accounts table with UNIQUE constraint on did |
|||
CREATE TABLE IF NOT EXISTS accounts ( |
|||
id INTEGER PRIMARY KEY AUTOINCREMENT, |
|||
dateCreated TEXT NOT NULL, |
|||
derivationPath TEXT, |
|||
did TEXT NOT NULL UNIQUE, -- UNIQUE constraint for foreign key support |
|||
identityEncrBase64 TEXT, |
|||
mnemonicEncrBase64 TEXT, |
|||
passkeyCredIdHex TEXT, |
|||
publicKeyHex TEXT NOT NULL |
|||
); |
|||
|
|||
-- Create active_identity table with foreign key constraint |
|||
CREATE TABLE IF NOT EXISTS active_identity ( |
|||
id INTEGER PRIMARY KEY CHECK (id = 1), |
|||
activeDid TEXT DEFAULT NULL, -- NULL instead of empty string |
|||
lastUpdated TEXT NOT NULL DEFAULT (datetime('now')), |
|||
FOREIGN KEY (activeDid) REFERENCES accounts(did) ON DELETE RESTRICT |
|||
); |
|||
|
|||
-- Seed singleton row |
|||
INSERT INTO active_identity (id, activeDid, lastUpdated) VALUES (1, NULL, datetime('now')); |
|||
``` |
|||
|
|||
#### 2) Data Access API Implementation |
|||
|
|||
**Add to PlatformServiceMixin.ts:** |
|||
```typescript |
|||
// Required DAL methods following the pattern |
|||
async $getAllAccountDids(): Promise<string[]> { |
|||
const result = await this.$dbQuery("SELECT did FROM accounts ORDER BY dateCreated, did"); |
|||
return result?.values?.map(row => row[0] as string) || []; |
|||
} |
|||
|
|||
async $getAccountDidById(id: number): Promise<string> { |
|||
const result = await this.$dbQuery("SELECT did FROM accounts WHERE id = ?", [id]); |
|||
return result?.values?.[0]?.[0] as string; |
|||
} |
|||
|
|||
async $getActiveDid(): Promise<string | null> { |
|||
const result = await this.$dbQuery("SELECT activeDid FROM active_identity WHERE id = 1"); |
|||
return result?.values?.[0]?.[0] as string || null; |
|||
} |
|||
|
|||
async $setActiveDid(did: string | null): Promise<void> { |
|||
await this.$dbExec( |
|||
"UPDATE active_identity SET activeDid = ?, lastUpdated = datetime('now') WHERE id = 1", |
|||
[did] |
|||
); |
|||
} |
|||
|
|||
async $countAccounts(): Promise<number> { |
|||
const result = await this.$dbQuery("SELECT COUNT(*) FROM accounts"); |
|||
return result?.values?.[0]?.[0] as number || 0; |
|||
} |
|||
|
|||
// Deterministic "next" picker |
|||
$pickNextAccountDid(all: string[], current?: string): string { |
|||
const sorted = [...all].sort(); |
|||
if (!current) return sorted[0]; |
|||
const i = sorted.indexOf(current); |
|||
return sorted[(i + 1) % sorted.length]; |
|||
} |
|||
``` |
|||
|
|||
#### 3) Smart Deletion Implementation |
|||
|
|||
**Replace deleteAccount in IdentitySwitcherView.vue:** |
|||
```typescript |
|||
async smartDeleteAccount(id: string) { |
|||
await this.$withTransaction(async () => { |
|||
const total = await this.$countAccounts(); |
|||
if (total <= 1) { |
|||
this.notify.warning("Cannot delete the last account. Keep at least one."); |
|||
throw new Error("blocked:last-item"); |
|||
} |
|||
|
|||
const accountDid = await this.$getAccountDidById(parseInt(id)); |
|||
const activeDid = await this.$getActiveDid(); |
|||
|
|||
if (activeDid === accountDid) { |
|||
const allDids = await this.$getAllAccountDids(); |
|||
const nextDid = this.$pickNextAccountDid(allDids.filter(d => d !== accountDid), accountDid); |
|||
await this.$setActiveDid(nextDid); |
|||
this.notify.success(`Switched active to ${nextDid} before deletion.`); |
|||
} |
|||
|
|||
await this.$exec("DELETE FROM accounts WHERE id = ?", [id]); |
|||
}); |
|||
|
|||
// Update UI |
|||
this.otherIdentities = this.otherIdentities.filter(ident => ident.id !== id); |
|||
} |
|||
``` |
|||
|
|||
#### 4) Bootstrapping Implementation |
|||
|
|||
**Add to PlatformServiceMixin.ts:** |
|||
```typescript |
|||
async $ensureActiveSelected() { |
|||
const active = await this.$getActiveDid(); |
|||
const all = await this.$getAllAccountDids(); |
|||
if (active === null && all.length > 0) { |
|||
await this.$setActiveDid(this.$pickNextAccountDid(all)); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
**Call after migrations:** |
|||
```typescript |
|||
// In migration completion or app startup |
|||
await this.$ensureActiveSelected(); |
|||
``` |
|||
|
|||
### Implementation Benefits |
|||
|
|||
**Following this clean path provides:** |
|||
- ✅ **Atomic Operations**: Transaction-safe account deletion |
|||
- ✅ **Last Account Protection**: Prevents deletion of final account |
|||
- ✅ **Smart Switching**: Auto-switches active account before deletion |
|||
- ✅ **Data Integrity**: Foreign key constraints prevent orphaned references |
|||
- ✅ **Deterministic Behavior**: Predictable "next account" selection |
|||
- ✅ **NULL Handling**: Proper empty state management |
|||
|
|||
### Migration Strategy |
|||
|
|||
**For Existing Databases:** |
|||
1. **Revert** current foreign key implementation |
|||
2. **Apply** clean migration sequence above |
|||
3. **Convert** existing `activeDid = ''` to `NULL` |
|||
4. **Implement** smart deletion logic |
|||
5. **Test** all scenarios from test matrix |
|||
|
|||
This clean implementation follows the directive exactly and provides **complete pattern compliance** with **production-grade safeguards**. |
|||
Loading…
Reference in new issue