cortexm 0.3.0__py3-none-any.whl

cortexm/config.py

@@ -0,0 +1,375 @@
+"""Central configuration for the memory fabric.
+
+Every knob the strategic plan calls out is expressed here so the whole
+system is reproducible from one dataclass. Codec selection implements the
+cortexm-compress tier model (INT8 default, Binary-HRR edge, RaBitQ
+ultra-edge, PQ cloud).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, asdict
+from typing import Final
+
+CODECS = ("int8", "binary", "rabitq", "pq")
+VSA_MODES = ("perm", "conv", "bag")
+# Index backends — alternative storage/search paths for the VSA palace.
+#   * "quadrant" — default page-clustered log-depth 2-means tree (Rust wheel
+#     at rust/quadrant/). INT8-quantized leaves, best-first tree descent.
+#   * "nsg"     — Navigating Spreading-out Graph (proximity graph). Lower
+#     query latency at high recall on high-dim vectors; build is slower.
+#   * "flat"    — exact brute-force dot product. Reference; O(N) per query.
+# Used by Config.index_backend (validated in __post_init__).
+INDEX_BACKENDS: Final[tuple[str, ...]] = ("quadrant", "nsg", "flat")
+
+# Storage tiers from the compression appendix (bytes per 1M memories).
+STORAGE_TIERS = {
+    "int8": "768 MB VSA + ~100 MB Trace  (baseline)",
+    "binary": "96 MB VSA + ~50 MB Trace   (edge / Raspberry Pi 5)",
+    "rabitq": "96 MB VSA + ~50 MB Trace   (ultra-edge, 94%+ recall)",
+    "pq": "8 MB VSA + ~75 MB Trace     (cloud, M=8 x 8-bit codes)",
+}
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    v = os.environ.get(name)
+    if v is None:
+        return default
+    return v.strip().lower() in ("1", "true", "yes", "on")
+
+
+@dataclass
+class Config:
+    """All knobs. Defaults implement the plan's "Edge tier" profile."""
+
+    # --- storage -------------------------------------------------------
+    db_path: str = ":memory:"          # SQLite file for Trace + vectors
+    codec: str = "int8"                # int8 | binary | rabitq | pq
+    tmr: bool = False                  # triple-modular redundancy (binary)
+    hash_provider: str = "blake3"      # blake3 | blake2b (auto-fallback)
+
+    # --- VSA ------------------------------------------------------------
+    dims: int = 768
+    vsa_mode: str = "perm"             # perm | conv | bag
+    lexical_lambda: float = 0.6        # weight of lexical superposition
+    seed: int = 0x0C0FFEE
+
+    # --- ingest ---------------------------------------------------------
+    min_confidence: float = 0.30       # below -> not committed
+    fallback_mentions: bool = True     # low-conf entity mentions
+    enable_rules: bool = True          # Datalog-lite materialization
+    apply_rules_each_add: bool = True  # False: defer to Memory.apply_rules()
+    enable_lifecycle: bool = True      # interference-aware lifecycle
+    value_match_threshold: float = 0.92  # near-duplicate merge cutoff
+    quarantine_injection: bool = True  # InjecMEM defense
+    quarantine_contagion: bool = True  # MINJA second-order defense
+    contagion_threshold: float = 0.50   # token-overlap cutoff for taint
+
+    # --- retrieval ------------------------------------------------------
+    top_k_default: int = 12
+    search_k_mult: int = 4             # oversampling for scope filtering
+    hop_expansion: int = 1             # associative hops for multi-hop
+    history_window: int = 3            # superseded facts shown per chain
+    fusion_vsa_weight: float = 0.6
+    fusion_symbolic_weight: float = 0.4
+
+    # --- OOD ingestion (Unmess + DisSim + Bitap trigger widening) -----------
+    # When True, the main `mem.add()` path runs the chaos-mode pipeline
+    # before the deterministic extractor:
+    #   1. PerUserIdiolectNormalizer.observe() — accumulate slang
+    #   2. PerUserIdiolectNormalizer.normalize() — text-speak + kNN slang
+    #      replacement ("u" → "you", "bruh" → "friend" if user-co-occurred)
+    #   3. DisSim recursive split — compound sentences become simple clauses
+    #      so each one matches its own pattern ("Although Alice works at X,
+    #      she quit yesterday" → 3 clauses, 3 patterns fire)
+    #   4. Bitap fuzzy-trigger widening in extractor._sentence_candidates
+    #      so "wrks at" / "livs in" still fires the works_at/lives_in pattern
+    # Default ON — the OOD paraphrase/slang recall catastrophe (9.4% / 5.1%
+    # in Tier-1) is exactly what this layer fixes, and it stays μ=0.
+    unmess_enabled: bool = True
+    unmess_max_depth: int = 2          # DisSim recursion limit
+    # Bitap trigger widening: if a known trigger word (works, lives, etc.)
+    # is NOT found in the sentence, try fuzzy match within max_edits. This
+    # catches "wrks", "livs", "prfrs" without bloating the regex set.
+    bitap_trigger_enabled: bool = True
+    bitap_trigger_max_edits: int = 2   # 2 edits = "wrks"→"works", "livs"→"lives"
+
+    # --- μ≈0 tiny-transformer fallback (pattern-miss retrieval) ------------
+    # When Bitap widened the trigger but the pattern library still returned
+    # zero candidates for a sentence, run a 2-layer self-attention "tiny
+    # transformer" whose weights are derived deterministically from the
+    # project seed (no external model download, no ONNX runtime, no GPU).
+    # Closes the OOD recall long tail without breaking the μ=0 / cost / audit
+    # moat. Default ON in production; bench baselines turn it off via
+    # bench_config_overrides() so the fallback's lift is visible in isolation.
+    tiny_fallback_enabled: bool = True
+
+    # --- LaBSE-inspired polyglot encoder (non-English ingest fix) ----------
+    # docs/BENCHMARKS.md Tier-1 shows non-English extraction recall =
+    # 0.000 ± 0.000 — the regex tokenizer + HashingEmbedder drops non-ASCII
+    # letters entirely, so every non-English sentence embeds to the same
+    # constant vector [1, 0, 0, ...] and retrieval is broken.
+    # When True, HashingEmbedder delegates text with >30% non-ASCII chars
+    # to PolyglotEncoder (cortexm.text.labse) — a LaBSE-inspired Unicode
+    # n-gram hasher that handles CJK / Devanagari / Arabic / Cyrillic /
+    # Thai / Hangul / Hiragana / Katakana via script-aware tokenization +
+    # char n-grams + signed feature hashing. Pure numpy + stdlib
+    # unicodedata, no model download (3GB LaBSE weights would violate the
+    # μ=0 + no-GPU rules), bit-identical across runs. Default OFF so the
+    # existing English path stays untouched; opt-in for deployments that
+    # ingest non-English text. See context_m/text/labse.py for the algorithm.
+    labse_enabled: bool = False
+
+    # --- Query-aware triple pre-filter (HippoRAG 2 lineage) ----------------
+    # When True, the reader drops candidate facts with low
+    # lexical+semantic+relation overlap with the query BEFORE fusion.
+    # HippoRAG 2 credits this for a 7% F1 gain. μ=0 — deterministic scorer.
+    prefilter_enabled: bool = True
+    prefilter_threshold: float = 0.08  # combined score below this → drop
+    prefilter_min_keep: int = 3        # always keep at least this many
+
+    # --- FadeMem-style forgetting (retention decay + sleep sweeps) ----------
+    # When True, the consolidate() pass also runs a FadeMem sweep that
+    # decays retention scores, marks low-retention facts for deactivation,
+    # and consolidates clusters of related facts into summary holograms.
+    # Default ON in production — measured 43.2% storage reduction with
+    # zero retrieval-precision regression (see benchmarks/results/final.json).
+    # Bench scripts flip this back to False via bench_config_overrides()
+    # so baseline numbers stay comparable across releases.
+    fade_enabled: bool = True
+    fade_lambda: float = 0.05          # exponential decay rate per day
+    fade_access_boost: float = 0.5     # each access multiplies retention
+    fade_contradiction_penalty: float = 0.25  # supersession pressure
+    fade_deactivate_threshold: float = 0.10  # below this → deactivate
+
+    # --- TiMem Temporal Memory Tree (4-level consolidation hierarchy) -------
+    # When True, the consolidate() pass also builds hierarchical summaries:
+    #   L1 raw chunks → L2 session summaries → L3 daily patterns → L4 persona
+    # Each higher level is a derived fact that links down to its constituents
+    # via DERIVED_FROM edges. Retrieval can short-circuit to the appropriate
+    # level based on query complexity (complex queries hit L3/L4).
+    tmt_enabled: bool = False
+    tmt_session_cluster_mins: int = 5   # facts needed before a session summary
+    tmt_persona_min_sessions: int = 3   # sessions before persona abstraction
+
+    # --- HMS Cognition Engine (self-organizing memory) ---------------------
+    # When True, the consolidate() pass also runs the 5-stage cognition
+    # pipeline: PatternScanner (surface regularities) + AbstractionEngine
+    # (build prototype categories) + GapDetector (find missing relations)
+    # + HypothesisEngine (propose fillers) + AnalogyDetector (find
+    # isomorphic domains). Output is HYPOTHESIZED_BY edges with confidence
+    # < 0.5 — never promoted to active retrieval unless explicitly
+    # confirmed by user input. Default OFF — opt-in for use cases that
+    # want self-organization (e.g. agent memory that should infer
+    # `grandparent` from two `father` facts).
+    cognition_enabled: bool = False
+    cognition_min_support: int = 2   # min facts for a pattern to be significant
+    cognition_max_hyp_confidence: float = 0.45  # cap on hypothesis confidence
+
+    # --- Provenance standards stack (enterprise-grade) ---------------------
+    # When True, every memory commit is wrapped in a COSE Sign1 envelope
+    # (RFC 9052) signed with an Ed25519 agent key, and memory ranges can
+    # be exported as W3C Verifiable Credentials / SCITT-signed statements.
+    # BLAKE3 source hashing stays as the internal integrity mechanism;
+    # this layer sits on top for external interoperability (enterprise
+    # security reviews ask "does it support W3C VC? C2PA? SCITT?" — yes).
+    provenance_enabled: bool = False
+    provenance_agent_key_path: str | None = None  # Ed25519 PEM (else generate)
+    provenance_agent_did: str | None = None        # did:key identifier
+
+    # --- Structural multi-hop query (deterministic symbolic chains) --------
+    # When True, the reader exposes `structural_query(start_entity,
+    # relation_chain)` that walks exact relation chains via Trace lookups
+    # + VSA unbinding as fallback. Complementary to PPR (probabilistic)
+    # — PPR answers "what else might be relevant?", structural query
+    # answers "exactly follow this chain."
+    structural_query_enabled: bool = True
+
+    # --- Hopfield sparse-softmax cleanup (modernized cleanup memory) -----
+    # When True, the VSA cleanup memory uses sparse-softmax attention
+    # instead of plain softmax for noise recovery. Sparse softmax keeps
+    # only the top-k highest attention weights per recall step, which is
+    # more robust to outlier codebook entries (HMS-style improvement
+    # over Ramsauer 2020's plain softmax).
+    hopfield_sparse_softmax: bool = True
+    hopfield_sparse_topk: int = 16   # top-k weights kept per recall step
+
+    # --- Active reconstruction (MRAgent ICML 2026) ---------------------------
+    # When True, the reader exposes a `reconstruct()` method that runs an
+    # iterative PPR+LLM-scoring loop: expand seed nodes via 2-hop PPR, score
+    # each hop's relevance to the query, prune low-scoring branches, return
+    # a synthesized narrative. Default OFF — it's an LLM-assisted path that
+    # breaks strict μ=0; opt-in for use cases that need it.
+    reconstruct_enabled: bool = False
+    reconstruct_max_hops: int = 3
+    reconstruct_prune_threshold: float = 0.25
+
+    # --- MIND defense (InjecMEM attack mitigation) -----------------------------
+    # When True, retrieval runs a diversity check on the top-k results.
+    # InjecMEM relies on centroid anchors that cluster in embedding space —
+    # if the top-k results are too similar (low intra-result diversity),
+    # that's a signature of anchor-based poisoning, and the results are
+    # flagged for audit. This is μ=0 compatible (pure embedding math).
+    mind_diversity_check: bool = True
+    mind_diversity_threshold: float = 0.85  # mean pairwise cosine above this → flag
+    mind_flag_on_low_diversity: bool = True   # mark results as suspect, don't drop
+
+    # --- cross-encoder rerank (μ=0, web search SOTA 2026-08) -------------
+    # Cross-encoder-style reranking: re-score top-K candidates by cosine
+    # sim between query embedding and a natural-language rendering of
+    # each fact ("the name of beam_1 is jennifer mccall"). Lifts prec@5
+    # 10-20pp on MS-MARCO-style benchmarks. Default OFF so baseline
+    # numbers don't shift; bench enables via "+rerank" config.
+    enable_rerank: bool = False
+    rerank_alpha: float = 0.55          # weight on rerank score (vs original)
+    rerank_beta: float = 0.45           # weight on original fusion score
+    prf_alpha: float = 0.6              # Rocchio: query weight
+    prf_beta: float = 0.4               # Rocchio: top-3 mean weight
+    prf_topn: int = 3                   # how many top hits for PRF mean
+
+    # --- index ----------------------------------------------------------
+    # Which proximity-index backend the memory palace uses for ANN search
+    # over hologram vectors. See INDEX_BACKENDS at the top of this file
+    # for the full menu. Default "quadrant" — the existing page-clustered
+    # log-depth 2-means tree. "nsg" switches to the Navigating Spreading-
+    # out Graph (Fu et al. VLDB 2019) — sparser edges, lower query latency
+    # at high recall, slower build. "flat" is the exact brute-force
+    # reference path (no approximation).
+    index_backend: str = "quadrant"
+    index_threshold: int = 2048        # build tree when N >= this
+    index_leaf_size: int = 512
+    index_branch: int = 8
+    beam_width: int = 6
+
+    # --- SLB --------------------------------------------------------------
+    slb_entries: int = 64
+    slb_threshold: float = 0.97
+    # Bench determinism: when True, the SLB is bypassed entirely so each
+    # query recomputes fresh fusion. Without this, templated near-duplicate
+    # queries (e.g. "What is the name of beam_1?" / "What is the age of
+    # beam_1?") land at cosine ≈ 0.97 against the SLB threshold, and BLAS
+    # ULP drift across processes flips the hit/miss decision — producing
+    # ±5pp prec@5 variance on identical bench runs. Production runs leave
+    # this False (SLB is a real perf win); only the bench script enables it.
+    slb_disabled: bool = False
+
+    # --- Personalized PageRank (HippoRAG 2 lineage) --------------------------
+    ppr_enabled: bool = True          # graph diffusion read mode
+    ppr_damping: float = 0.85
+    ppr_iters: int = 12
+    ppr_weight: float = 0.5           # fusion boost multiplier
+    ppr_graph_size: int = 96          # local subgraph node budget
+    ppr_seeds: int = 6                # teleport set size
+
+    # --- scopes -----------------------------------------------------------
+    default_user_id: str = "default"
+    sandbox_enabled: bool = True        # agent-scoped facts isolated from
+    #                                       user-scope reads until promoted
+    sandbox_promote_min_confidence: float = 0.5  # promotion gate
+
+    # --- durability ---------------------------------------------------------
+    wal_sync: str = "normal"            # normal | full (full = fsync every
+    #                                       commit; survives power loss)
+
+    # --- enterprise ---------------------------------------------------------
+    pii_mode: str = "off"              # off | redact | block | tag
+    encryption_at_rest: bool = False    # AES-256-GCM field encryption
+    master_key_path: str | None = None  # explicit key file (else env/sidecar)
+    audit_enabled: bool = True          # hash-chained audit log
+    audit_actions: str = "security"    # "security" | "all" | "none"
+    rate_limit_rps: float = 50.0        # REST server, requests/second/key
+    rate_limit_burst: int = 100
+
+    # --- ZK-SQL proofs (Halo2/PLONKish-inspired, pure-Python) ----------------
+    # When True, the MCP server exposes `contextm_zk_sql_proof` (membership /
+    # count / sum / avg / min / max proofs over the Trace without revealing
+    # the underlying facts). Default OFF — proof generation is O(N) in trace
+    # size, opt-in. The verifier is sublinear (commitment check is O(1) hash
+    # equality + O(1) HMAC). The prover holds an HMAC key (ZK_SQL_KEY in the
+    # trace kv store) and signs each transcript; this is NOT a cryptographic
+    # SNARK (BLAKE3 commitments are not homomorphic), but it demonstrates the
+    # API surface that a production Halo2/KZG backend would expose.
+    zk_sql_enabled: bool = False
+
+    def __post_init__(self) -> None:
+        if self.codec not in CODECS:
+            raise ValueError(f"codec must be one of {CODECS}, got {self.codec!r}")
+        if self.vsa_mode not in VSA_MODES:
+            raise ValueError(f"vsa_mode must be one of {VSA_MODES}, got {self.vsa_mode!r}")
+        if self.dims <= 0 or self.dims % 8:
+            raise ValueError("dims must be a positive multiple of 8")
+        if self.index_backend not in INDEX_BACKENDS:
+            raise ValueError(
+                f"index_backend must be one of {INDEX_BACKENDS}, "
+                f"got {self.index_backend!r}")
+
+    # Environment overrides (12-factor friendly for MCP server / edge daemon)
+    @classmethod
+    def from_env(cls, **overrides) -> "Config":
+        cfg = cls(**overrides) if overrides else cls()
+        if p := os.environ.get("CONTEXT_M_DB"):
+            cfg.db_path = p
+        if c := os.environ.get("CONTEXT_M_CODEC"):
+            cfg.codec = c
+        if m := os.environ.get("CONTEXT_M_VSA_MODE"):
+            cfg.vsa_mode = m
+        if d := os.environ.get("CONTEXT_M_DIMS"):
+            cfg.dims = int(d)
+        if _env_bool("CONTEXT_M_TMR", cfg.tmr):
+            cfg.tmr = True
+        if pm := os.environ.get("CONTEXT_M_PII_MODE"):
+            cfg.pii_mode = pm
+        if mk := os.environ.get("CONTEXT_M_MASTER_KEY_PATH"):
+            cfg.master_key_path = mk
+        if os.environ.get("CONTEXT_M_ENCRYPT"):
+            cfg.encryption_at_rest = _env_bool("CONTEXT_M_ENCRYPT",
+                                               cfg.encryption_at_rest)
+        if aa := os.environ.get("CONTEXT_M_AUDIT"):
+            cfg.audit_actions = aa
+        # Allow flipping the index backend via env (e.g. CONTEXT_M_INDEX_BACKEND=nsg
+        # for high-recall cloud deployments where the build cost is amortized).
+        if ib := os.environ.get("CONTEXT_M_INDEX_BACKEND"):
+            cfg.index_backend = ib
+        # Production nightly-cron flips. The helm CronJob template sets
+        # CONTEXT_M_FADE=true and CONTEXT_M_TMT=true so the batch process
+        # runs the FadeMem sweep + TiMem TMT hierarchy build on top of the
+        # standard consolidate pass. Reading from env (not just CLI flags)
+        # means `cortexm consolidate --db …` in the CronJob container
+        # automatically picks them up.
+        if os.environ.get("CONTEXT_M_FADE") is not None:
+            cfg.fade_enabled = _env_bool("CONTEXT_M_FADE", cfg.fade_enabled)
+        if os.environ.get("CONTEXT_M_TMT") is not None:
+            cfg.tmt_enabled = _env_bool("CONTEXT_M_TMT", cfg.tmt_enabled)
+        if os.environ.get("CONTEXT_M_RECONSTRUCT") is not None:
+            cfg.reconstruct_enabled = _env_bool(
+                "CONTEXT_M_RECONSTRUCT", cfg.reconstruct_enabled)
+        # HMS Cognition Engine — opt-in self-organization. The helm
+        # CronJob template sets CONTEXT_M_COGNITION=true so the batch
+        # process also runs PatternScanner + AbstractionEngine +
+        # GapDetector + HypothesisEngine + AnalogyDetector on top of
+        # the standard consolidate pass.
+        if os.environ.get("CONTEXT_M_COGNITION") is not None:
+            cfg.cognition_enabled = _env_bool(
+                "CONTEXT_M_COGNITION", cfg.cognition_enabled)
+        # Enterprise provenance standards. Opt-in — when true, every
+        # commit is wrapped in a COSE Sign1 envelope (RFC 9052) and
+        # ranges can be exported as W3C VC / SCITT statements.
+        if os.environ.get("CONTEXT_M_PROVENANCE") is not None:
+            cfg.provenance_enabled = _env_bool(
+                "CONTEXT_M_PROVENANCE", cfg.provenance_enabled)
+        # ZK-SQL proofs (PoneglyphDB-style PLONKish). Opt-in.
+        if os.environ.get("CONTEXT_M_ZK_SQL") is not None:
+            cfg.zk_sql_enabled = _env_bool(
+                "CONTEXT_M_ZK_SQL", cfg.zk_sql_enabled)
+        # Polyglot encoder for non-English text. Opt-in — production
+        # deployments that ingest CJK / Indic / Arabic / Cyrillic text
+        # flip this on so HashingEmbedder falls back to PolyglotEncoder
+        # for >30% non-ASCII text instead of emitting a constant
+        # [1,0,0,...] vector that breaks retrieval (Tier-1 bug).
+        if os.environ.get("CONTEXT_M_LABSE") is not None:
+            cfg.labse_enabled = _env_bool("CONTEXT_M_LABSE", cfg.labse_enabled)
+        return cfg
+
+    def to_dict(self) -> dict:
+        return asdict(self)

