marvisx-cli 0.1.0__py3-none-any.whl

migrations/133_brain_v1_2_direction_schema_down.sql

@@ -0,0 +1,273 @@
+-- Migration 133 DOWN: Revert Brain v1.2 Direction Integration schema
+-- Date: 2026-05-18
+--
+-- WARNING: Down migration may lose data if production rows used new enum
+-- values (direction_drift / direction_bootstrap finding_type, DR8 rule_id,
+-- direction_misalignment signal_type, pending_bootstrap / applied
+-- approval_state). The down script will REMOVE such rows before swap.
+
+PRAGMA foreign_keys = OFF;
+
+BEGIN IMMEDIATE;
+
+-- =============================================================================
+-- 1. Drop new tables
+-- =============================================================================
+DROP TABLE IF EXISTS direction_changelog;
+DROP TRIGGER IF EXISTS trg_project_directions_updated_at;
+DROP TABLE IF EXISTS project_directions;
+
+-- =============================================================================
+-- 2. Revert brain_findings (remove new enum values + new columns)
+-- =============================================================================
+
+-- Remove rows that depend on new enum values (data loss accepted on rollback)
+DELETE FROM brain_findings
+ WHERE finding_type IN ('direction_drift', 'direction_bootstrap')
+    OR approval_state IN ('pending_bootstrap', 'applied');
+
+DROP TRIGGER IF EXISTS trg_brain_findings_updated_at;
+DROP TRIGGER IF EXISTS trg_brain_findings_no_delete_resolved;
+DROP TRIGGER IF EXISTS trg_brain_findings_terminal_forward_only;
+
+DROP INDEX IF EXISTS uk_brain_findings_natural;
+DROP INDEX IF EXISTS idx_brain_findings_scope_cycle;
+DROP INDEX IF EXISTS idx_brain_findings_open;
+DROP INDEX IF EXISTS idx_brain_findings_fingerprint;
+DROP INDEX IF EXISTS idx_brain_findings_type_cycle;
+DROP INDEX IF EXISTS idx_brain_findings_run;
+DROP INDEX IF EXISTS idx_brain_findings_regression;
+DROP INDEX IF EXISTS idx_brain_findings_entity_open;
+DROP INDEX IF EXISTS idx_brain_findings_urgency;
+
+CREATE TABLE brain_findings_old (
+    finding_id                  TEXT PRIMARY KEY,
+    run_id                      TEXT NOT NULL,
+    cycle_key                   TEXT NOT NULL,
+    detected_at                 TEXT NOT NULL
+                                CHECK(detected_at LIKE '%Z' OR detected_at LIKE '%+00:00'),
+    finding_type                TEXT NOT NULL
+                                CHECK(finding_type IN (
+                                    'idea','task_candidate','open_question',
+                                    'scope_gap','procedure_change','contradiction'
+                                )),
+    schema_version              INTEGER NOT NULL DEFAULT 1,
+    scope_type                  TEXT NOT NULL
+                                CHECK(scope_type IN ('company','program','project','artifact')),
+    scope_key                   TEXT NOT NULL,
+    program_key                 TEXT,
+    title                       TEXT NOT NULL CHECK(length(title) <= 200),
+    summary                     TEXT NOT NULL CHECK(length(summary) <= 2000),
+    why_now                     TEXT NOT NULL CHECK(length(why_now) <= 500),
+    evidence_hash               TEXT NOT NULL CHECK(length(evidence_hash) = 64),
+    involved_projects_json      TEXT NOT NULL DEFAULT '[]' CHECK(json_valid(involved_projects_json)),
+    suggested_artifact          TEXT NOT NULL
+                                CHECK(suggested_artifact IN (
+                                    'task','adr','guide','learning','status_update','question','none'
+                                )),
+    owner_hint_json             TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(owner_hint_json)),
+    closure_condition_kind      TEXT NOT NULL
+                                CHECK(closure_condition_kind IN (
+                                    'drift_signal_clears','memory_op_applied','artifact_exists','manual_attest'
+                                )),
+    closure_condition_json      TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(closure_condition_json)),
+    closure_condition_human     TEXT CHECK(closure_condition_human IS NULL OR length(closure_condition_human) <= 500),
+    severity                    TEXT NOT NULL CHECK(severity IN ('low','medium','high','critical')),
+    confidence                  TEXT NOT NULL CHECK(confidence IN ('low','medium','high')),
+    approval_state              TEXT NOT NULL DEFAULT 'open'
+                                CHECK(approval_state IN ('open','approved','dismissed','resolved','superseded','expired')),
+    regression_of_finding_id    TEXT,
+    proposal_fingerprint        TEXT NOT NULL CHECK(length(proposal_fingerprint) = 32),
+    recurrence_count            INTEGER NOT NULL DEFAULT 1 CHECK(recurrence_count >= 1),
+    first_seen_cycle_key        TEXT NOT NULL,
+    last_seen_cycle_key         TEXT NOT NULL,
+    applied_artifact_ref        TEXT,
+    applied_at                  TEXT,
+    applied_by_user_id          TEXT,
+    expires_at                  TEXT NOT NULL,
+    superseded_by_finding_id    TEXT,
+    created_at                  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    updated_at                  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    FOREIGN KEY (run_id) REFERENCES brain_runs(run_id) ON DELETE RESTRICT,
+    FOREIGN KEY (regression_of_finding_id) REFERENCES brain_findings_old(finding_id) ON DELETE SET NULL,
+    FOREIGN KEY (superseded_by_finding_id) REFERENCES brain_findings_old(finding_id) ON DELETE SET NULL
+);
+
+INSERT INTO brain_findings_old (
+    finding_id, run_id, cycle_key, detected_at, finding_type, schema_version,
+    scope_type, scope_key, program_key, title, summary, why_now, evidence_hash,
+    involved_projects_json, suggested_artifact, owner_hint_json,
+    closure_condition_kind, closure_condition_json, closure_condition_human,
+    severity, confidence, approval_state, regression_of_finding_id,
+    proposal_fingerprint, recurrence_count, first_seen_cycle_key,
+    last_seen_cycle_key, applied_artifact_ref, applied_at, applied_by_user_id,
+    expires_at, superseded_by_finding_id, created_at, updated_at
+)
+SELECT
+    finding_id, run_id, cycle_key, detected_at, finding_type, schema_version,
+    scope_type, scope_key, program_key, title, summary, why_now, evidence_hash,
+    involved_projects_json, suggested_artifact, owner_hint_json,
+    closure_condition_kind, closure_condition_json, closure_condition_human,
+    severity, confidence, approval_state, regression_of_finding_id,
+    proposal_fingerprint, recurrence_count, first_seen_cycle_key,
+    last_seen_cycle_key, applied_artifact_ref, applied_at, applied_by_user_id,
+    expires_at, superseded_by_finding_id, created_at, updated_at
+FROM brain_findings;
+
+DROP TABLE brain_findings;
+ALTER TABLE brain_findings_old RENAME TO brain_findings;
+
+CREATE UNIQUE INDEX uk_brain_findings_natural
+    ON brain_findings(cycle_key, finding_type, scope_type, scope_key, evidence_hash, closure_condition_kind);
+CREATE INDEX idx_brain_findings_scope_cycle
+    ON brain_findings(scope_type, scope_key, cycle_key DESC) WHERE superseded_by_finding_id IS NULL;
+CREATE INDEX idx_brain_findings_open
+    ON brain_findings(approval_state, created_at DESC) WHERE approval_state = 'open';
+CREATE INDEX idx_brain_findings_fingerprint
+    ON brain_findings(proposal_fingerprint, cycle_key DESC);
+CREATE INDEX idx_brain_findings_type_cycle
+    ON brain_findings(finding_type, cycle_key DESC);
+CREATE INDEX idx_brain_findings_run
+    ON brain_findings(run_id);
+CREATE INDEX idx_brain_findings_regression
+    ON brain_findings(regression_of_finding_id) WHERE regression_of_finding_id IS NOT NULL;
+
+CREATE TRIGGER trg_brain_findings_updated_at
+    AFTER UPDATE ON brain_findings FOR EACH ROW WHEN NEW.updated_at = OLD.updated_at
+BEGIN
+    UPDATE brain_findings SET updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE finding_id = NEW.finding_id;
+END;
+CREATE TRIGGER trg_brain_findings_no_delete_resolved
+    BEFORE DELETE ON brain_findings FOR EACH ROW WHEN OLD.approval_state = 'resolved'
+BEGIN
+    SELECT RAISE(ABORT, 'cannot delete resolved finding');
+END;
+CREATE TRIGGER trg_brain_findings_terminal_forward_only
+    BEFORE UPDATE OF approval_state ON brain_findings FOR EACH ROW
+    WHEN OLD.approval_state IN ('dismissed','resolved','expired') AND NEW.approval_state <> OLD.approval_state
+BEGIN
+    SELECT RAISE(ABORT, 'terminal finding state is forward-only');
+END;
+
+-- =============================================================================
+-- 2b. Revert brain_finding_states to_state CHECK
+-- =============================================================================
+
+DELETE FROM brain_finding_states WHERE to_state IN ('pending_bootstrap', 'applied');
+
+DROP INDEX IF EXISTS idx_brain_findings_states_finding;
+DROP INDEX IF EXISTS idx_brain_findings_states_actor;
+
+CREATE TABLE brain_finding_states_old (
+    state_id              TEXT PRIMARY KEY,
+    finding_id            TEXT NOT NULL,
+    from_state            TEXT,
+    to_state              TEXT NOT NULL
+                          CHECK(to_state IN ('open','approved','dismissed','resolved','superseded','expired')),
+    actor_user_id         TEXT,
+    reason                TEXT CHECK(reason IS NULL OR length(reason) <= 500),
+    applied_artifact_ref  TEXT,
+    created_at            TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    FOREIGN KEY (finding_id) REFERENCES brain_findings(finding_id) ON DELETE RESTRICT
+);
+
+INSERT INTO brain_finding_states_old SELECT * FROM brain_finding_states;
+DROP TABLE brain_finding_states;
+ALTER TABLE brain_finding_states_old RENAME TO brain_finding_states;
+
+CREATE INDEX idx_brain_findings_states_finding ON brain_finding_states(finding_id, created_at DESC);
+CREATE INDEX idx_brain_findings_states_actor ON brain_finding_states(actor_user_id, created_at DESC);
+
+-- =============================================================================
+-- 3. Revert brain_drift_signals (remove DR8 + direction_misalignment)
+-- =============================================================================
+
+DELETE FROM brain_drift_signals
+ WHERE rule_id = 'DR8' OR signal_type = 'direction_misalignment';
+
+DROP TRIGGER IF EXISTS trg_brain_drift_signals_updated_at;
+DROP INDEX IF EXISTS idx_brain_drift_signals_scope_cycle;
+DROP INDEX IF EXISTS idx_brain_drift_signals_scope_type;
+DROP INDEX IF EXISTS idx_brain_drift_signals_type_cycle;
+DROP INDEX IF EXISTS idx_brain_drift_signals_observed_ref;
+DROP INDEX IF EXISTS idx_brain_drift_signals_run;
+DROP INDEX IF EXISTS idx_brain_drift_signals_recurrence;
+DROP INDEX IF EXISTS idx_brain_drift_signals_open_severity;
+DROP INDEX IF EXISTS idx_brain_drift_signals_lookback;
+DROP INDEX IF EXISTS idx_brain_drift_signals_axis;
+
+CREATE TABLE brain_drift_signals_old (
+    signal_id                   TEXT PRIMARY KEY,
+    run_id                      TEXT NOT NULL,
+    cycle_key                   TEXT NOT NULL,
+    detected_at                 TEXT NOT NULL CHECK(detected_at LIKE '%Z' OR detected_at LIKE '%+00:00'),
+    rule_id                     TEXT NOT NULL CHECK(rule_id IN ('DR1','DR2','DR3','DR4','DR5','DR6','DR7')),
+    schema_version              INTEGER NOT NULL DEFAULT 1,
+    scope_type                  TEXT NOT NULL CHECK(scope_type IN ('company','program','project')),
+    scope_key                   TEXT NOT NULL,
+    program_key                 TEXT,
+    signal_type                 TEXT NOT NULL
+                                CHECK(signal_type IN (
+                                    'activity_without_status','decision_without_adr','playbook_changed',
+                                    'stale_open_loop','docs_governance_drift','external_update_unpropagated',
+                                    'claimed_decision_gap'
+                                )),
+    knowledge_form              TEXT NOT NULL
+                                CHECK(knowledge_form IN ('adr','spec','playbook','tribal_memory','external_update','claimed_decision','unknown')),
+    classifier_version          INTEGER NOT NULL DEFAULT 1,
+    expected_direction_source   TEXT NOT NULL
+                                CHECK(expected_direction_source IN (
+                                    'journal','project_status','handoff','doc','brainstorm','meeting_transcript','none','task','pr','commit'
+                                )),
+    expected_direction_ref      TEXT,
+    observed_direction_ref      TEXT NOT NULL,
+    observed_delta              TEXT NOT NULL CHECK(length(observed_delta) <= 2000),
+    evidence_json               TEXT NOT NULL DEFAULT '[]' CHECK(json_valid(evidence_json)),
+    evidence_hash               TEXT NOT NULL CHECK(length(evidence_hash) = 64),
+    severity                    TEXT NOT NULL CHECK(severity IN ('low','medium','high','critical')),
+    confidence                  REAL NOT NULL CHECK(confidence BETWEEN 0.0 AND 1.0 AND confidence = confidence),
+    recurrence_key              TEXT NOT NULL,
+    involved_projects_json      TEXT NOT NULL DEFAULT '[]' CHECK(json_valid(involved_projects_json)),
+    state                       TEXT NOT NULL DEFAULT 'open' CHECK(state IN ('open','superseded','resolved','dismissed')),
+    superseded_by_signal_id     TEXT,
+    resolved_at                 TEXT,
+    dismissed_at                TEXT,
+    dismissed_by                TEXT,
+    dismiss_reason              TEXT,
+    drift_axis                  TEXT CHECK(drift_axis IS NULL OR drift_axis IN ('intent','context','both')),
+    created_at                  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    updated_at                  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+    FOREIGN KEY (run_id) REFERENCES brain_runs(run_id) ON DELETE RESTRICT,
+    FOREIGN KEY (superseded_by_signal_id) REFERENCES brain_drift_signals_old(signal_id)
+);
+
+INSERT INTO brain_drift_signals_old SELECT * FROM brain_drift_signals;
+DROP TABLE brain_drift_signals;
+ALTER TABLE brain_drift_signals_old RENAME TO brain_drift_signals;
+
+CREATE INDEX idx_brain_drift_signals_scope_cycle ON brain_drift_signals(scope_type, scope_key, cycle_key DESC);
+CREATE INDEX idx_brain_drift_signals_scope_type ON brain_drift_signals(scope_type, scope_key, cycle_key DESC, signal_type);
+CREATE INDEX idx_brain_drift_signals_type_cycle ON brain_drift_signals(signal_type, cycle_key DESC);
+CREATE INDEX idx_brain_drift_signals_observed_ref ON brain_drift_signals(observed_direction_ref, signal_type, cycle_key DESC);
+CREATE INDEX idx_brain_drift_signals_run ON brain_drift_signals(run_id);
+CREATE INDEX idx_brain_drift_signals_recurrence ON brain_drift_signals(recurrence_key, cycle_key DESC);
+CREATE INDEX idx_brain_drift_signals_open_severity ON brain_drift_signals(severity, cycle_key DESC)
+    WHERE state = 'open' AND superseded_by_signal_id IS NULL;
+CREATE INDEX idx_brain_drift_signals_lookback ON brain_drift_signals(scope_type, scope_key, signal_type, resolved_at)
+    WHERE resolved_at IS NULL AND state = 'open';
+CREATE INDEX idx_brain_drift_signals_axis ON brain_drift_signals(cycle_key, drift_axis) WHERE drift_axis IS NOT NULL;
+
+CREATE TRIGGER trg_brain_drift_signals_updated_at
+    AFTER UPDATE ON brain_drift_signals FOR EACH ROW WHEN NEW.updated_at = OLD.updated_at
+BEGIN
+    UPDATE brain_drift_signals SET updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE signal_id = NEW.signal_id;
+END;
+
+-- =============================================================================
+-- 4. Remove schema_versions entry
+-- =============================================================================
+DELETE FROM schema_versions WHERE version = 133;
+
+COMMIT;
+
+PRAGMA foreign_keys = ON;

