superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/storage/migrations/M032_write_coordinator_admission.py

@@ -1,188 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""M032 — durable, append-only receipts for canonical write commands.
-
-The receipt ledger is profile-isolated at the client idempotency boundary.
-``command_id`` and ``journal_id`` remain globally durable identifiers; a
-client-supplied idempotency key is unique only with its target profile.  An
-operation id is a projection label (for example, ``update:<fact_id>``), not a
-durable command identifier, so it is deliberately indexed but not unique.
-"""
-
-from __future__ import annotations
-
-import sqlite3
-
-NAME = "M032_write_coordinator_admission"
-DB_TARGET = "memory"
-
-DDL = """
-CREATE TABLE IF NOT EXISTS write_commits (
-    commit_sequence INTEGER PRIMARY KEY AUTOINCREMENT,
-    command_id      TEXT NOT NULL UNIQUE,
-    journal_id      TEXT NOT NULL UNIQUE,
-    command_kind    TEXT NOT NULL,
-    request_hash    TEXT NOT NULL,
-    profile_id      TEXT NOT NULL,
-    idempotency_key TEXT NOT NULL,
-    operation_id    TEXT NOT NULL,
-    receipt_json    TEXT NOT NULL,
-    committed_at    REAL NOT NULL,
-    UNIQUE(profile_id, idempotency_key)
-);
-CREATE INDEX IF NOT EXISTS idx_write_commits_committed_at
-    ON write_commits (committed_at);
-CREATE INDEX IF NOT EXISTS idx_write_commits_operation_id
-    ON write_commits (operation_id);
-CREATE TRIGGER IF NOT EXISTS trg_write_commits_immutable_update
-BEFORE UPDATE ON write_commits
-BEGIN
-    SELECT RAISE(ABORT, 'write_commits receipts are immutable');
-END;
-CREATE TRIGGER IF NOT EXISTS trg_write_commits_immutable_delete
-BEFORE DELETE ON write_commits
-BEGIN
-    SELECT RAISE(ABORT, 'write_commits receipts are immutable');
-END;
-"""
-
-_CREATE_TABLE = DDL.split(";", 1)[0]
-_CREATE_COMMITTED_AT_INDEX = (
-    "CREATE INDEX IF NOT EXISTS idx_write_commits_committed_at "
-    "ON write_commits (committed_at)"
-)
-_CREATE_OPERATION_ID_INDEX = (
-    "CREATE INDEX IF NOT EXISTS idx_write_commits_operation_id "
-    "ON write_commits (operation_id)"
-)
-_CREATE_UPDATE_TRIGGER = """
-CREATE TRIGGER IF NOT EXISTS trg_write_commits_immutable_update
-BEFORE UPDATE ON write_commits
-BEGIN
-    SELECT RAISE(ABORT, 'write_commits receipts are immutable');
-END
-"""
-_CREATE_DELETE_TRIGGER = """
-CREATE TRIGGER IF NOT EXISTS trg_write_commits_immutable_delete
-BEFORE DELETE ON write_commits
-BEGIN
-    SELECT RAISE(ABORT, 'write_commits receipts are immutable');
-END
-"""
-
-
-def apply(conn: sqlite3.Connection) -> None:
-    """Create or safely upgrade the profile-scoped append-only receipt ledger."""
-    if verify(conn):
-        return
-    if not _table_exists(conn):
-        _create_current_schema(conn)
-        return
-    _rebuild_legacy_schema(conn)
-
-
-def repair(conn: sqlite3.Connection) -> None:
-    """Repair a completed provisional M032 in developer/test databases."""
-    apply(conn)
-
-
-def verify(conn: sqlite3.Connection) -> bool:
-    """Return true only when the full profile-safe ledger contract exists."""
-    if not _table_exists(conn):
-        return False
-    columns = {row[1] for row in conn.execute("PRAGMA table_info(write_commits)").fetchall()}
-    required = {
-        "commit_sequence",
-        "command_id",
-        "journal_id",
-        "command_kind",
-        "request_hash",
-        "profile_id",
-        "idempotency_key",
-        "operation_id",
-        "receipt_json",
-        "committed_at",
-    }
-    if not required <= columns:
-        return False
-    if not _has_unique_index(conn, ("command_id",)):
-        return False
-    if not _has_unique_index(conn, ("journal_id",)):
-        return False
-    if not _has_unique_index(conn, ("profile_id", "idempotency_key")):
-        return False
-    if _has_unique_index(conn, ("idempotency_key",)):
-        return False
-    if _has_unique_index(conn, ("operation_id",)):
-        return False
-    object_names = {
-        row[0]
-        for row in conn.execute(
-            "SELECT name FROM sqlite_master WHERE name IN (?, ?, ?, ?)",
-            (
-                "idx_write_commits_committed_at",
-                "idx_write_commits_operation_id",
-                "trg_write_commits_immutable_update",
-                "trg_write_commits_immutable_delete",
-            ),
-        ).fetchall()
-    }
-    return object_names == {
-        "idx_write_commits_committed_at",
-        "idx_write_commits_operation_id",
-        "trg_write_commits_immutable_update",
-        "trg_write_commits_immutable_delete",
-    }
-
-
-def _table_exists(conn: sqlite3.Connection) -> bool:
-    return conn.execute(
-        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='write_commits'"
-    ).fetchone() is not None
-
-
-def _has_unique_index(conn: sqlite3.Connection, columns: tuple[str, ...]) -> bool:
-    for index in conn.execute("PRAGMA index_list(write_commits)").fetchall():
-        if not index[2]:
-            continue
-        index_columns = tuple(
-            row[2] for row in conn.execute(f"PRAGMA index_info({index[1]})").fetchall()
-        )
-        if index_columns == columns:
-            return True
-    return False
-
-
-def _create_current_schema(conn: sqlite3.Connection) -> None:
-    conn.execute(_CREATE_TABLE)
-    conn.execute(_CREATE_COMMITTED_AT_INDEX)
-    conn.execute(_CREATE_OPERATION_ID_INDEX)
-    conn.execute(_CREATE_UPDATE_TRIGGER)
-    conn.execute(_CREATE_DELETE_TRIGGER)
-
-
-def _rebuild_legacy_schema(conn: sqlite3.Connection) -> None:
-    """Rebuild only M032's own standalone table under one savepoint."""
-    conn.execute("SAVEPOINT m032_profile_scoped_idempotency")
-    try:
-        conn.execute("DROP TRIGGER IF EXISTS trg_write_commits_immutable_update")
-        conn.execute("DROP TRIGGER IF EXISTS trg_write_commits_immutable_delete")
-        conn.execute("ALTER TABLE write_commits RENAME TO write_commits_legacy")
-        conn.execute("DROP INDEX IF EXISTS idx_write_commits_committed_at")
-        conn.execute("DROP INDEX IF EXISTS idx_write_commits_operation_id")
-        _create_current_schema(conn)
-        conn.execute(
-            "INSERT INTO write_commits("
-            "commit_sequence, command_id, journal_id, command_kind, request_hash, "
-            "profile_id, idempotency_key, operation_id, receipt_json, committed_at"
-            ") SELECT commit_sequence, command_id, journal_id, command_kind, request_hash, "
-            "profile_id, idempotency_key, operation_id, receipt_json, committed_at "
-            "FROM write_commits_legacy"
-        )
-        conn.execute("DROP TABLE write_commits_legacy")
-    except BaseException:
-        conn.execute("ROLLBACK TO m032_profile_scoped_idempotency")
-        conn.execute("RELEASE m032_profile_scoped_idempotency")
-        raise
-    conn.execute("RELEASE m032_profile_scoped_idempotency")

