mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/078-snapshot-restore.rispec.md

@@ -0,0 +1,128 @@
+# RISE-078: Snapshot Restore
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/078-snapshot-restore.rispec.md
+
+## Creative Intent
+
+Any snapshot becomes a recovery point — the developer can rewind the workspace to any captured state with a single command. Whether undoing the last edit or reverting an entire sequence of changes, restore operations are safe, documented, and themselves reversible. The agent's workspace becomes a timeline the developer can scrub backward through.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no snapshot system, so no restore capability exists
+- Reverting agent changes requires manual `git checkout` per file or `git stash`
+- No way to undo a specific tool call while keeping later changes
+- Partial reverts (restoring specific files) require knowing exactly which files changed
+- Undo operations are not documented in session history — the developer loses context
+- Restoring to a previous state risks overwriting files the developer modified independently
+
+**Desired State:**
+- `restore(hash)` reverts all files to a captured snapshot state with one operation
+- `restore(hash, files)` selectively restores specific files, leaving others untouched
+- A safety snapshot is automatically created before every restore (restore is itself undoable)
+- Restore operations create session messages documenting what was reverted and why
+- `/undo` command provides one-keystroke access to undo the most recent tool execution
+- `/revert <messageId>` restores to the state before a specific message's tool calls began
+
+## Desired Outcome Definition
+
+The agent edits `src/api.ts`, `src/db.ts`, and `tests/api.test.ts`. The developer likes the API changes but not the database changes. They run `/undo` to revert the last edit (restoring `tests/api.test.ts`), then selectively restore `src/db.ts` from the session-start snapshot. The API changes remain. A message in the session records what was restored.
+
+## Natural Language Functional Description
+
+### Restore Operations
+
+**Full Restore** — `restore(hash: string)`
+1. Create a safety snapshot of the current state (so the restore itself can be undone).
+2. Read the tree object at the given hash from the snapshot repository.
+3. For each file in the tree: overwrite the working copy with the snapshot version.
+4. For files present in the working copy but not in the snapshot: leave them (don't delete new files unless explicitly requested).
+5. Record a restore event in the session.
+
+**Selective Restore** — `restore(hash: string, files: string[])`
+1. Create a safety snapshot of the current state.
+2. For each specified file: read its content from the snapshot tree and overwrite the working copy.
+3. Files not in the `files` array are left untouched.
+4. Record which files were restored in the session.
+
+### Safety Snapshot
+
+Every restore operation begins by capturing a new snapshot of the current state. This means:
+- Restoring to snapshot A creates snapshot B (current state before restore)
+- If the developer doesn't like the restore, they can restore to snapshot B to get back
+- Restore chains are always reversible — no state is ever permanently lost
+
+### Commands
+
+**`/undo`** — Undo the most recent file-modifying tool execution.
+1. Find the most recent snapshot in the session's snapshot index.
+2. Restore all files to that snapshot's state.
+3. Display: "Restored {n} files to state before {tool call description}."
+
+**`/revert <messageId>`** — Revert to the state before a specific message.
+1. Look up the first snapshot associated with the given message ID.
+2. Restore all files to that snapshot's state.
+3. Display: "Restored to state before message #{messageId}."
+
+**`/revert session`** — Revert to session start.
+1. Restore all files to snapshot #0 (the initial session snapshot).
+2. Display: "Restored all files to session start state."
+
+### Restore Respect for Gitignore
+
+Restore operations respect the project's `.gitignore`:
+- Files listed in `.gitignore` are not restored (they were likely excluded from snapshots too)
+- `node_modules/`, build outputs, and other ignored directories are never touched
+- This prevents restore from overwriting environment-specific files
+
+### Restore Notification
+
+Every restore produces a structured session message:
+
+```typescript
+interface RestoreMessage {
+  type: "restore";
+  snapshotHash: string;
+  filesRestored: string[];
+  filesSkipped: string[];    // gitignored or binary files
+  diff: FileDiff[];          // what actually changed
+  description: string;       // human-readable summary
+}
+```
+
+Example output:
+```
+✓ Restored 3 files to state before file_edit on src/db.ts
+  - src/db.ts (reverted 12 lines)
+  - src/models/user.ts (reverted 5 lines)
+  - tests/db.test.ts (reverted 8 lines)
+```
+
+### Edge Cases
+
+- **File deleted since snapshot:** Restore recreates the file from the snapshot.
+- **File created since snapshot:** Restore does not delete it (conservative approach). User can explicitly request deletion.
+- **File modified by developer AND agent:** Restore overwrites with snapshot state. The safety snapshot preserves the developer's version if needed.
+- **Empty diff:** If restoring would change nothing (current state matches snapshot), skip and notify: "Already at requested state."
+
+## Supporting Structures
+
+- **Snapshot System (RISE-076)** provides the snapshots that restore operations target
+- **Snapshot Diff (RISE-077)** shows what a restore will change before executing
+- **Session Persistence (RISE-018)** records restore events in session history
+- **Permission System (RISE-074)** may require permission for restore operations (they modify files)
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Quick Undo:**
+The agent edits `src/auth.ts` and introduces a regression. The developer immediately types `/undo`. mia-code restores `src/auth.ts` to its pre-edit state in under a second. The session records the undo. The developer asks the agent to try a different approach.
+
+**Scenario 2 — Selective File Restore:**
+After a 10-tool-call session, the developer is happy with most changes but wants to revert `config.yml` to its original state. They restore just that file from the session-start snapshot. All other modifications remain intact.
+
+**Scenario 3 — Undo the Undo:**
+The developer runs `/undo`, then realizes the original change was actually correct. They run `/undo` again — which restores to the safety snapshot created before the first undo, effectively re-applying the original change. Every restore is reversible.
+
+**Scenario 4 — Revert to Pre-Message State:**
+The agent's response to message #5 made sweeping changes across 8 files. The developer wants to undo everything from that message but keep changes from messages #1-4. They run `/revert 5`, which restores to the snapshot captured before message #5's first tool call.

package/rispecs/borrowed_from_opencode/079-worktree-branch-naming.rispec.md

@@ -0,0 +1,122 @@
+# RISE-079: Worktree Branch Naming
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/079-worktree-branch-naming.rispec.md
+
+## Creative Intent
+
+Agent-created worktrees get memorable, human-readable names that feel natural in conversation and git logs. Instead of UUIDs or timestamps, branches like `mia-code/swift-falcon` and `mia-code/calm-brook` give each workspace a distinct identity — easy to reference, easy to remember, easy to discuss with teammates.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no worktree management, so no branch naming convention exists
+- Developer-created branches typically follow patterns like `feature/ticket-123` or `fix/bug-description`
+- Agent-generated identifiers tend toward UUIDs or timestamps — functional but inhuman
+- No collision detection mechanism exists for programmatically generated branch names
+- No configurable prefix for namespacing agent branches from developer branches
+- Branch cleanup after worktree removal is manual
+
+**Desired State:**
+- Worktree branches follow a `{prefix}/{adjective}-{noun}` pattern that is immediately recognizable
+- Curated word pools ensure names are positive, professional, and easy to pronounce
+- Collision detection tries alternative pairs before falling back to numeric suffixes
+- The prefix is configurable (default `mia-code/`) to support team conventions
+- Branch lifecycle is tied to worktree lifecycle — branch is deleted when worktree is removed
+- Names work well in conversation: "check the swift-falcon branch" is natural
+
+## Desired Outcome Definition
+
+The agent creates a worktree. The naming system randomly selects "swift" from the adjective pool and "falcon" from the noun pool. It verifies no branch `mia-code/swift-falcon` exists and no directory `.mia-code/worktrees/swift-falcon/` exists. The worktree is created with branch `mia-code/swift-falcon`. In git log, the branch is immediately identifiable as agent-created and distinguishable from developer branches.
+
+## Natural Language Functional Description
+
+### Naming Pattern
+
+Branch names follow the pattern: `{prefix}{adjective}-{noun}`
+
+- **Default prefix:** `mia-code/`
+- **Separator:** hyphen between adjective and noun
+- **Examples:** `mia-code/swift-falcon`, `mia-code/calm-brook`, `mia-code/bright-cedar`
+
+### Adjective Pool
+
+Approximately 50 positive, professional adjectives:
+
+```
+swift, bright, calm, clear, crisp, deep, fair, fast, fine, firm,
+glad, keen, kind, lean, mild, neat, pure, rich, sage, warm,
+wise, bold, cool, deft, dry, apt, free, full, good, hale,
+just, live, new, open, peak, rare, safe, slim, soft, sure,
+tall, tidy, trim, true, vast, wry, able, avid, brave, fresh
+```
+
+### Noun Pool
+
+Approximately 50 nature and animal nouns:
+
+```
+brook, cedar, crane, dawn, eagle, flame, grove, hawk, jade, lake,
+maple, north, oak, peak, quail, ridge, sage, tide, vale, wave,
+wolf, ash, bay, birch, cliff, cove, dune, elm, fern, finch,
+frost, glade, heron, iris, ivy, knoll, lark, marsh, moss, nest,
+otter, pine, plum, reef, robin, shore, stone, swift, thorn, wren
+```
+
+### Name Generation Algorithm
+
+Generate a random adjective-noun pair. Check for collisions (existing branch via `git branch --list`, existing directory, existing worktree). If collision detected, retry with a new random pair (up to 10 attempts). After 10 failures, append an incrementing counter: `mia-code/swift-falcon-2`. With two pools of 50, collision probability is 1/2500 per attempt — practically impossible even with dozens of active worktrees.
+
+### Configuration
+
+The branch prefix is configurable in `mia-code.json`:
+
+```json
+{
+  "worktree": {
+    "branchPrefix": "mia-code/",
+    "nameFormat": "adjective-noun"
+  }
+}
+```
+
+Teams can customize the prefix to match their conventions (e.g., `ai/`, `agent/`, `auto/`).
+
+### Branch Lifecycle
+
+- **Creation:** branch created with `git checkout -b {name}` during worktree setup
+- **Active:** branch tracks all commits made within the worktree
+- **Removal:** branch deleted with `git branch -D {name}` when worktree is removed
+- **Pruning:** `git worktree prune` cleans stale references after removal
+- **Protection:** branches with unmerged commits trigger a warning before deletion
+
+### Display
+
+When listing worktrees, names are displayed with their creation time and status:
+
+```
+Active worktrees:
+  ● swift-falcon  (created 2h ago, 3 commits ahead)
+  ● calm-brook    (created 1d ago, 1 commit ahead)
+  ○ deep-ridge    (created 3d ago, merged)
+```
+
+## Supporting Structures
+
+- **Git Worktree Management (RISE-075)** uses this naming system when creating worktrees
+- **Session Persistence (RISE-018)** records which worktree names are associated with which sessions
+- **Multi-Level Config (RISE-064)** provides the `worktree.branchPrefix` configuration
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Natural Conversation:**
+Developer: "What's on the swift-falcon branch?" Agent: "In swift-falcon, I implemented the caching optimization — 3 files changed, all tests passing." The name is memorable enough that both human and agent can reference it naturally.
+
+**Scenario 2 — Team Visibility:**
+A team runs `git branch -a` and sees `mia-code/calm-brook` alongside `feature/auth-redesign`. The prefix immediately identifies it as agent-created. The adjective-noun format distinguishes it from other agent branches without needing to check metadata.
+
+**Scenario 3 — Multiple Active Worktrees:**
+An agent creates three worktrees for parallel exploration. The names — `swift-falcon`, `calm-brook`, `bright-cedar` — are distinct and memorable. The developer can say "merge bright-cedar" without looking up UUIDs or timestamps.
+
+**Scenario 4 — Collision Handling:**
+In a long-running project, `swift-falcon` already exists from a previous session. The naming system detects the collision, generates a new pair `keen-maple`, and creates the worktree with that name. No manual intervention needed.

package/rispecs/borrowed_from_opencode/080-sqlite-storage.rispec.md

@@ -0,0 +1,134 @@
+# RISE-080: SQLite Storage Layer
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/080-sqlite-storage.rispec.md
+
+## Creative Intent
+
+mia-code's persistence moves from fragile JSON file I/O to a proper database — SQLite provides transactional integrity, concurrent access safety, query capabilities, and efficient partial updates. The developer's session data, configuration cache, and project metadata live in a single reliable database file that never corrupts on concurrent writes and never rewrites 10MB of JSON to update one message.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code stores sessions in `~/.mia-code-sessions.json` — a single JSON file holding all session data
+- Every write operation serializes the entire sessions object and overwrites the file
+- Concurrent access (multiple mia-code instances) risks data corruption or loss
+- No query capability — finding sessions by project, date, or model requires loading and scanning everything
+- File size grows unbounded as sessions accumulate — reads become slow
+- No transactional guarantees — a crash mid-write can corrupt the entire file
+- Schema changes require migrating JSON manually with no versioning
+
+**Desired State:**
+- SQLite database (`~/.mia-code/data.db`) replaces JSON files as the primary storage layer
+- Normalized tables (sessions, messages, parts) enable efficient queries and partial updates
+- WAL mode allows concurrent reads from multiple instances without blocking
+- Single connection per instance with proper locking prevents corruption
+- Queries filter, sort, and join data without loading everything into memory
+- Schema is versioned with migrations — evolves safely over time
+- File permissions (0o600) protect sensitive session data
+
+## Desired Outcome Definition
+
+mia-code starts and opens `~/.mia-code/data.db`. On first run, it creates the database with the base schema. If `~/.mia-code-sessions.json` exists, it imports existing sessions (one-time migration). Subsequent operations — creating sessions, appending messages, querying by project — use SQL queries. Two mia-code instances running simultaneously both read and write safely via WAL mode.
+
+## Natural Language Functional Description
+
+### Database Location
+
+The database file lives at `~/.mia-code/data.db`. The directory is created if it doesn't exist. File permissions are set to `0o600` (owner read/write only) to protect session data that may contain code snippets, file contents, and conversation history.
+
+### Schema
+
+Core tables:
+
+```sql
+CREATE TABLE sessions (
+  id TEXT PRIMARY KEY,
+  project_root TEXT NOT NULL,
+  model TEXT,
+  provider TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  title TEXT,
+  summary TEXT,
+  message_count INTEGER DEFAULT 0,
+  cost_total REAL DEFAULT 0
+);
+
+CREATE TABLE messages (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  role TEXT NOT NULL,          -- 'user' | 'assistant' | 'system'
+  content TEXT,
+  created_at INTEGER NOT NULL,
+  token_input INTEGER,
+  token_output INTEGER,
+  cost REAL,
+  model TEXT,
+  tool_calls TEXT              -- JSON array of tool call objects
+);
+
+CREATE TABLE parts (
+  id TEXT PRIMARY KEY,
+  message_id TEXT NOT NULL REFERENCES messages(id),
+  type TEXT NOT NULL,          -- 'text' | 'tool_call' | 'tool_result'
+  content TEXT NOT NULL,       -- JSON content
+  sequence INTEGER NOT NULL
+);
+
+CREATE TABLE projects (
+  root TEXT PRIMARY KEY,
+  name TEXT,
+  last_session_id TEXT,
+  last_accessed INTEGER
+);
+
+CREATE TABLE config_cache (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  source TEXT NOT NULL,        -- 'global' | 'project' | 'env'
+  cached_at INTEGER NOT NULL
+);
+
+CREATE INDEX idx_messages_session ON messages(session_id, created_at);
+CREATE INDEX idx_parts_message ON parts(message_id, sequence);
+CREATE INDEX idx_sessions_project ON sessions(project_root, updated_at);
+```
+
+### Query Layer
+
+Queries use `better-sqlite3` with TypeScript type definitions mirroring table columns for compile-time safety. Prepared statements with parameterized queries prevent SQL injection.
+
+### Connection Management
+
+One database connection per mia-code instance. WAL mode (`PRAGMA journal_mode=WAL`) enables concurrent reads without blocking. Writes are serialized. Busy timeout: 5 seconds (`PRAGMA busy_timeout=5000`). Connection closed on process exit via shutdown hook.
+
+### Benefits Over JSON
+
+Concurrent access safety (WAL vs. file race), partial updates (single row vs. full rewrite), query capabilities (SQL WHERE vs. load-and-filter), ACID transactions, and scalability to GB+ without degradation.
+
+### Database Creation
+
+On first access: ensure `~/.mia-code/` exists, open connection (creates file if missing), enable WAL mode and busy timeout, apply pending migrations, connection ready.
+
+## Supporting Structures
+
+- **Database Migrations (RISE-081)** manages schema versioning and evolution
+- **Database Transactions (RISE-082)** provides atomic multi-operation guarantees
+- **Deferred Effects (RISE-083)** ensures side effects only execute after successful commits
+- **Session Persistence (RISE-018)** moves from JSON storage to SQLite queries
+- **Managed Config Directory (RISE-070)** manages the `~/.mia-code/` directory where the database lives
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Fast Session Lookup:**
+A developer has 500 sessions across 20 projects. They run `mia-code sessions` in a project directory. SQLite queries `SELECT * FROM sessions WHERE project_root = ? ORDER BY updated_at DESC LIMIT 20` — instant results. The JSON approach would have loaded and scanned the entire 50MB file.
+
+**Scenario 2 — Concurrent Instances:**
+Two terminal windows run mia-code in different project directories. Both read and write session data simultaneously. WAL mode ensures reads never block and writes are serialized safely. No data corruption, no lost messages.
+
+**Scenario 3 — Efficient Message Append:**
+The agent generates a 100-message session. Each message is an `INSERT INTO messages` — only the new row is written. The JSON approach would have rewritten the entire file 100 times, each time larger than the last.
+
+**Scenario 4 — Migration from JSON:**
+A developer upgrades mia-code. On first run, the migration system detects `~/.mia-code-sessions.json`, reads it, inserts all sessions and messages into SQLite, and renames the JSON file to `.mia-code-sessions.json.migrated`. All history is preserved. Subsequent runs use SQLite exclusively.

package/rispecs/borrowed_from_opencode/081-database-migrations.rispec.md

@@ -0,0 +1,148 @@
+# RISE-081: Database Migrations
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/081-database-migrations.rispec.md
+
+## Creative Intent
+
+The database schema evolves safely alongside the codebase. Each schema change is captured in a versioned migration that runs exactly once, in order, within a transaction. Developers never face "database out of sync" errors — mia-code auto-applies pending migrations at startup, and the migration from JSON to SQLite is itself just migration #1.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code uses a JSON file with no schema versioning — the structure is implicit in the code
+- Adding a new field to sessions requires updating serialization code and hoping existing files parse correctly
+- No mechanism exists to transform existing data when the schema changes
+- Downgrading mia-code may break storage compatibility with no recovery path
+- The JSON-to-SQLite transition (RISE-080) requires a one-time data transformation with no framework to support it
+- Schema changes across versions are not tracked — users on older versions face silent data issues
+
+**Desired State:**
+- Migrations are ordered files, each with an `up()` function that applies one schema change
+- A `_migrations` table tracks which migrations have been applied and when
+- On startup, mia-code checks the current version and applies any pending migrations in order
+- Each migration runs within a transaction — failure rolls back cleanly, leaving the database in its previous state
+- Migration #1 handles the JSON-to-SQLite import, making the transition a standard migration
+- Migrations are additive — columns are added, not dropped, preserving backward compatibility
+
+## Desired Outcome Definition
+
+A developer updates mia-code from v1.0 to v1.3. Three new migrations exist (004, 005, 006). On startup, mia-code checks `_migrations`, finds the last applied is 003, and runs 004, 005, 006 in order within transactions. Each succeeds and is recorded. The database now has cost tracking columns (004), snapshot tables (005), and a full-text search index (006). The developer notices nothing — it just works.
+
+## Natural Language Functional Description
+
+### Migration Structure
+
+Each migration is a TypeScript module exporting an `up()` function:
+
+```typescript
+// migrations/001_base_tables.ts
+import { Database } from "better-sqlite3";
+
+export const version = 1;
+export const description = "Create base tables for sessions, messages, and parts";
+
+export function up(db: Database): void {
+  db.exec(`
+    CREATE TABLE sessions (
+      id TEXT PRIMARY KEY,
+      project_root TEXT NOT NULL,
+      model TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE TABLE messages (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL REFERENCES sessions(id),
+      role TEXT NOT NULL,
+      content TEXT,
+      created_at INTEGER NOT NULL
+    );
+  `);
+}
+```
+
+### Migration Registry
+
+Migrations are registered in order:
+
+```typescript
+const migrations = [
+  migration_001_base_tables,
+  migration_002_json_import,
+  migration_003_cost_tracking,
+  migration_004_snapshot_tables,
+  migration_005_plugin_state,
+  migration_006_fulltext_search,
+];
+```
+
+### Tracking Table
+
+The `_migrations` table records applied migrations:
+
+```sql
+CREATE TABLE IF NOT EXISTS _migrations (
+  version INTEGER PRIMARY KEY,
+  description TEXT NOT NULL,
+  applied_at INTEGER NOT NULL
+);
+```
+
+### Startup Process
+
+On every startup:
+
+1. Open database connection.
+2. Ensure `_migrations` table exists (bootstrap).
+3. Query: `SELECT MAX(version) FROM _migrations` → current version (or 0 if empty).
+4. Filter migration registry to those with `version > currentVersion`.
+5. For each pending migration, in order:
+   a. Begin transaction.
+   b. Execute `up(db)`.
+   c. Insert into `_migrations`: `{version, description, applied_at: now}`.
+   d. Commit transaction.
+   e. If any step fails: rollback transaction, log error, abort startup.
+6. Log: "Applied {n} migration(s), database at version {latest}."
+
+### Example Migrations
+
+- **001 — Base Tables:** Creates `sessions`, `messages`, `parts`, `projects`, `config_cache` tables.
+- **002 — JSON Import:** Reads `~/.mia-code-sessions.json`, imports into SQLite, renames to `.migrated`.
+- **003 — Cost Tracking:** Adds `cost`, `token_input`, `token_output` columns to messages; `cost_total` to sessions.
+- **004 — Snapshot Tables:** Creates `snapshots` and `snapshot_files` tables (RISE-076).
+- **005 — Plugin State:** Creates `plugin_state` table for cross-session plugin data.
+- **006 — Full-Text Search:** Creates FTS5 virtual table on message content.
+
+### Safety Principles
+
+- **Transactional:** each migration runs in a single transaction — all or nothing.
+- **Ordered:** migrations always apply in version order, never skipping.
+- **Idempotent:** version check prevents re-applying already-applied migrations.
+- **Additive only:** add columns/tables, don't drop them. Use defaults for new columns.
+- **Forward-only:** no `down()` — rollback via database backup, not reverse migrations.
+
+### Error Handling
+
+If a migration fails, the transaction rolls back, the error is logged, and mia-code refuses to start with an outdated schema. Each migration application is logged with version, description, and success/failure status.
+
+## Supporting Structures
+
+- **SQLite Storage (RISE-080)** provides the database that migrations operate on
+- **Database Transactions (RISE-082)** ensures each migration is atomic
+- **Structured Logging (RISE-007)** records migration progress and errors
+- **Managed Config Directory (RISE-070)** manages the `~/.mia-code/` directory containing the database
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Seamless Upgrade:**
+A developer hasn't updated mia-code in 3 months. They install the latest version. On startup, 5 pending migrations apply automatically in 200ms. Their existing sessions, messages, and configuration are preserved and enhanced with new columns. They never know migrations happened.
+
+**Scenario 2 — JSON to SQLite Transition:**
+A long-time user with 200 sessions in JSON upgrades. Migration 002 reads the JSON file, inserts all sessions and messages into SQLite, and archives the JSON. Startup takes 2 seconds for the one-time import. All history is queryable via SQL.
+
+**Scenario 3 — Migration Failure Recovery:**
+Migration 005 fails because the database file is read-only (permissions issue). The transaction rolls back. mia-code logs the error and refuses to start. The developer fixes permissions with `chmod 600 ~/.mia-code/data.db` and restarts — migration applies successfully.
+
+**Scenario 4 — Development Workflow:**
+A contributor adds a new feature requiring a schema change. They create `migration_007_add_tags.ts`, add it to the registry, and test locally. The migration applies on their dev database. PR review includes the migration file. After merge, all users get the migration on next update.

package/rispecs/borrowed_from_opencode/082-database-transactions.rispec.md

@@ -0,0 +1,138 @@
+# RISE-082: Database Transactions
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/082-database-transactions.rispec.md
+
+## Creative Intent
+
+Every multi-step database operation is atomic — either all changes commit or none do. Paired with deferred effects, transactions ensure that the system never publishes events about data that wasn't persisted, never leaves partial session state, and never corrupts the database from a crash mid-operation. The developer's session data maintains perfect consistency.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code writes to JSON by serializing the entire object — no transactional guarantees
+- A crash during JSON write can corrupt the entire sessions file
+- Creating a session and adding its first message are separate operations — failure between them leaves orphaned data
+- Events (if they existed) would fire before data is confirmed persisted
+- No mechanism to group related operations into an atomic unit
+- Concurrent writes from multiple instances can interleave, producing inconsistent state
+
+**Desired State:**
+- Related database operations are grouped in transactions that commit or rollback atomically
+- Side effects (event publishing, notifications) are deferred until after successful commit
+- Nested operations use savepoints for fine-grained control within a larger transaction
+- Read-only transactions provide consistent snapshots without write locks
+- Lock management coordinates cross-process operations when needed
+- A crash at any point during a transaction leaves the database in its pre-transaction state
+
+## Desired Outcome Definition
+
+Creating a new session involves inserting into `sessions`, creating the initial message, updating the `projects` table, and publishing a `session.created` event. All four operations happen within a transaction. If the message insert fails, the session insert is rolled back too. The event only fires after all inserts succeed and the transaction commits. The database is never in a state where a session exists without its initial message.
+
+## Natural Language Functional Description
+
+### Transaction Pattern
+
+The primary transaction API wraps operations in an async callback:
+
+```typescript
+await db.transaction(async (tx) => {
+  // All operations within are atomic
+  await tx.run(
+    "INSERT INTO sessions (id, project_root, created_at, updated_at) VALUES (?, ?, ?, ?)",
+    [id, root, now, now]
+  );
+  
+  await tx.run(
+    "INSERT INTO messages (id, session_id, role, content, created_at) VALUES (?, ?, ?, ?, ?)",
+    [msgId, id, "system", systemPrompt, now]
+  );
+  
+  // Side effects are deferred — only execute after commit
+  tx.effect(() => {
+    Bus.publish("session.created", { id, root });
+  });
+});
+// At this point: both inserts committed, event published
+```
+
+If any operation within the callback throws, the entire transaction is rolled back and the effects are discarded.
+
+### Atomic Guarantees
+
+Within a transaction:
+- **All or nothing:** either every `INSERT`, `UPDATE`, `DELETE` commits, or none do.
+- **Isolation:** concurrent reads see the pre-transaction state until commit.
+- **Durability:** once committed, data survives process crashes (SQLite's WAL guarantees).
+- **Consistency:** foreign key constraints and check constraints are enforced at commit.
+
+### Deferred Effects
+
+Side effects registered with `tx.effect()` are queued during the transaction and executed only after successful commit. See RISE-083 for full details. Key properties:
+
+- Effects execute in registration order.
+- Effects run outside the transaction — they cannot cause rollback.
+- If the transaction rolls back, effects are silently discarded.
+- Common effects: event bus publishing, cache invalidation, file operations.
+
+### Nested Transactions (Savepoints)
+
+For complex operations with sub-operations that may independently fail:
+
+```typescript
+await db.transaction(async (tx) => {
+  await tx.run("INSERT INTO sessions ...");
+  
+  try {
+    await tx.savepoint(async (sp) => {
+      await sp.run("INSERT INTO optional_metadata ...");
+      // If this fails, only the savepoint rolls back
+    });
+  } catch {
+    // Savepoint rolled back, but outer transaction continues
+  }
+  
+  await tx.run("INSERT INTO messages ...");
+  // Session and message commit even if metadata failed
+});
+```
+
+### Read Transactions
+
+`db.read(async (tx) => { ... })` provides consistent reads using SQLite's snapshot isolation — all queries within see the same database state, even if writes occur concurrently. No write lock is acquired.
+
+### Lock Management
+
+`db.lock(key, callback)` provides cross-process coordination using advisory locking. Only one process holds a given lock at a time. Lock timeout is configurable (default 5 seconds).
+
+### Error Handling
+
+If any operation within a transaction throws, the entire transaction rolls back automatically, no effects execute, and the error propagates to the caller. The database remains in its pre-transaction state.
+
+### Common Transaction Patterns
+
+- **Session creation:** INSERT session + INSERT initial message + UPDATE project → effect: publish `session.created`
+- **Message append:** INSERT message + INSERT parts + UPDATE session.updated_at → effect: publish `message.added`
+- **Session deletion:** DELETE parts + DELETE messages + DELETE session → effect: publish `session.deleted`, invalidate cache
+
+## Supporting Structures
+
+- **SQLite Storage (RISE-080)** provides the database connection that transactions operate on
+- **Deferred Effects (RISE-083)** implements the `tx.effect()` mechanism in detail
+- **Database Migrations (RISE-081)** uses transactions to ensure each migration is atomic
+- **Event Bus (RISE-002)** receives events published by deferred effects after commit
+- **Session Persistence (RISE-018)** uses transactions for all session read/write operations
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Crash-Safe Session Creation:**
+mia-code creates a session with 3 related inserts. The process is killed mid-transaction (power failure, OOM kill). On restart, the database is in its pre-transaction state — no orphaned sessions, no partial data. The user starts a new session cleanly.
+
+**Scenario 2 — Event Consistency:**
+A session is created within a transaction. The `session.created` event is deferred. If the message insert fails, the transaction rolls back and the event never fires. No subscriber (UI, logger, plugin) ever learns about a session that doesn't exist in the database.
+
+**Scenario 3 — Concurrent Instance Safety:**
+Two mia-code instances write to the same database. Instance A creates a session while instance B appends a message to a different session. SQLite serializes the writes. Both transactions commit successfully. Neither instance sees partial state from the other.
+
+**Scenario 4 — Graceful Degradation:**
+A plugin's `session.create` hook (RISE-072) throws an error during a transaction's deferred effect. The transaction already committed — session data is safe. The effect error is logged. The plugin is notified of its failure. The user's session is unaffected.