migrations/134_brain_journal_narrative_polished.sql

@@ -0,0 +1,8 @@
+-- Wave 3.1 Gap 2: persist LLM-polished narrative on journal entries.
+-- Polished after cycle publish when settings.brain_llm_polish_enabled=1
+-- and the entry is non-empty (is_empty=0). NULL when polish disabled or LLM
+-- unavailable; deterministic body_json always present as fallback.
+
+ALTER TABLE brain_journal_entries ADD COLUMN narrative_polished TEXT;
+ALTER TABLE brain_journal_entries ADD COLUMN narrative_polished_at TEXT;
+ALTER TABLE brain_journal_entries ADD COLUMN narrative_polished_model TEXT;

migrations/134_brain_journal_narrative_polished_down.sql

@@ -0,0 +1,6 @@
+-- Down migration: drop narrative_polished columns. SQLite ALTER TABLE DROP
+-- COLUMN requires 3.35+; the runtime is 3.45+ so we use it directly.
+
+ALTER TABLE brain_journal_entries DROP COLUMN narrative_polished_model;
+ALTER TABLE brain_journal_entries DROP COLUMN narrative_polished_at;
+ALTER TABLE brain_journal_entries DROP COLUMN narrative_polished;

migrations/135_kg_edges_provider.sql

@@ -0,0 +1,21 @@
+-- Migration 135 — KG edge provider tracking
+--
+-- Adds a nullable provider field for newly written KG edges. The live KG edge
+-- table is named `graph_edges`; this migration keeps the task wording
+-- `kg_edges_provider` in the filename for traceability.
+--
+-- No retroactive backfill is performed in this migration. Legacy `similar_to`
+-- rows stay NULL until they are naturally recomputed by the populator during
+-- the transition window.
+--
+-- Idempotency note:
+-- SQLite does not support `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`. The
+-- guarded column add and index creation run in the version-135 post-migration
+-- hook in `core/api/db.py`. This SQL file only reserves/stamps the version so
+-- startup migration ordering remains deterministic.
+
+BEGIN IMMEDIATE;
+
+INSERT OR IGNORE INTO schema_versions(version) VALUES (135);
+
+COMMIT;