package/src/superlocalmemory/storage/migrations/M033_projection_transactions.py

@@ -1,148 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-from __future__ import annotations
-
-import sqlite3
-
-NAME = "M033_projection_transactions"
-DB_TARGET = "memory"
-
-DDL = """
-CREATE TABLE IF NOT EXISTS projection_obligations (
-    obligation_id   INTEGER PRIMARY KEY AUTOINCREMENT,
-    operation_id    TEXT NOT NULL,
-    profile_id      TEXT NOT NULL,
-    owner           TEXT NOT NULL,
-    kind            TEXT NOT NULL CHECK (kind IN ('apply', 'erase')),
-    subject_id      TEXT NOT NULL,
-    revision        INTEGER NOT NULL DEFAULT 0,
-    state           TEXT NOT NULL DEFAULT 'pending' CHECK (
-                        state IN (
-                            'pending', 'applied', 'verified',
-                            'failed', 'compensated', 'erased'
-                        )
-                    ),
-    checksum        TEXT,
-    detail          TEXT,
-    attempts        INTEGER NOT NULL DEFAULT 0,
-    created_at      REAL NOT NULL,
-    updated_at      REAL NOT NULL,
-    UNIQUE (operation_id, owner, kind)
-);
-CREATE INDEX IF NOT EXISTS idx_projection_obligations_operation
-    ON projection_obligations (operation_id);
-CREATE INDEX IF NOT EXISTS idx_projection_obligations_profile_state
-    ON projection_obligations (profile_id, state);
-CREATE INDEX IF NOT EXISTS idx_projection_obligations_state_updated
-    ON projection_obligations (state, updated_at);
-CREATE TABLE IF NOT EXISTS completion_manifests (
-    operation_id        TEXT PRIMARY KEY,
-    profile_id          TEXT NOT NULL,
-    state               TEXT NOT NULL CHECK (
-                            state IN ('COMPLETE', 'DEGRADED', 'FAILED')
-                        ),
-    all_met             INTEGER NOT NULL DEFAULT 0 CHECK (all_met IN (0, 1)),
-    obligation_count    INTEGER NOT NULL DEFAULT 0,
-    owner_evidence_json TEXT NOT NULL,
-    manifest_hash       TEXT NOT NULL,
-    created_at          REAL NOT NULL,
-    updated_at          REAL NOT NULL
-);
-CREATE INDEX IF NOT EXISTS idx_completion_manifests_profile_state
-    ON completion_manifests (profile_id, state);
-"""
-
-_REQUIRED_OBLIGATION_COLUMNS = frozenset({
-    "obligation_id",
-    "operation_id",
-    "profile_id",
-    "owner",
-    "kind",
-    "subject_id",
-    "revision",
-    "state",
-    "checksum",
-    "detail",
-    "attempts",
-    "created_at",
-    "updated_at",
-})
-
-_REQUIRED_MANIFEST_COLUMNS = frozenset({
-    "operation_id",
-    "profile_id",
-    "state",
-    "all_met",
-    "obligation_count",
-    "owner_evidence_json",
-    "manifest_hash",
-    "created_at",
-    "updated_at",
-})
-
-_REQUIRED_OBJECTS = frozenset({
-    "projection_obligations",
-    "completion_manifests",
-    "idx_projection_obligations_operation",
-    "idx_projection_obligations_profile_state",
-    "idx_projection_obligations_state_updated",
-    "idx_completion_manifests_profile_state",
-})
-
-
-def apply(conn: sqlite3.Connection) -> None:
-    if verify(conn):
-        return
-    conn.executescript(DDL)
-
-
-def repair(conn: sqlite3.Connection) -> None:
-    apply(conn)
-
-
-def verify(conn: sqlite3.Connection) -> bool:
-    if not _table_exists(conn, "projection_obligations"):
-        return False
-    if not _table_exists(conn, "completion_manifests"):
-        return False
-    if not _REQUIRED_OBLIGATION_COLUMNS <= _columns(conn, "projection_obligations"):
-        return False
-    if not _REQUIRED_MANIFEST_COLUMNS <= _columns(conn, "completion_manifests"):
-        return False
-    if not _has_unique_index(conn, "projection_obligations", ("operation_id", "owner", "kind")):
-        return False
-    present = {
-        row[0]
-        for row in conn.execute(
-            "SELECT name FROM sqlite_master WHERE name IN "
-            "(?, ?, ?, ?, ?, ?)",
-            tuple(sorted(_REQUIRED_OBJECTS)),
-        ).fetchall()
-    }
-    return _REQUIRED_OBJECTS <= present
-
-
-def _table_exists(conn: sqlite3.Connection, name: str) -> bool:
-    return conn.execute(
-        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?",
-        (name,),
-    ).fetchone() is not None
-
-
-def _columns(conn: sqlite3.Connection, table: str) -> set[str]:
-    return {row[1] for row in conn.execute(f"PRAGMA table_info({table})").fetchall()}
-
-
-def _has_unique_index(
-    conn: sqlite3.Connection, table: str, columns: tuple[str, ...],
-) -> bool:
-    for index in conn.execute(f"PRAGMA index_list({table})").fetchall():
-        if not index[2]:
-            continue
-        index_columns = tuple(
-            row[2] for row in conn.execute(f"PRAGMA index_info({index[1]})").fetchall()
-        )
-        if index_columns == columns:
-            return True
-    return False