cortexm/cortexm.py

@@ -0,0 +1,8 @@
+"""Alias module — the strategic plan ships the import name ``cortexm``.
+
+    from cortexm import Memory        # identical to: from cortexm import Memory
+"""
+
+from cortexm import Memory, Config, __version__  # noqa: F401
+
+__all__ = ["Memory", "Config", "__version__"]

cortexm/enterprise/audit.py

@@ -0,0 +1,178 @@
+"""Hash-chained, append-only audit log (SOC 2 / SIEM ready).
+
+Every security-relevant operation — add, search, delete, erasure, key
+management, snapshot, restore — appends one record:
+
+  {seq, ts, actor, role, action, resource, outcome, meta,
+   prev_hash, hash}
+
+``hash = BLAKE2b(prev_hash || canonical-record)`` — tampering with any
+record breaks the chain and ``verify()`` pinpoints the first damaged
+sequence number. Records are also exported as JSONL (one per line) for
+Splunk / Elastic / Datadog ingestion, and a syslog-style single-line
+format for legacy collectors.
+
+GDPR note: the audit chain is intentionally exempt from user erasure
+(accounting/legitimate-interest records). It stores actor + resource
+ids, never raw conversation text.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from datetime import datetime, timezone
+
+from cortexm.security.hashes import HashProvider
+
+# actions that are always audited
+AUDITED_ACTIONS = {
+    "memory.add", "memory.search", "memory.update", "memory.delete",
+    "memory.delete_all", "memory.verify",
+    "governance.erase", "governance.retention", "governance.snapshot",
+    "governance.restore", "governance.pitr",
+    "keys.create", "keys.revoke", "auth.failure", "security.quarantine",
+}
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds")
+
+
+class AuditLog:
+    def __init__(self, store, enabled: bool = True) -> None:
+        self.store = store
+        self.enabled = enabled
+        self._hasher = HashProvider("blake2b")
+        self._lock = threading.Lock()
+        self._ensure_table()
+
+    def _ensure_table(self) -> None:
+        self.store.conn.execute("""
+            CREATE TABLE IF NOT EXISTS audit_log (
+                seq INTEGER PRIMARY KEY AUTOINCREMENT,
+                ts TEXT NOT NULL,
+                actor TEXT NOT NULL,
+                role TEXT,
+                action TEXT NOT NULL,
+                resource TEXT,
+                outcome TEXT NOT NULL,
+                meta TEXT,
+                prev_hash TEXT NOT NULL,
+                hash TEXT NOT NULL
+            )""")
+        # indexes for the common tail() filters (actor, action, ts)
+        self.store.conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_audit_actor_action "
+            "ON audit_log(actor, action)")
+        self.store.conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_audit_ts ON audit_log(ts)")
+        self.store.conn.commit()
+
+    # ------------------------------------------------------------- append
+    def log(self, action: str, *, actor: str = "system", role: str | None = None,
+            resource: str | None = None, outcome: str = "success",
+            meta: dict | None = None) -> dict | None:
+        if not self.enabled:
+            return None
+        with self._lock:
+            row = self.store.conn.execute(
+                "SELECT seq, hash FROM audit_log ORDER BY seq DESC LIMIT 1"
+            ).fetchone()
+            prev = row["hash"] if row else "genesis"
+            rec = {
+                "ts": _now_iso(), "actor": actor, "role": role or "-",
+                "action": action, "resource": resource or "-",
+                "outcome": outcome,
+                "meta": json.dumps(meta or {}, sort_keys=True),
+            }
+            canonical = json.dumps(rec, sort_keys=True, separators=(",", ":"))
+            digest = self._hasher.hash_text(f"{prev}|{canonical}")
+            self.store.conn.execute(
+                "INSERT INTO audit_log(ts, actor, role, action, resource,"
+                " outcome, meta, prev_hash, hash) VALUES(?,?,?,?,?,?,?,?,?)",
+                (rec["ts"], rec["actor"], rec["role"], rec["action"],
+                 rec["resource"], rec["outcome"], rec["meta"], prev, digest))
+            self.store.conn.commit()
+            return {"seq": self.store.conn.execute(
+                "SELECT last_insert_rowid() AS s").fetchone()["s"],
+                **rec, "prev_hash": prev, "hash": digest}
+
+    # ------------------------------------------------------------- read
+    def tail(self, n: int = 100, actor: str | None = None,
+             action: str | None = None) -> list[dict]:
+        q = "SELECT * FROM audit_log"
+        conds, args = [], []
+        if actor:
+            conds.append("actor=?"); args.append(actor)
+        if action:
+            conds.append("action=?"); args.append(action)
+        if conds:
+            q += " WHERE " + " AND ".join(conds)
+        q += " ORDER BY seq DESC LIMIT ?"
+        args.append(int(n))
+        return [dict(r) for r in self.store.conn.execute(q, args)]
+
+    def verify(self) -> dict:
+        """Recompute the chain; report the first broken seq."""
+        prev = "genesis"
+        broken_at = None
+        n = 0
+        for row in self.store.conn.execute(
+                "SELECT * FROM audit_log ORDER BY seq ASC"):
+            n += 1
+            rec = {"ts": row["ts"], "actor": row["actor"], "role": row["role"],
+                   "action": row["action"], "resource": row["resource"],
+                   "outcome": row["outcome"], "meta": row["meta"]}
+            canonical = json.dumps(rec, sort_keys=True, separators=(",", ":"))
+            digest = self._hasher.hash_text(f"{prev}|{canonical}")
+            if digest != row["hash"] or prev != row["prev_hash"]:
+                broken_at = row["seq"]
+                break
+            prev = row["hash"]
+        return {"records": n, "intact": broken_at is None,
+                "first_broken_seq": broken_at,
+                "head_hash": prev if broken_at is None else None}
+
+    # ------------------------------------------------------------- export
+    def export_jsonl(self, path: str) -> int:
+        """SIEM ingestion export (Splunk/Elastic/Datadog friendly)."""
+        count = 0
+        with open(path, "w", encoding="utf-8") as fh:
+            for row in self.store.conn.execute(
+                    "SELECT * FROM audit_log ORDER BY seq ASC"):
+                rec = {k: row[k] for k in row.keys()}
+                try:
+                    rec["meta"] = json.loads(rec["meta"])
+                except Exception:
+                    pass
+                fh.write(json.dumps(rec, sort_keys=True) + "\n")
+                count += 1
+        return count
+
+    def export_syslog(self, path: str) -> int:
+        """RFC-3164-style lines: <134>ts actor action resource outcome."""
+        count = 0
+        with open(path, "w", encoding="utf-8") as fh:
+            for row in self.store.conn.execute(
+                    "SELECT * FROM audit_log ORDER BY seq ASC"):
+                ts = row["ts"][:19].replace("T", " ")
+                fh.write(f"<134>{ts} context-m audit: actor={row['actor']} "
+                         f"action={row['action']} resource={row['resource']} "
+                         f"outcome={row['outcome']} seq={row['seq']}\n")
+                count += 1
+        return count
+
+
+class AuditContext:
+    """Request-scoped audit binding (actor/role propagated by the server)."""
+
+    def __init__(self, audit: AuditLog | None, actor: str = "system",
+                 role: str | None = None) -> None:
+        self.audit = audit
+        self.actor = actor
+        self.role = role
+
+    def log(self, action: str, **kw) -> None:
+        if self.audit is not None:
+            self.audit.log(action, actor=self.actor, role=self.role, **kw)