migrations/136_documents_fts.sql

@@ -0,0 +1,56 @@
+-- Migration 136 — documents_fts for W2 hybrid retrieval
+--
+-- Adds an FTS5 index over the semantic-search documents table so
+-- embedding_service.search_by_type can fuse sqlite-vec KNN with BM25 over
+-- handoffs, files, audits, learnings, tasks, inbox items, and projects.
+--
+-- We intentionally keep the FTS table content-owned instead of
+-- content='documents': the live documents table has doc_title/file_path but
+-- no title/content body columns, and an external-content FTS5 table with
+-- non-existent source columns breaks ordinary reads and rebuilds. The Python
+-- migration post-hook backfills full file/row bodies where possible.
+
+BEGIN IMMEDIATE;
+
+CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5(
+    doc_id UNINDEXED,
+    title,
+    content,
+    tokenize='porter unicode61 remove_diacritics 2'
+);
+
+-- SQL-only fallback backfill. The migration runner post-hook replaces these
+-- lightweight rows with full readable body text for loadable documents.
+INSERT INTO documents_fts(rowid, doc_id, title, content)
+SELECT d.id, d.id, d.file_path, d.file_path
+FROM documents AS d
+WHERE NOT EXISTS (
+    SELECT 1
+    FROM documents_fts AS f
+    WHERE f.rowid = d.id
+);
+
+DROP TRIGGER IF EXISTS documents_fts_insert;
+CREATE TRIGGER documents_fts_insert AFTER INSERT ON documents
+BEGIN
+    INSERT INTO documents_fts(rowid, doc_id, title, content)
+    VALUES (NEW.id, NEW.id, NEW.file_path, NEW.file_path);
+END;
+
+DROP TRIGGER IF EXISTS documents_fts_update;
+CREATE TRIGGER documents_fts_update AFTER UPDATE ON documents
+BEGIN
+    DELETE FROM documents_fts WHERE rowid = OLD.id;
+    INSERT INTO documents_fts(rowid, doc_id, title, content)
+    VALUES (NEW.id, NEW.id, NEW.file_path, NEW.file_path);
+END;
+
+DROP TRIGGER IF EXISTS documents_fts_delete;
+CREATE TRIGGER documents_fts_delete AFTER DELETE ON documents
+BEGIN
+    DELETE FROM documents_fts WHERE rowid = OLD.id;
+END;
+
+COMMIT;
+
+INSERT OR IGNORE INTO schema_versions (version) VALUES (136);