package/src/superlocalmemory/storage/migrations/M034_obligation_integrity.py

@@ -1,58 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-from __future__ import annotations
-
-import sqlite3
-
-NAME = "M034_obligation_integrity"
-DB_TARGET = "memory"
-
-DDL = """
-ALTER TABLE projection_obligations ADD COLUMN context_digest TEXT;
-ALTER TABLE projection_obligations ADD COLUMN verify_attempts INTEGER NOT NULL DEFAULT 0;
-ALTER TABLE projection_obligations ADD COLUMN last_verified_at REAL;
-"""
-
-_ADDED_COLUMNS = {
-    "context_digest": "ALTER TABLE projection_obligations ADD COLUMN context_digest TEXT",
-    "verify_attempts": (
-        "ALTER TABLE projection_obligations "
-        "ADD COLUMN verify_attempts INTEGER NOT NULL DEFAULT 0"
-    ),
-    "last_verified_at": (
-        "ALTER TABLE projection_obligations ADD COLUMN last_verified_at REAL"
-    ),
-}
-
-
-def apply(conn: sqlite3.Connection) -> None:
-    if not _table_exists(conn):
-        return
-    existing = _columns(conn)
-    for column, statement in _ADDED_COLUMNS.items():
-        if column not in existing:
-            conn.execute(statement)
-
-
-def repair(conn: sqlite3.Connection) -> None:
-    apply(conn)
-
-
-def verify(conn: sqlite3.Connection) -> bool:
-    if not _table_exists(conn):
-        return False
-    return set(_ADDED_COLUMNS) <= _columns(conn)
-
-
-def _table_exists(conn: sqlite3.Connection) -> bool:
-    return conn.execute(
-        "SELECT 1 FROM sqlite_master WHERE type='table' AND name='projection_obligations'"
-    ).fetchone() is not None
-
-
-def _columns(conn: sqlite3.Connection) -> set[str]:
-    return {
-        row[1]
-        for row in conn.execute("PRAGMA table_info(projection_obligations)").fetchall()
-    }

