@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/README.md

@@ -1,258 +1,95 @@
-# @jungjaehoon/mama-core
+# mama-core
 
-Shared memory, provenance, graph, and context substrate for MAMA.
+The shared engine for storage, records and revisions, evidence links, memory, search and native
+runtime drivers. Consumers supply their own database, principals, source access and product
+vocabulary through public exports. Core does not require the MAMA OS daemon.
 
-## What is MAMA Core?
+Version **4.1.0**; Node.js 22.13+. This README describes the current rebuild checkout.
+See [architecture](../../docs/explanation/architecture.md) and
+[the shared-engine goal](../../INTENT.md).
 
-MAMA Core is a shared package containing the fundamental modules used by all MAMA packages:
+## Public API
 
-- **mcp-server**: MCP protocol server
-- **claude-code-plugin**: Claude Code plugin
-- **standalone**: Standalone HTTP server
+[package.json](package.json) defines supported import paths; [src/index.ts](src/index.ts)
+defines root exports. Representative root exports:
 
-This package provides embedding generation, database management, scoped memory, provenance, raw
-evidence refs, graph/entity helpers, and worker context primitives without the transport layer
-(MCP/HTTP).
+| Area      | Root exports                                                                                      |
+| --------- | ------------------------------------------------------------------------------------------------- |
+| Storage   | `createAdapter`, `SQLiteAdapter`, `initDB`, `getDB`, `getAdapter`, `closeDB`                      |
+| Records   | `createKnowledge`, `appendJudgment`, `ingestSource`                                               |
+| Memory    | `mama`, `createMamaApi`, `saveMemory`, `recallMemory`, `ingestConversation`, `MEMORY_KINDS`       |
+| Search    | `generateEmbedding`, `generateEnhancedEmbedding`, `cosineSimilarity`, `EmbeddingCache`            |
+| Evidence  | `getMemoryProvenance`, `resolveMemoryProvenance`, `insertTwinEdge`, `listVisibleTwinEdgesForRefs` |
+| Execution | `createCatalog`, `createDispatcher`, `createClient`, `startRuntime`, `createActionIpcServer`      |
+| Traces    | `beginModelRun`, `commitModelRun`, `appendToolTrace`, `listToolTracesForRun`                      |
 
-## Installation
+Every public subpath below is relative to `@jungjaehoon/mama-core`:
 
-```bash
-npm install @jungjaehoon/mama-core
-# or
-pnpm add @jungjaehoon/mama-core
-```
+| Area                  | Export paths                                                                                                                       |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Root                  | `.`                                                                                                                                |
+| Memory and storage    | `./embeddings`, `./memory/types`, `./db-manager`, `./mama-api`                                                                     |
+| Helpers               | `./relevance-scorer`, `./debug-logger`, `./decision-formatter`, `./errors`, `./canonicalize`                                       |
+| Evidence and records  | `./connectors`, `./connectors/event-index`, `./connectors/raw-query`, `./provenance/source-ref`, `./registry/store`, `./knowledge` |
+| Actions               | `./operations/owner-action-effects`, `./action-contracts`, `./api/catalog`, `./api/dispatch`                                       |
+| Transport and runtime | `./client/client`, `./client/ipc`, `./runtime/*`                                                                                   |
 
-## Usage
+The two event-index paths export the same module. Runtime subpaths map to compiled JavaScript
+and declarations under `dist/runtime/`. Source files without an export path are internal.
 
-### Import Everything
+After installing the package, a minimal CommonJS example is:
 
 ```javascript
-const mama = require('@jungjaehoon/mama-core');
-
-// Access all exported functions
-const embedding = await mama.generateEmbedding('your text');
-await mama.initDB();
+process.env.MAMA_DB_PATH = '/path/to/consumer/memory.db';
+const { initDB, getDB, closeDB } = require('@jungjaehoon/mama-core');
+
+async function main() {
+  await initDB();
+  getDB(); // The initialized SQLite connection.
+  closeDB();
+}
+main().catch(console.error);
 ```
 