migrations/137_promote_llm_costs.sql

@@ -0,0 +1,59 @@
+-- v1.0.0 - 2026-04-30 - Promote llm_costs from lazy-create to formal migration
+--
+-- Until now `llm_costs` was lazy-created by inbox_llm_classifier._ensure_llm_costs_table().
+-- That helper shipped the table only after the classifier path had been exercised at
+-- least once, leaving fresh DB bootstrap + integration tests + Triage onboarding
+-- without the table. Promote to a formal migration so every environment has the
+-- schema from boot.
+--
+-- The schema preserves the existing column types already in production rows
+-- (id TEXT, created_at TEXT ISO8601). Three new nullable columns are added for
+-- MAC-Phase 0.5 LiteLLM gateway:
+--
+--   - tier_logical TEXT          : logical model name (tier-think|tier-fast|...) or NULL for legacy.
+--   - fallback_used INTEGER      : 0/1 flag, set when LiteLLM falls back from local Mac to cloud.
+--   - litellm_request_id TEXT    : LiteLLM correlation id, for cross-DB debug
+--                                  (Hetzner llm_costs ↔ Mac LiteLLM_SpendLogs).
+--
+-- WARNING: NEVER add prompt or response columns to llm_costs. PII / GDPR Art. 32
+-- violation. Plain-text prompts/responses must live only in rotated file logs
+-- with pii_redactor applied (retention <= 7 days, chmod 600).
+--
+-- Idempotency strategy:
+--   - This SQL file does the safe-on-rerun parts (CREATE TABLE IF NOT EXISTS,
+--     CREATE INDEX IF NOT EXISTS, schema_versions stamp).
+--   - The post-migration Python hook `_promote_llm_costs_columns()` in api/db.py
+--     handles ALTER TABLE ADD COLUMN for the 3 new columns, guarded by
+--     `_column_exists()` so it is safe on both fresh DBs (where CREATE already
+--     installed them) and prod DBs (where the lazy-created old schema lacked them).
+--
+-- DEPLOY PROCEDURE (auto via run_migrations at startup):
+--   1. Deploy api → /data/pir/migrations/137_promote_llm_costs.sql in place.
+--   2. systemctl --user restart pir-api.service.
+--   3. run_migrations() applies version 137, then runs the post-hook.
+--
+-- Reversible: vedi migrations/137_promote_llm_costs_down.sql (no-op, SQLite
+-- pre-3.35 cannot DROP COLUMN; documented).
+
+BEGIN IMMEDIATE;
+
+CREATE TABLE IF NOT EXISTS llm_costs (
+    id TEXT PRIMARY KEY,
+    feature TEXT NOT NULL,
+    model TEXT,
+    input_tokens INTEGER,
+    output_tokens INTEGER,
+    cost_usd REAL NOT NULL,
+    workspace_id TEXT NOT NULL DEFAULT 'ws_default',
+    created_at TEXT DEFAULT (datetime('now','utc')),
+    tier_logical TEXT,
+    fallback_used INTEGER NOT NULL DEFAULT 0,
+    litellm_request_id TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_llm_costs_feature_created
+    ON llm_costs(feature, created_at, workspace_id);
+
+INSERT OR IGNORE INTO schema_versions (version) VALUES (137);
+
+COMMIT;

migrations/137_promote_llm_costs_down.sql

@@ -0,0 +1,19 @@
+-- Rollback per migration 137 (promote llm_costs).
+--
+-- SQLite pre-3.35 non supporta DROP COLUMN; per rollback canonico delle 3
+-- nuove colonne (tier_logical, fallback_used, litellm_request_id) servirebbe
+-- drop+recreate della tabella. Pero' llm_costs contiene dati operativi
+-- (cost tracking inbox classifier, ~1500 row/mese) e ricrearla rischierebbe
+-- perdita di dati. Per rollback al volo, basta rimuovere il version bump:
+-- le colonne extra restano fisicamente in tabella ma il codice pre-137
+-- semplicemente non le legge ne' scrive (NULL default).
+--
+-- Per rollback completo (drop colonne + ripristino lazy-create), servirebbe
+-- una migration successiva con CREATE TABLE _new + INSERT SELECT + DROP +
+-- RENAME. Non lo facciamo qui — questa down-migration e' "version bump only".
+
+BEGIN IMMEDIATE;
+
+DELETE FROM schema_versions WHERE version = 137;
+
+COMMIT;

migrations/138_ingest_api_keys.sql

@@ -0,0 +1,39 @@
+-- Migration 138: ingestion API-key credential (single-org).
+-- v1.0.0 - 2026-05-26 - M1 CAPTURE U1
+--
+-- Purpose-built credential for the governed ingestion ingress (POST /api/v1/ingest).
+-- NOT an extension of agent_tokens: agent_tokens is load-bearing for the 91-tool
+-- MCP server; a separate table reuses the crypto (SHA-256 hash via security.py)
+-- while isolating the per-source policy (no blast radius on MCP auth).
+--
+-- Convergence with agent_tokens (future M7 merge): same hashing helper,
+-- same revoke-audit shape (revoked_at/by/reason), same expires_at semantics.
+--
+-- Rollback: migrations/138_ingest_api_keys_down.sql
+
+CREATE TABLE IF NOT EXISTS ingest_api_keys (
+    id                 TEXT PRIMARY KEY,                 -- uuid
+    name               TEXT NOT NULL,                    -- human label
+    token_hash         TEXT NOT NULL UNIQUE,             -- SHA-256 hex (reuse security.py _hash_token)
+    prefix             TEXT NOT NULL,                    -- first chars for display (ing_xxxx...)
+    project_scope      TEXT NOT NULL DEFAULT '[]',       -- JSON array of slugs (default-deny)
+    ingest_policy      TEXT NOT NULL DEFAULT 'open'
+                         CHECK(ingest_policy IN ('open', 'trusted')),
+    default_source     TEXT,                             -- label applied when payload omits source
+    rate_limit_per_min INTEGER NOT NULL DEFAULT 60,
+    daily_quota        INTEGER NOT NULL DEFAULT 1000,    -- durable abuse backstop (non-NULL by design)
+    workspace_id       TEXT NOT NULL DEFAULT 'ws_default',
+    created_by         TEXT,                             -- user slug who minted it
+    created_at         TEXT NOT NULL DEFAULT (datetime('now')),
+    expires_at         TEXT,                             -- NULL = no expiry
+    last_used_at       TEXT,
+    is_active          INTEGER NOT NULL DEFAULT 1,
+    revoked_at         TEXT,
+    revoked_by         TEXT,
+    revoke_reason      TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_ingest_api_keys_hash ON ingest_api_keys(token_hash);
+CREATE INDEX IF NOT EXISTS idx_ingest_api_keys_active ON ingest_api_keys(is_active, workspace_id);
+
+INSERT OR IGNORE INTO schema_versions(version) VALUES (138);

migrations/138_ingest_api_keys_down.sql

@@ -0,0 +1,8 @@
+-- Rollback migration 138: drop ingest_api_keys.
+-- v1.0.0 - 2026-05-26 - M1 CAPTURE U1
+
+DROP INDEX IF EXISTS idx_ingest_api_keys_active;
+DROP INDEX IF EXISTS idx_ingest_api_keys_hash;
+DROP TABLE IF EXISTS ingest_api_keys;
+
+DELETE FROM schema_versions WHERE version = 138;

migrations/139_ingest_pending_ingress.sql

@@ -0,0 +1,91 @@
+-- Migration 139: ingress columns + 'api_ingress' source kind on ingest_pending.
+-- v1.0.0 - 2026-05-26 - M1 CAPTURE U2
+--
+-- SQLite cannot alter a CHECK constraint in place, so ingest_pending is rebuilt
+-- (same pattern as mig 126). Three governance columns are added in the same
+-- rebuild (api_key_id, source, ingest_policy) — declared in the new-table DDL,
+-- NOT via separate ALTER ADD COLUMN (a CHECK change forces a full rebuild, so a
+-- standalone ALTER would be dead/conflicting). The ~324 historical rows keep
+-- these columns NULL (owner drops, no API key) — correct, no backfill needed.
+--
+-- api_key_id is bare TEXT by design (no FK): key revocation is a soft-delete
+-- (ingest_api_keys.revoked_at, never a row DELETE), so no dangling reference can
+-- ever occur and no ON DELETE rule is required.
+--
+-- The PRAGMA foreign_keys=OFF envelope (mirrors mig 126) is mandatory: without
+-- it, DROP TABLE ingest_pending cascade-deletes ingest_change_history (FK
+-- ON DELETE CASCADE, mig 097 — the triage audit trail) and NULLs
+-- ingest_skipped.existing_ingest_id (FK, mig 103). Invariant: row counts of
+-- ingest_change_history / ingest_skipped are unchanged across this migration.
+--
+-- Rollback: migrations/139_ingest_pending_ingress_down.sql
+
+PRAGMA foreign_keys=OFF;
+
+BEGIN IMMEDIATE;
+
+CREATE TABLE ingest_pending_new_139 (
+    id TEXT PRIMARY KEY,
+    file_path TEXT NOT NULL,
+    sha256 TEXT NOT NULL,
+    project_slug TEXT NOT NULL DEFAULT 'unclassified',
+    source_kind TEXT NOT NULL DEFAULT 'file_drop' CHECK(source_kind IN (
+        'file_drop', 'manual_upload', 'api_upload', 'terminal_upload', 'api_ingress'
+    )),
+    mime_type TEXT,
+    file_size_bytes INTEGER,
+    parser_used TEXT,
+    extracted_text TEXT,
+    structure_json TEXT,
+    classification_json TEXT,
+    status TEXT NOT NULL DEFAULT 'queued' CHECK(status IN (
+        'queued', 'parser_waiting', 'parsing', 'classified', 'awaiting_triage',
+        'approved', 'inserted', 'done', 'parse_error', 'rejected'
+    )),
+    error_message TEXT,
+    triage_decision_id TEXT,
+    target_folder TEXT,
+    target_filename TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    recovery_attempts INTEGER NOT NULL DEFAULT 0,
+    locked_by TEXT,
+    locked_at TEXT,
+    -- M1 CAPTURE ingress columns (NULL for owner drops):
+    api_key_id TEXT,            -- ingest_api_keys.id (bare TEXT, soft-delete keys → no dangling ref)
+    source TEXT,                -- payload source label (provenance / filtering)
+    ingest_policy TEXT,         -- snapshot of key policy at intake ('open' | 'trusted')
+    UNIQUE(sha256, project_slug)
+);
+
+INSERT INTO ingest_pending_new_139 (
+    id, file_path, sha256, project_slug, source_kind, mime_type,
+    file_size_bytes, parser_used, extracted_text, structure_json,
+    classification_json, status, error_message, triage_decision_id,
+    target_folder, target_filename, created_at, updated_at,
+    recovery_attempts, locked_by, locked_at
+)
+SELECT
+    id, file_path, sha256, project_slug, source_kind, mime_type,
+    file_size_bytes, parser_used, extracted_text, structure_json,
+    classification_json, status, error_message, triage_decision_id,
+    target_folder, target_filename, created_at, updated_at,
+    recovery_attempts, locked_by, locked_at
+FROM ingest_pending;
+
+DROP TABLE ingest_pending;
+ALTER TABLE ingest_pending_new_139 RENAME TO ingest_pending;
+
+CREATE INDEX idx_ingest_pending_status ON ingest_pending(status);
+CREATE INDEX idx_ingest_pending_project ON ingest_pending(project_slug);
+CREATE INDEX idx_ingest_pending_created ON ingest_pending(created_at DESC);
+CREATE INDEX idx_ingest_pending_lock ON ingest_pending(locked_at)
+    WHERE locked_at IS NOT NULL;
+CREATE INDEX idx_ingest_pending_source ON ingest_pending(source);
+CREATE INDEX idx_ingest_pending_api_key ON ingest_pending(api_key_id);
+
+INSERT OR IGNORE INTO schema_versions(version) VALUES (139);
+
+COMMIT;
+
+PRAGMA foreign_keys=ON;

migrations/139_ingest_pending_ingress_down.sql

@@ -0,0 +1,73 @@
+-- Rollback migration 139: drop ingress columns + 'api_ingress' source kind.
+-- v1.0.0 - 2026-05-26 - M1 CAPTURE U2
+--
+-- SQLite cannot drop a CHECK value in place, so this is a reverse full rebuild
+-- back to the pre-139 (mig 126) DDL. Any 'api_ingress' rows are first demoted to
+-- 'file_drop' so they survive the restored CHECK. Same foreign_keys=OFF envelope
+-- as the up migration (protects ingest_change_history / ingest_skipped FKs).
+
+PRAGMA foreign_keys=OFF;
+
+BEGIN IMMEDIATE;
+
+UPDATE ingest_pending SET source_kind = 'file_drop' WHERE source_kind = 'api_ingress';
+
+CREATE TABLE ingest_pending_old_139 (
+    id TEXT PRIMARY KEY,
+    file_path TEXT NOT NULL,
+    sha256 TEXT NOT NULL,
+    project_slug TEXT NOT NULL DEFAULT 'unclassified',
+    source_kind TEXT NOT NULL DEFAULT 'file_drop' CHECK(source_kind IN (
+        'file_drop', 'manual_upload', 'api_upload', 'terminal_upload'
+    )),
+    mime_type TEXT,
+    file_size_bytes INTEGER,
+    parser_used TEXT,
+    extracted_text TEXT,
+    structure_json TEXT,
+    classification_json TEXT,
+    status TEXT NOT NULL DEFAULT 'queued' CHECK(status IN (
+        'queued', 'parser_waiting', 'parsing', 'classified', 'awaiting_triage',
+        'approved', 'inserted', 'done', 'parse_error', 'rejected'
+    )),
+    error_message TEXT,
+    triage_decision_id TEXT,
+    target_folder TEXT,
+    target_filename TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    recovery_attempts INTEGER NOT NULL DEFAULT 0,
+    locked_by TEXT,
+    locked_at TEXT,
+    UNIQUE(sha256, project_slug)
+);
+
+INSERT INTO ingest_pending_old_139 (
+    id, file_path, sha256, project_slug, source_kind, mime_type,
+    file_size_bytes, parser_used, extracted_text, structure_json,
+    classification_json, status, error_message, triage_decision_id,
+    target_folder, target_filename, created_at, updated_at,
+    recovery_attempts, locked_by, locked_at
+)
+SELECT
+    id, file_path, sha256, project_slug, source_kind, mime_type,
+    file_size_bytes, parser_used, extracted_text, structure_json,
+    classification_json, status, error_message, triage_decision_id,
+    target_folder, target_filename, created_at, updated_at,
+    recovery_attempts, locked_by, locked_at
+FROM ingest_pending;
+
+DROP TABLE ingest_pending;
+ALTER TABLE ingest_pending_old_139 RENAME TO ingest_pending;
+
+CREATE INDEX idx_ingest_pending_status ON ingest_pending(status);
+CREATE INDEX idx_ingest_pending_project ON ingest_pending(project_slug);
+CREATE INDEX idx_ingest_pending_created ON ingest_pending(created_at DESC);
+CREATE INDEX idx_ingest_pending_lock ON ingest_pending(locked_at)
+    WHERE locked_at IS NOT NULL;
+
+DELETE FROM schema_versions WHERE version = 139;
+
+COMMIT;
+
+PRAGMA foreign_keys=ON;