package/src/superlocalmemory/storage/migrations/M035_erasure_receipts.py

@@ -1,113 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-from __future__ import annotations
-
-import sqlite3
-
-NAME = "M035_erasure_receipts"
-DB_TARGET = "memory"
-
-DDL = """
-CREATE TABLE IF NOT EXISTS erasure_receipts (
-    erasure_id          TEXT PRIMARY KEY,
-    profile_id          TEXT NOT NULL,
-    subject_type        TEXT NOT NULL CHECK (
-                            subject_type IN ('fact', 'entity', 'profile')
-                        ),
-    subject_id          TEXT NOT NULL,
-    requested_by        TEXT NOT NULL DEFAULT '',
-    fact_count          INTEGER NOT NULL DEFAULT 0,
-    state               TEXT NOT NULL CHECK (state IN ('COMPLETE', 'FAILED')),
-    all_erased          INTEGER NOT NULL DEFAULT 0 CHECK (all_erased IN (0, 1)),
-    owner_evidence_json TEXT NOT NULL DEFAULT '[]',
-    audit_hash          TEXT NOT NULL,
-    requested_at        REAL NOT NULL,
-    completed_at        REAL NOT NULL
-);
-CREATE INDEX IF NOT EXISTS idx_erasure_receipts_profile
-    ON erasure_receipts (profile_id);
-CREATE INDEX IF NOT EXISTS idx_erasure_receipts_state
-    ON erasure_receipts (state);
-CREATE TABLE IF NOT EXISTS projection_tombstones (
-    profile_id  TEXT NOT NULL,
-    fact_id     TEXT NOT NULL,
-    erasure_id  TEXT NOT NULL,
-    memory_id   TEXT,
-    created_at  REAL NOT NULL,
-    PRIMARY KEY (profile_id, fact_id)
-);
-CREATE INDEX IF NOT EXISTS idx_projection_tombstones_fact
-    ON projection_tombstones (fact_id);
-"""
-
-_REQUIRED_RECEIPT_COLUMNS = frozenset({
-    "erasure_id",
-    "profile_id",
-    "subject_type",
-    "subject_id",
-    "requested_by",
-    "fact_count",
-    "state",
-    "all_erased",
-    "owner_evidence_json",
-    "audit_hash",
-    "requested_at",
-    "completed_at",
-})
-
-_REQUIRED_TOMBSTONE_COLUMNS = frozenset({
-    "profile_id",
-    "fact_id",
-    "erasure_id",
-    "memory_id",
-    "created_at",
-})
-
-_REQUIRED_OBJECTS = frozenset({
-    "erasure_receipts",
-    "projection_tombstones",
-    "idx_erasure_receipts_profile",
-    "idx_erasure_receipts_state",
-    "idx_projection_tombstones_fact",
-})
-
-
-def apply(conn: sqlite3.Connection) -> None:
-    if verify(conn):
-        return
-    conn.executescript(DDL)
-
-
-def repair(conn: sqlite3.Connection) -> None:
-    apply(conn)
-
-
-def verify(conn: sqlite3.Connection) -> bool:
-    if not _table_exists(conn, "erasure_receipts"):
-        return False
-    if not _table_exists(conn, "projection_tombstones"):
-        return False
-    if not _REQUIRED_RECEIPT_COLUMNS <= _columns(conn, "erasure_receipts"):
-        return False
-    if not _REQUIRED_TOMBSTONE_COLUMNS <= _columns(conn, "projection_tombstones"):
-        return False
-    present = {
-        row[0]
-        for row in conn.execute(
-            "SELECT name FROM sqlite_master WHERE name IN (?, ?, ?, ?, ?)",
-            tuple(sorted(_REQUIRED_OBJECTS)),
-        ).fetchall()
-    }
-    return _REQUIRED_OBJECTS <= present
-
-
-def _table_exists(conn: sqlite3.Connection, name: str) -> bool:
-    return conn.execute(
-        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?",
-        (name,),
-    ).fetchone() is not None
-
-
-def _columns(conn: sqlite3.Connection, table: str) -> set[str]:
-    return {row[1] for row in conn.execute(f"PRAGMA table_info({table})").fetchall()}