-### Import Specific Modules
-
-```javascript
-const { generateEmbedding } = require('@jungjaehoon/mama-core/embeddings');
-const { initDB, getDB } = require('@jungjaehoon/mama-core/db-manager');
-const mamaApi = require('@jungjaehoon/mama-core/mama-api');
+Set the path before initialization: the default `~/.claude/mama-memory.db` is real development
+memory, not a test database. Adapter-based APIs accept consumer-owned storage; consult the
+exported types for input contracts.
+
+Embeddings use `Xenova/multilingual-e5-large` (1024 dimensions), computed locally.
+Core selects `HF_HOME`, then `TRANSFORMERS_CACHE`, then the directory declared by the consumer;
+otherwise Transformers uses its own default. MAMA's OS, MCP and plugin consumers declare
+`~/.cache/huggingface/transformers`. Other consumers can call `declareEmbeddingCacheDir()`
+from `./embeddings` before the first embedding. Initial use can download model assets.
+
+## Directory layout and migrations
+
+```text
+src/
+  index.ts                  root exports
+  db-manager.ts, mama-api.ts database and development-memory facade
+  api/, client/             catalog, dispatch and transports
+  db-adapter/, storage/     SQLite adapters and storage support
+  embedding/                embeddings and model cache
+  identity/, registry/      principals and record identity
+  knowledge/, memory/       records, revisions, evidence, recall
+  operations/, provenance/  effect contracts and source references
+  runtime/                  sessions, mailbox, drivers, runs and traces
+db/migrations/              numbered SQLite migrations
+scripts/                    build support
+tests/                      package tests
 ```
 
-## Available Modules
-
-### Embedding Modules
-
-- **embeddings** - Generate embeddings using Transformers.js
-  - `generateEmbedding(text)` - Single text embedding
-  - `generateBatchEmbeddings(texts)` - Batch embedding generation
-  - `cosineSimilarity(a, b)` - Similarity calculation
-
-- **embedding-cache** - In-memory embedding cache
-  - `embeddingCache.get(key)` - Retrieve cached embedding
-  - `embeddingCache.set(key, value)` - Store embedding
-  - `embeddingCache.clear()` - Clear cache
-
-- **embedding-client** - HTTP client for embedding server
-  - `isServerRunning()` - Check server availability
-  - `getEmbeddingFromServer(text)` - Get embedding via HTTP
-  - `getServerStatus()` - Server health check
-
-### Database Modules
-
-- **db-manager** - SQLite database initialization
-  - `initDB()` - Initialize database with migrations
-  - `getDB()` - Get database connection
-  - `closeDB()` - Close connection
-
-- **db-adapter** - Database adapter interface
-  - `createAdapter(type)` - Create SQLite adapter
-  - Supports prepared statements and transactions
-
-- **memory-store** - Decision storage operations
-  - CRUD operations for decisions
-  - Vector similarity search
-
-### Memory API
-
-- **memory/api** - Scoped memory operations
-  - `saveMemory(input)` - Save typed memory with scopes and optional event_date (preference, fact, decision, lesson, constraint)
-  - `recallMemory(query, options)` - Truth-aware recall with scope filtering, strictness modes, and retrieval diagnostics
-  - `buildProfile(scopes)` - Build memory profile (static/dynamic/evidence)
-  - `ingestMemory(input)` - Ingest raw content as memory
-  - `ingestConversation(input)` - Decompose conversations into typed memory units via optional LLM extraction
-  - `evolveMemory(input)` - Resolve graph edges between memories
-  - `buildMemoryBootstrap(params)` - Build memory agent bootstrap context
-  - `createAuditAck(input)` - Create audit acknowledgment
-  - `recordMemoryAudit(input)` - Record channel audit with state management
-
-- **memory/truth-store** - Truth projection layer
-  - `projectMemoryTruth(row)` - Write truth projection
-  - `queryRelevantTruth(params)` - Query current truth with scope/query filtering
-  - `queryTruthByTopic(topic)` - Get truth rows for a topic
-
-- **memory/evolution-engine** - Graph edge resolution
-  - `resolveMemoryEvolution(input)` - Determine supersedes/builds_on edges
-
-- **memory/extraction-prompt** - LLM extraction for conversation ingestion
-  - `buildExtractionPrompt(messages)` - Build structured prompt for memory extraction
-  - `parseExtractionResponse(response)` - Parse LLM JSON response into typed units
-
-- **memory/channel-summary-state-store** - Channel state management
-  - `recordChannelAudit(input)` - Accumulate audit outcomes into channel state
-
-- **memory/provenance** - Trusted memory provenance
-  - Preserves compact runtime origin metadata in `provenance_json`
-  - Keeps underlying raw/memory/case/entity refs in `source_refs_json`
-  - Ignores caller-supplied untrusted provenance on public paths
-
-- **model-runs** - Agent execution lineage
-  - `model-runs/store` records model run lifecycle and replay metadata
-  - `model-runs/tool-trace-store` records tool calls for later audit and reconstruction
-
-- **connectors/raw-query** - Unified raw evidence reads
-  - Query raw connector rows through scope-aware filters
-  - Preserve raw source ids for downstream provenance
-
-- **agent-situation** - Worker situation packets
-  - Build, rank, cache, insert, and read append-only situation packets for worker context
-
-- **agent-graph** - Worker graph/entity helpers
-  - Query graph neighborhoods, resolve entities, and write aliases with visibility checks
-
-### Core API (Legacy)
-
-- **mama-api** - High-level API interface (wraps memory API)
-  - `save(decision)` - Save decision
-  - `recall(topic)` - Retrieve decision history
-  - `suggest(query, options)` - Semantic search with hybrid FTS5 + vector + recency, strictness controls, and diagnostics
-  - `updateOutcome(id, outcome)` - Update decision outcome
-
-- **search/search-quality** - Search option normalization
-  - `normalizeSearchQualityOptions(options)` - Normalize recall/balanced/strict thresholds and confirmation requirements
-
-- **edges** - Twin edge ledger
-  - Validate refs and store durable edges between memory, raw, entity, case, and packet refs
-
-- **decision-tracker** - Decision graph management
-  - `learnDecision(decision)` - Learn from decision
-  - `createEdgesFromReasoning(reasoning)` - Parse decision links
-
-- **relevance-scorer** - Semantic similarity scoring
-  - `scoreRelevance(query, decisions)` - Score decision relevance
-  - Combines vector, graph, and recency signals
-
-### Configuration
-
-- **config-loader** - Configuration management
-  - `loadConfig()` - Load MAMA configuration
-  - `getModelName()` - Get embedding model name
-  - `getEmbeddingDim()` - Get embedding dimensions
-  - `updateConfig(config)` - Update configuration
-
-## Environment Variables
-
-- `MAMA_DB_PATH` - Database file path (default: `~/.claude/mama-memory.db`)
-- `MAMA_EMBEDDING_PORT` - Embedding server port (default: `3849`)
-- `MAMA_HTTP_PORT` - Backward-compatible alias for embedding server port
-
-## Dependencies
-
-- **@huggingface/transformers** - Local embedding generation
-- **better-sqlite3** - SQLite runtime with FTS5 support
-- **Pure-TS cosine similarity** - Vector search (no native extensions)
+The highest migration is **096**, `096-drop-connector-event-index-fts.sql`.
+Migration files cover **001–042** and **061–096**; there is no 043 file.
+**044–060 are reserved** by the retired chain's `schema_version` entries and must never be
+reused. Add schema changes after 096, not into a gap. See [migrations](db/migrations).
 
 ## Development
 
-```bash
-# Install dependencies
-pnpm install
-
-# Run tests
-pnpm test
-
-# Watch mode
-pnpm test:watch
-```
-
-## Test Coverage
-
-- 120+ unit/integration test files in `packages/mama-core/tests`
-- 100% passing
-- Tests cover:
-  - Config loader, database initialization, module exports
-  - Memory API (save, recall, profile)
-  - Truth store, evolution engine, scope schema
-  - Channel summary, channel summary state
-  - Event store, finding store, bootstrap builder
-  - Memory provenance, model runs, tool traces
-  - Twin edges, raw query, agent situation, agent graph
-  - Strict search diagnostics and rollup provenance
-  - Legacy shim compatibility
-
-## Architecture
-
-MAMA Core uses CommonJS modules and is designed to be shared across multiple packages:
-
-```
-packages/mama-core/
-├── src/
-│   ├── index.ts              # Main exports
-│   ├── embeddings.ts         # Embedding generation
-│   ├── db-manager.ts         # Database management
-│   ├── mama-api.ts           # High-level API (wraps memory API)
-│   ├── db-adapter/           # Database adapter (SQLite)
-│   ├── memory/               # Memory infrastructure
-│       ├── types.ts          # MemoryRecord, MemoryScopeRef, RecallBundle, etc.
-│       ├── api.ts            # saveMemory, recallMemory, buildProfile, etc.
-│       ├── truth-store.ts    # Truth projection layer
-│       ├── extraction-prompt.ts  # LLM extraction prompt + parser
-│       ├── evolution-engine.ts  # Graph edge resolution
-│       ├── scope-store.ts    # Scope management
-│       ├── event-store.ts    # Audit event persistence
-│       ├── finding-store.ts  # Audit finding persistence
-│       ├── channel-summary-store.ts       # Channel summaries
-│       ├── channel-summary-state-store.ts # Channel state reducer
-│       ├── bootstrap-builder.ts           # Memory agent bootstrap
-│       └── profile-builder.ts             # Profile classification
-│   ├── model-runs/           # Model run + tool trace lineage
-│   ├── connectors/           # Raw connector query/index helpers
-│   ├── edges/                # Twin edge ledger
-│   ├── agent-situation/      # Worker situation packets
-│   ├── agent-graph/          # Worker graph/entity helpers
-│   └── search/               # Search quality option normalization
-├── db/migrations/            # SQLite migrations (001-036)
-└── tests/                    # Unit and integration tests
-```
-
-## Migration Files
-
-Database migrations are included in `db/migrations/` (001-036):
-
-- 001-013: Core schema (decisions, embeddings, graph edges)
-- 014: Add is_static column
-- 015: FTS5 full-text search index
-- 016: Memory kind/status/summary columns
-- 017-018: Memory scopes and scope bindings
-- 019-020: Memory events and audit findings
-- 021: Memory truth projection
-- 022-023: Channel summaries and state
-- 024-036: event dates, connector memory kinds, canonical entities, case-first memory, wiki/index
-  provenance, model/tool traces, twin edges, and agent situation packets
-
-## License
-
-MIT - see LICENSE file for details
-
-## Links
-
-- [GitHub Repository](https://github.com/jungjaehoon-lifegamez/MAMA)
-- [Documentation](https://github.com/jungjaehoon-lifegamez/MAMA/tree/main/docs)
-- [Issues](https://github.com/jungjaehoon-lifegamez/MAMA/issues)
-
----
+Build with `pnpm install` and `pnpm build` at the repository root.
+Run `pnpm typecheck` or `pnpm test` inside this package; use a temporary home and explicit
+database path as described in [testing](../../docs/development/testing.md).
+The packed second-consumer check is tracked in [the rebuild plan](../../docs/rebuild/plan.md);
+package tests alone do not establish that goal.
 
-**Part of the MAMA monorepo** - Memory-Augmented MCP Assistant
+[Documentation](../../docs/index.md) · [MIT](../../LICENSE).

package/db/migrations/030-case-first-memory-substrate.sql

@@ -8,7 +8,7 @@
 -- connector_event_index, learned ranker + search feedback,
 -- case_links + tombstones, case promotion/freshness columns,
 -- case membership explanation columns.
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md
+-- Spec: the case-first memory design spec (not retained in the repository)
 
 -- ================================================================
 -- Entity substrate — decision_entity_sources
@@ -259,7 +259,7 @@ ALTER TABLE entity_observations DROP COLUMN source_raw_db_ref;
 -- ================================================================
 -- Migration 039: Create case_truth table
 -- Phase 1 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md §5.2
+-- Spec: the case-first memory design spec (not retained in the repository) §5.2
 
 CREATE TABLE IF NOT EXISTS case_truth (
   case_id TEXT PRIMARY KEY,                                                 -- UUID, also persisted in wiki frontmatter
@@ -295,7 +295,7 @@ CREATE INDEX IF NOT EXISTS idx_case_truth_last_activity ON case_truth(last_activ
 -- ================================================================
 -- Migration 040: Create case_memberships table
 -- Phase 1 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md §5.3
+-- Spec: the case-first memory design spec (not retained in the repository) §5.3
 --
 -- Locked tombstone encoding (§0d Option B): (status='stale', user_locked=1).
 -- CHECK enum stays at 5 values; no 'stale_locked'.
@@ -326,7 +326,7 @@ CREATE INDEX IF NOT EXISTS idx_case_memberships_case_status
 -- ================================================================
 -- Migration 041: Create case_corrections table
 -- Phase 1 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md §5.4
+-- Spec: the case-first memory design spec (not retained in the repository) §5.4
 --
 -- Option C (Phase 0 §0f): target_ref_json TEXT (readable canonical JSON) +
 -- target_ref_hash BLOB (32-byte SHA-256 over canonical JSON).
@@ -372,7 +372,7 @@ CREATE INDEX IF NOT EXISTS idx_case_corrections_target_kind
 -- ================================================================
 -- Migration 042: Create case_proposal_queue table
 -- Phase 1 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md §5.7
+-- Spec: the case-first memory design spec (not retained in the repository) §5.7
 --
 -- Acceptance-layer queue for LLM proposals rejected by the deterministic
 -- acceptance layer (§4.2). Phase 1 SCAFFOLD + quarantine writes only; HITL
@@ -429,7 +429,7 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_case_proposal_queue_dedup
 -- ================================================================
 -- Migration 043: Wiki page search index for mama_search integration
 -- Phase 1 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md §7.1
+-- Spec: the case-first memory design spec (not retained in the repository) §7.1
 --
 -- Tables: wiki_page_index (metadata), wiki_page_embeddings (vectors),
 -- wiki_pages_fts (FTS5 inverted index). FTS5 is REGULAR (not contentless,
@@ -515,101 +515,16 @@ ALTER TABLE entity_timeline_events ADD COLUMN role TEXT;
 
 -- ================================================================
 -- Phase 3 — connector_event_index
--- ================================================================
--- Migration 045: Create connector_event_index and replay-safe connector cursors
--- Phase 3 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md Amendment 9
-
-CREATE TABLE IF NOT EXISTS connector_event_index (
-  event_index_id TEXT PRIMARY KEY,
-  source_connector TEXT NOT NULL,
-  source_type TEXT NOT NULL,
-  source_id TEXT NOT NULL,
-  source_locator TEXT,
-  channel TEXT,
-  author TEXT,
-  title TEXT,
-  content TEXT NOT NULL,
-  event_datetime INTEGER,
-  event_date TEXT,
-  source_timestamp_ms INTEGER NOT NULL,
-  metadata_json TEXT,
-  artifact_locator TEXT,
-  artifact_title TEXT,
-  content_hash BLOB NOT NULL CHECK(length(content_hash) = 32),
-  indexed_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL,
-  expires_at TEXT
-);
-
-CREATE UNIQUE INDEX IF NOT EXISTS idx_connector_event_index_source_identity
-  ON connector_event_index(source_connector, source_id);
-
-CREATE INDEX IF NOT EXISTS idx_connector_event_index_cursor_order
-  ON connector_event_index(source_connector, source_timestamp_ms, source_id);
-
-CREATE INDEX IF NOT EXISTS idx_connector_event_index_event_datetime
-  ON connector_event_index(event_datetime, event_index_id);
-
-CREATE INDEX IF NOT EXISTS idx_connector_event_index_event_date
-  ON connector_event_index(event_date, event_datetime, event_index_id);
-
-CREATE INDEX IF NOT EXISTS idx_connector_event_index_artifact_locator
-  ON connector_event_index(artifact_locator)
-  WHERE artifact_locator IS NOT NULL;
-
-CREATE INDEX IF NOT EXISTS idx_connector_event_index_expires_at
-  ON connector_event_index(expires_at)
-  WHERE expires_at IS NOT NULL;
-
-CREATE VIRTUAL TABLE IF NOT EXISTS connector_event_index_fts USING fts5(
-  event_index_id UNINDEXED,
-  title,
-  content,
-  author,
-  channel,
-  tokenize = 'unicode61 remove_diacritics 2'
-);
-
-CREATE TRIGGER IF NOT EXISTS trg_connector_event_index_ai
-AFTER INSERT ON connector_event_index
-BEGIN
-  INSERT INTO connector_event_index_fts(event_index_id, title, content, author, channel)
-  VALUES (NEW.event_index_id, NEW.title, NEW.content, NEW.author, NEW.channel);
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_connector_event_index_au
-AFTER UPDATE OF title, content, author, channel ON connector_event_index
-BEGIN
-  DELETE FROM connector_event_index_fts WHERE event_index_id = OLD.event_index_id;
-  INSERT INTO connector_event_index_fts(event_index_id, title, content, author, channel)
-  VALUES (NEW.event_index_id, NEW.title, NEW.content, NEW.author, NEW.channel);
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_connector_event_index_ad
-AFTER DELETE ON connector_event_index
-BEGIN
-  DELETE FROM connector_event_index_fts WHERE event_index_id = OLD.event_index_id;
-END;
-
-CREATE TABLE IF NOT EXISTS connector_event_index_cursors (
-  connector_name TEXT PRIMARY KEY,
-  last_seen_timestamp_ms INTEGER NOT NULL DEFAULT 0,
-  last_seen_source_id TEXT NOT NULL DEFAULT '',
-  last_sweep_at TEXT,
-  last_success_at TEXT,
-  last_error TEXT,
-  last_error_at TEXT,
-  indexed_count INTEGER NOT NULL DEFAULT 0
-);
-
+-- The connector event index was declared here. It moved to the package that has
+-- connectors: three of the four consumers of this core have none, and were
+-- creating eighteen tables they never write. See standalone/db/migrations/001.
 
 -- ================================================================
 -- Phase 3 — search_feedback + ranker
 -- ================================================================
 -- Migration 046: Create search_feedback and ranker_model_versions
 -- Phase 3 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md Amendment 10
+-- Spec: the case-first memory design spec (not retained in the repository) Amendment 10
 
 CREATE TABLE IF NOT EXISTS search_feedback (
   feedback_id TEXT PRIMARY KEY,
@@ -700,7 +615,7 @@ VALUES ('search_feedback_retention_days', '180', strftime('%Y-%m-%dT%H:%M:%fZ','
 -- ================================================================
 -- Migration 047: Create case_links and revoked wiki tombstones
 -- Phase 3 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md Amendment 11
+-- Spec: the case-first memory design spec (not retained in the repository) Amendment 11
 
 CREATE TABLE IF NOT EXISTS case_links (
   link_id TEXT PRIMARY KEY,
@@ -855,7 +770,7 @@ WHERE split_from_case_id IS NOT NULL
 -- ================================================================
 -- Migration 048: Add case promotion and freshness columns
 -- Phase 3 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md Amendments 12 + 13
+-- Spec: the case-first memory design spec (not retained in the repository) Amendments 12 + 13
 
 ALTER TABLE case_truth ADD COLUMN canonical_decision_id TEXT;
 ALTER TABLE case_truth ADD COLUMN canonical_event_id TEXT;
@@ -886,7 +801,7 @@ ALTER TABLE case_truth ADD COLUMN freshness_reason_json TEXT;
 -- ================================================================
 -- Migration 049: Add case membership explanation columns
 -- Phase 3 of MAMA Case-First Memory System
--- Spec: docs/superpowers/specs/2026-04-17-mama-work-case-first-memory-system-design.md Amendment 14
+-- Spec: the case-first memory design spec (not retained in the repository) Amendment 14
 
 ALTER TABLE case_memberships ADD COLUMN assignment_strategy TEXT;
 ALTER TABLE case_memberships ADD COLUMN score_breakdown_json TEXT;

package/db/migrations/034-add-connector-event-scope-columns.sql

@@ -1,14 +1,10 @@
-ALTER TABLE connector_event_index ADD COLUMN source_cursor TEXT;
-ALTER TABLE connector_event_index ADD COLUMN tenant_id TEXT;
-ALTER TABLE connector_event_index ADD COLUMN project_id TEXT;
-ALTER TABLE connector_event_index ADD COLUMN memory_scope_kind TEXT;
-ALTER TABLE connector_event_index ADD COLUMN memory_scope_id TEXT;
+-- Retired: this migration declared scope columns on the connector event index.
+--
+-- The index moved to the package that has connectors. Three of the four consumers
+-- of this core have none, and were running these statements against tables they
+-- never write. The schema is declared whole in standalone/db/migrations/001.
+--
+-- The file stays, and the number stays claimed: databases in the field recorded
+-- 34 as applied, and a number that comes back meaning something else is worse
+-- than a number that means nothing.
 
-CREATE INDEX IF NOT EXISTS idx_connector_event_scope
-  ON connector_event_index(tenant_id, project_id, memory_scope_kind, memory_scope_id);
-
-CREATE INDEX IF NOT EXISTS idx_connector_event_source_cursor
-  ON connector_event_index(source_connector, source_cursor);
-
-INSERT OR IGNORE INTO schema_version (version, description)
-VALUES (34, 'Add connector event scope columns');

package/db/migrations/039-add-connector-event-operator-ingest-seq.sql

@@ -1,96 +1,10 @@
-ALTER TABLE connector_event_index
-  ADD COLUMN operator_ingest_seq INTEGER CHECK (
-    operator_ingest_seq IS NULL OR operator_ingest_seq >= 1
-  );
+-- Retired: this migration declared the operator ingest sequence on the connector event index.
+--
+-- The index moved to the package that has connectors. Three of the four consumers
+-- of this core have none, and were running these statements against tables they
+-- never write. The schema is declared whole in standalone/db/migrations/001.
+--
+-- The file stays, and the number stays claimed: databases in the field recorded
+-- 39 as applied, and a number that comes back meaning something else is worse
+-- than a number that means nothing.
 
-CREATE TABLE IF NOT EXISTS connector_event_index_operator_seq_cursors (
-  source_connector TEXT NOT NULL,
-  channel TEXT NOT NULL DEFAULT '',
-  next_seq INTEGER NOT NULL CHECK (next_seq >= 1),
-  PRIMARY KEY (source_connector, channel)
-);
-
-WITH ranked_events AS (
-  SELECT
-    event_index_id,
-    ROW_NUMBER() OVER (
-      PARTITION BY source_connector, COALESCE(channel, '')
-      ORDER BY rowid ASC
-    ) AS operator_seq
-  FROM connector_event_index
-)
-UPDATE connector_event_index
-SET operator_ingest_seq = (
-  SELECT operator_seq
-  FROM ranked_events
-  WHERE ranked_events.event_index_id = connector_event_index.event_index_id
-)
-WHERE operator_ingest_seq IS NULL;
-
-INSERT OR IGNORE INTO connector_event_index_operator_seq_cursors (
-  source_connector,
-  channel,
-  next_seq
-)
-SELECT
-  source_connector,
-  COALESCE(channel, ''),
-  COALESCE(MAX(operator_ingest_seq), 0) + 1
-FROM connector_event_index
-GROUP BY source_connector, COALESCE(channel, '');
-
-CREATE UNIQUE INDEX IF NOT EXISTS idx_connector_event_index_operator_scope_seq
-  ON connector_event_index(source_connector, COALESCE(channel, ''), operator_ingest_seq)
-  WHERE operator_ingest_seq IS NOT NULL;
-
-CREATE INDEX IF NOT EXISTS idx_connector_event_index_operator_cursor_order
-  ON connector_event_index(source_connector, channel, operator_ingest_seq);
-
-CREATE TRIGGER IF NOT EXISTS trg_connector_event_index_operator_ingest_seq_ai
-AFTER INSERT ON connector_event_index
-WHEN NEW.operator_ingest_seq IS NULL
-BEGIN
-  INSERT OR IGNORE INTO connector_event_index_operator_seq_cursors (
-    source_connector,
-    channel,
-    next_seq
-  )
-  VALUES (NEW.source_connector, COALESCE(NEW.channel, ''), 1);
-
-  UPDATE connector_event_index
-  SET operator_ingest_seq = (
-    SELECT next_seq
-    FROM connector_event_index_operator_seq_cursors
-    WHERE source_connector = NEW.source_connector
-      AND channel = COALESCE(NEW.channel, '')
-  )
-  WHERE event_index_id = NEW.event_index_id;
-
-  UPDATE connector_event_index_operator_seq_cursors
-  SET next_seq = next_seq + 1
-  WHERE source_connector = NEW.source_connector
-    AND channel = COALESCE(NEW.channel, '');
-END;
-
-CREATE TRIGGER IF NOT EXISTS trg_connector_event_index_operator_ingest_seq_explicit_ai
-AFTER INSERT ON connector_event_index
-WHEN NEW.operator_ingest_seq IS NOT NULL
-BEGIN
-  INSERT OR IGNORE INTO connector_event_index_operator_seq_cursors (
-    source_connector,
-    channel,
-    next_seq
-  )
-  VALUES (NEW.source_connector, COALESCE(NEW.channel, ''), 1);
-
-  UPDATE connector_event_index_operator_seq_cursors
-  SET next_seq = CASE
-    WHEN next_seq <= NEW.operator_ingest_seq THEN NEW.operator_ingest_seq + 1
-    ELSE next_seq
-  END
-  WHERE source_connector = NEW.source_connector
-    AND channel = COALESCE(NEW.channel, '');
-END;
-
-INSERT OR IGNORE INTO schema_version (version, description)
-VALUES (39, 'Add connector event operator ingest sequence');