package/src/superlocalmemory/storage/migrations/M036_vector_row_map.py

@@ -1,107 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-from __future__ import annotations
-
-import sqlite3
-
-NAME = "M036_vector_row_map"
-DB_TARGET = "memory"
-
-DDL = """
-CREATE TABLE IF NOT EXISTS vector_row_map (
-    fact_id    TEXT NOT NULL,
-    profile_id TEXT NOT NULL,
-    vec_rowid  INTEGER NOT NULL,
-    PRIMARY KEY (fact_id)
-);
-CREATE INDEX IF NOT EXISTS idx_vector_row_map_profile
-    ON vector_row_map (profile_id);
-"""
-
-_REQUIRED_COLUMNS = frozenset({"fact_id", "profile_id", "vec_rowid"})
-
-_REQUIRED_OBJECTS = frozenset({
-    "vector_row_map",
-    "idx_vector_row_map_profile",
-})
-
-
-def apply(conn: sqlite3.Connection) -> None:
-    _reconcile(conn)
-
-
-def repair(conn: sqlite3.Connection) -> None:
-    _reconcile(conn)
-
-
-def _reconcile(conn: sqlite3.Connection) -> None:
-    _rebuild_if_malformed(conn)
-    conn.executescript(DDL)
-    _backfill(conn)
-
-
-def _rebuild_if_malformed(conn: sqlite3.Connection) -> None:
-    if not _table_exists(conn, "vector_row_map"):
-        return
-    if _REQUIRED_COLUMNS <= _columns(conn, "vector_row_map"):
-        return
-    conn.execute("DROP TABLE vector_row_map")
-
-
-def _backfill(conn: sqlite3.Connection) -> None:
-    if not _table_exists(conn, "embedding_metadata"):
-        return
-    if not {"fact_id", "profile_id", "vec_rowid"} <= _columns(conn, "embedding_metadata"):
-        return
-    conn.execute(
-        "INSERT INTO vector_row_map (fact_id, profile_id, vec_rowid) "
-        "SELECT em.fact_id, em.profile_id, em.vec_rowid FROM embedding_metadata em "
-        "WHERE em.fact_id IS NOT NULL AND em.vec_rowid IS NOT NULL "
-        "AND NOT EXISTS ("
-        "SELECT 1 FROM vector_row_map vrm WHERE vrm.fact_id = em.fact_id"
-        ")"
-    )
-
-
-def verify(conn: sqlite3.Connection) -> bool:
-    if not _table_exists(conn, "vector_row_map"):
-        return False
-    if not _REQUIRED_COLUMNS <= _columns(conn, "vector_row_map"):
-        return False
-    present = {
-        row[0]
-        for row in conn.execute(
-            "SELECT name FROM sqlite_master WHERE name IN (?, ?)",
-            tuple(sorted(_REQUIRED_OBJECTS)),
-        ).fetchall()
-    }
-    if not _REQUIRED_OBJECTS <= present:
-        return False
-    return _backfill_complete(conn)
-
-
-def _backfill_complete(conn: sqlite3.Connection) -> bool:
-    if not _table_exists(conn, "embedding_metadata"):
-        return True
-    if not {"fact_id", "vec_rowid"} <= _columns(conn, "embedding_metadata"):
-        return True
-    uncovered = conn.execute(
-        "SELECT 1 FROM embedding_metadata em "
-        "WHERE em.fact_id IS NOT NULL AND em.vec_rowid IS NOT NULL "
-        "AND NOT EXISTS ("
-        "SELECT 1 FROM vector_row_map vrm WHERE vrm.fact_id = em.fact_id"
-        ") LIMIT 1"
-    ).fetchone()
-    return uncovered is None
-
-
-def _table_exists(conn: sqlite3.Connection, name: str) -> bool:
-    return conn.execute(
-        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?",
-        (name,),
-    ).fetchone() is not None
-
-
-def _columns(conn: sqlite3.Connection, table: str) -> set[str]:
-    return {row[1] for row in conn.execute(f"PRAGMA table_info({table})").fetchall()}