marvisx-cli 0.3.7b3__tar.gz → 0.3.8b2__tar.gz

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marvisx-cli
-Version: 0.3.7b3
+Version: 0.3.8b2
 Summary: MarvisX OSS — agent-native company-brain CLI runtime (init, status, brief, triage)
 Author: MarvisX maintainers
 License: BSL-1.1

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/core/api/config.py

@@ -439,6 +439,62 @@ class Settings(BaseSettings):
         False  # pydantic-settings maps KG_HTTP_DEEP_DEFAULT env var
     )
 
+    # Track 2 #3a — STRUCTURAL graph-lane in the RRF fusion (DEFAULT OFF).
+    # When False the fused ranking is byte-identical to today (5 lanes). When
+    # True a 6th lane (seeded 1-hop edge-weighted KG expansion) joins the blend.
+    # graph_lane_hops / graph_lane_fanout / graph_lane_weight / graph_lane_seeds
+    # tune the lane without code changes. Edge-type subset = all 15 by default.
+    graph_lane_enabled: bool = Field(
+        default=False, alias="MARVIS_GRAPH_LANE"
+    )
+    graph_lane_hops: int = Field(default=1, alias="MARVIS_GRAPH_LANE_HOPS")
+    graph_lane_fanout: int = Field(default=25, alias="MARVIS_GRAPH_LANE_FANOUT")
+    graph_lane_seeds: int = Field(default=10, alias="MARVIS_GRAPH_LANE_SEEDS")
+    graph_lane_weight: float = Field(
+        default=0.12, alias="MARVIS_GRAPH_LANE_WEIGHT"
+    )
+    # #13: when a graph read finds its index stale/behind HEAD, surface the
+    # reindex as an EXPLICIT next action (command + auto_reindex marker). Default
+    # off; even when on, a read NEVER fires the (heavy, repo-re-parsing) KG
+    # reindex itself — re-indexing stays an explicit operation.
+    graph_autoreindex_on_drift: bool = Field(
+        default=False, alias="MARVIS_GRAPH_AUTOREINDEX_ON_DRIFT"
+    )
+
+    # Track 2 #1 — bi-temporal memory READ path (DEFAULT OFF). When False every
+    # learnings read is byte-identical to today (no invalid_at filter, no as_of):
+    # the temporal helper emits NO extra SQL. When True the default learnings
+    # reads (check/list/get + the learnings retrieval lane in search) add
+    # ``AND invalid_at IS NULL`` — a MECHANICAL, BINARY exclusion (superseded rows
+    # never reach the LLM; never a down-weight, which would still let the model
+    # cite the stale value). An explicit ``as_of=<ISO>`` relaxes the filter to the
+    # point-in-time window ``valid_from <= as_of AND (invalid_at IS NULL OR
+    # invalid_at > as_of)`` for audit. S3/S4/S5 (write path / LLM tiebreak / dream
+    # cycle) reuse this SAME flag. Requires migration 148 columns when enabled.
+    temporal_memory_enabled: bool = Field(
+        default=False, alias="MARVIS_TEMPORAL_MEMORY"
+    )
+
+    # Track 2 #3c — community summaries in the brief (GraphRAG global-search,
+    # DEFAULT OFF). When False the brief is byte-identical to today: the
+    # communities/community_summary modules are a flag-gated library + seam,
+    # never imported into session_brief. When True (off-host wiring), the KG is
+    # partitioned (deterministic label propagation, NO LLM) and per-community
+    # summaries enter the brief AFTER #2 so they inherit span-citation + NLI
+    # verification (a summary is itself a claim to ground, not free text).
+    community_summaries_enabled: bool = Field(
+        default=False, alias="MARVIS_COMMUNITY_SUMMARIES"
+    )
+
+    # Track 2 #2: span-citation + grounding-verification layer for the brief.
+    # DEFAULT OFF — the layer exists as a flag-gated library; when off the
+    # session_brief output is byte-for-byte unchanged (the seam is never entered).
+    # See core/api/services/grounding/. Wiring the NLI head (MiniCheck) is a
+    # separate, deliberate, off-host step (NoopVerifier is the default).
+    brief_citations_enabled: bool = Field(
+        default=False, alias="MARVIS_BRIEF_CITATIONS"
+    )
+
     # WIP limit: max tasks in_progress per project (doc/none tasks count as 0.5)
     wip_max_in_progress: int = 3
 

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/core/api/db.py

@@ -118,6 +118,13 @@ async def init_pool(size: int = 2) -> None:
 
     Pool size=8 supports concurrent deep=true requests (4 parallel KG subqueries × 2 concurrent requests).
     """
+    # Apply any pending schema migrations before opening the pool, so EVERY
+    # entry point (CLI, MCP, brain, API) lands on a current schema — not only
+    # `marvis init` and the API lifespan. Idempotent and cheap when already
+    # current (the API path migrates explicitly first, so this finds nothing).
+    # Fail-loud here is a clearer signal than a later "no such column" on the
+    # first write against a half-upgraded DB. (#12)
+    run_migrations()
     global _pool, _pool_size, _writer
     actual_size = 8  # read-only pool: expanded for KG lens 4-subquery parallel pattern (Phase 7.0)
     _pool = asyncio.Queue(maxsize=actual_size)

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/core/api/main.py

@@ -931,6 +931,20 @@ async def _periodic_inbox_digest() -> None:
                     result.get("overflow", 0),
                     result.get("expired", 0),
                 )
+            # Invariant guard: every VISIBLE item must be deepened. The 6 UTC
+            # precompute is best-effort/one-shot; this sweep catches its failures
+            # and items promoted into visible later in the day.
+            from core.api.services.inbox_digest_deep_research import (
+                sweep_visible_missing_deep_research,
+            )
+
+            sweep = await sweep_visible_missing_deep_research()
+            if sweep.get("missing"):
+                logger.info(
+                    "Digest deep-research sweep: deepened %d/%d missing visible items",
+                    sweep.get("generated", 0),
+                    sweep.get("missing", 0),
+                )
         except asyncio.CancelledError:
             break
         except Exception:

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/core/api/mcp/server.py

@@ -34,10 +34,51 @@ from core.api.mcp.tools import register_all
 # `app.state` equivalent for a server with no FastAPI `app`). Tools register on
 # this at import time so `from core.api.mcp.server import mcp` already carries the
 # full tool set — the smoke test introspects it without launching stdio.
-mcp = FastMCP("marvis")
+_INSTRUCTIONS = (
+    "Marvis is a company-brain MCP for cross-project orchestration and institutional memory.\n"
+    "Route by task type (prefer these structured tools over re-deriving context from raw files):\n"
+    "- Cold-start / 'state of project X': session_brief(slug) — it also suggests the next tool when the project is cross-project.\n"
+    "- 'If I pause / close / de-prioritize project X, what blocks?': project_impact(slug) — the project-level blast radius. "
+    "(graph_impact on a 'project:artifact:<slug>' node with depends_on does the same.)\n"
+    "- 'What breaks if I change function X' (code level): graph_impact / graph_neighbors on a 'py:function:...' node.\n"
+    "- 'What do we already know / what bit us before' (decisions and risky actions): check_learnings(q).\n"
+    "- Cross-project discovery by meaning: search(q). Body of ONE known project: get_project(slug) — do not layer search on top of get_project.\n"
+)
+
+mcp = FastMCP("marvis", instructions=_INSTRUCTIONS)
 
 register_all(mcp)
 
+# mcp-ergonomics (tiering): mark the cold-start core always-loaded so clients with
+# MCP tool-search (e.g. Claude Code — the agent that drives the brain) keep these in
+# context and defer the other ~60 tools on demand. A 70-tool surface is well over the
+# ~20-30 threshold where tool-selection accuracy degrades. Additive: clients without
+# tool-search still see every tool (no regression). Best-effort — a FastMCP registry
+# shape change degrades to a no-op, never a boot failure.
+_CORE_TOOLS = frozenset(
+    {
+        "session_brief",
+        "search",
+        "check_learnings",
+        "list_tasks",
+        "get_task",
+        "create_task",
+        "update_task",
+        "get_project",
+        "graph_impact",
+        "graph_neighbors",
+        "project_impact",
+    }
+)
+try:
+    for _name, _tool in mcp._tool_manager._tools.items():
+        if _name in _CORE_TOOLS:
+            _m = dict(_tool.meta or {})
+            _m["anthropic/alwaysLoad"] = True
+            _tool.meta = _m
+except Exception:  # pragma: no cover - FastMCP internal-shape guard
+    pass
+
 
 def main() -> None:
     """Run the MCP server over stdio (the OSS runtime entrypoint).

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/core/api/mcp/tools/graph.py

@@ -123,10 +123,10 @@ def register(mcp) -> None:
         rank: NeighborRank = "none",
         as_of: Annotated[str, Field(pattern=_AS_OF_PATTERN, max_length=32)] | None = None,
     ) -> dict[str, Any]:
-        """[Power-user] Surgical 1-hop neighbour query for a KG node (calls/imports/defines/mentions/...) — per context completo su un nodo usa get_task/get_project/get_handoff/get_learning(deep=true). Usa questo tool solo quando hai bisogno di ispezionare il vicinato topologico diretto senza il bundle completo.
-        QUANDO USARLO: refactor impact assessment su una singola function; verificare se un nodo ha caller inattesi; time-travel as_of su commit specifico; rank=suspect_write per bug write-through-read.
-        QUANDO NON USARLO: NOT per context di un task/handoff/learning -> usa get_*(deep=true). NOT per BFS transitivo -> usa graph_impact.
-        RESTITUISCE: list of {node_id, relation, direction, rank_score?} cap 200."""
+        """1-hop: chi tocca / dipende direttamente da un nodo. Funziona su codice ('py:function:...') E su progetti ('project:artifact:<slug>').
+        ORCHESTRAZIONE: per i vicini diretti di un PROGETTO (chi dipende da X) passa node_id='project:artifact:<slug>' con edge_types=['depends_on']. Codice: caller/callee 1-hop di una function.
+        QUANDO USARLO: vicinato diretto senza il bundle completo; caller inattesi; time-travel as_of; rank=suspect_write per bug write-through-read. Per il blast radius transitivo usa graph_impact / project_impact.
+        RESTITUISCE: list of {node_id, relation, direction, rank_score?, freshness} cap 200."""
         try:
             async with acquire_db() as db:
                 # Node proxy hardcodes limit=200 (the surface exposes no limit param).
@@ -152,7 +152,7 @@ def register(mcp) -> None:
         limit: Annotated[int, Field(ge=1, le=100)] = 20,
         type_filter: HotspotTypeFilter = "file",
     ) -> dict[str, Any]:
-        """[Power-user] DORA-style churn ranking: files/functions sorted by touch_count 7d/30d with bus-factor warning — per context completo su un progetto usa get_project(deep=true). Usa questo tool per analisi architetturale di rischio o pianificazione refactor.
+        """DORA-style churn ranking: files/functions sorted by touch_count 7d/30d with bus-factor warning — per context completo su un progetto usa get_project(deep=true). Usa questo tool per analisi architetturale di rischio o pianificazione refactor.
         QUANDO USARLO: identificare moduli ad alto rischio prima di una release; trovare ownership gaps (bus_factor=1); pianificare tech debt.
         QUANDO NON USARLO: NOT per context di un progetto specifico -> usa get_project(deep=true). NOT per BFS da un nodo -> usa graph_impact.
         RESTITUISCE: list of {node_id, touch_count_7d, touch_count_30d, authors[], bus_factor} top N."""
@@ -178,10 +178,10 @@ def register(mcp) -> None:
         edge_types: list[EdgeType] | None = None,
         project: Annotated[str, Field(max_length=50, pattern=_PROJECT_PATTERN)] | None = None,
     ) -> dict[str, Any]:
-        """[Power-user] BFS impact analysis: 'cosa si rompe se cambio X?' con ranker su direct callers + transitive list — per context completo usa get_task(deep=true). Usa questo tool per delete/rename risk assessment o pre-refactor sweep.
-        QUANDO USARLO: prima di eliminare/rinominare una function critica; misurare blast radius di una migration; dependency cascade analysis.
-        QUANDO NON USARLO: NOT per context standard -> usa get_*(deep=true). NOT per 1-hop only -> usa graph_neighbors.
-        RESTITUISCE: {direct_callers[], transitive_list[], rank_score} depth configurabile."""
+        """Impact / blast radius: 'cosa si rompe — o quali progetti si bloccano — se cambio / pauso / chiudo X?'. BFS sui rami transitivi + ranker sui diretti.
+        ORCHESTRAZIONE DI PORTAFOGLIO: per sapere quali PROGETTI si bloccano se pausi/chiudi un progetto, passa node_id='project:artifact:<slug>' con edge_types=['depends_on','mentions','refers_to'] — oppure usa il tool dedicato project_impact(slug). Livello-codice: per 'cosa si rompe se cambio questa function' passa un node 'py:function:...'.
+        QUANDO USARLO: prima di pausare/chiudere/de-prioritizzare un progetto (blast radius cross-project); prima di eliminare/rinominare una function critica; dependency cascade analysis; sequenziare lavoro (cosa sblocca cosa).
+        RESTITUISCE: {direct (callers/dependents)[], transitive_list[], rank_score, freshness (indexed_sha vs HEAD)} depth configurabile."""
         try:
             async with acquire_db() as db:
                 result = await graph_uc.graph_impact(
@@ -197,15 +197,38 @@ def register(mcp) -> None:
         except ServiceError as e:
             raise_mcp_error(e)
 
+    @mcp.tool()
+    async def project_impact(
+        slug: Annotated[str, Field(max_length=50, pattern=_PROJECT_PATTERN)],
+        depth: Annotated[int, Field(ge=1, le=5)] = 2,
+    ) -> dict[str, Any]:
+        """Portfolio blast radius: 'se pauso / chiudo / de-prioritizzo questo PROGETTO, quali altri progetti si bloccano?'. Il tool di prima classe per l'orchestrazione cross-progetto — distinto dal grafo-codice.
+        Risolve 'project:artifact:<slug>' e fa l'impact BFS sui soli edge progetto->progetto (depends_on / mentions / refers_to). La response porta il segnale freshness (indexed_sha vs HEAD) per non fidarsi di un indice stantio.
+        QUANDO USARLO: prima di pausare/chiudere/de-prioritizzare un progetto; sequenziare un portafoglio (cosa sblocca cosa); capire le dipendenze cross-progetto di una decisione.
+        RESTITUISCE: {direct_dependents[], transitive_list[], rank_score, freshness}."""
+        try:
+            async with acquire_db() as db:
+                result = await graph_uc.graph_impact(
+                    LOCAL_CTX,
+                    db,
+                    node_id=f"project:artifact:{slug}",
+                    depth=depth,
+                    limit=100,
+                    edge_types=["depends_on", "mentions", "refers_to"],
+                    project=None,
+                )
+                return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
     @mcp.tool()
     async def graph_context(
         node_id: Annotated[str, Field(pattern=_NODE_ID_PATTERN, max_length=256)],
         per_category_limit: Annotated[int, Field(ge=1, le=20)] = 5,
         project: Annotated[str, Field(max_length=50, pattern=_PROJECT_PATTERN)] | None = None,
     ) -> dict[str, Any]:
-        """[Power-user] Rationale chain: function→commit→PR→task→handoff→learning in 1 call — per context su un singolo artefatto usa get_task/get_handoff/get_learning(deep=true). Usa questo tool quando hai un node_id e vuoi la storia completa del PERCHE'.
-        QUANDO USARLO: archeologia di codice legacy ('perche esiste questa function?'); audit trail pre-refactor; linkare codice a decision record.
-        QUANDO NON USARLO: NOT per workflow standard su task/handoff -> usa get_*(deep=true). NOT per vicinato topologico -> usa graph_neighbors.
+        """Rationale chain di un nodo: function/progetto → commit → PR → task → handoff → learning in 1 call. Il PERCHE' dietro qualcosa.
+        QUANDO USARLO: perche' esiste / da dove viene una function o una decisione di progetto; audit trail; linkare codice o progetto a un decision record.
         RESTITUISCE: chain {commits[], PR?, task?, handoffs[], learnings[]} per_category_limit configurabile."""
         try:
             async with acquire_db() as db:
@@ -225,7 +248,7 @@ def register(mcp) -> None:
         scope: Annotated[str, Field(max_length=256)],
         limit: Annotated[int, Field(ge=1, le=100)] = 20,
     ) -> dict[str, Any]:
-        """[Power-user] Learnings scoped a un modulo/path specifico via KG — per learnings generici usa check_learnings. Usa questo tool per learnings chirurgici su un file/modulo specifico prima di toccare codice in quella area.
+        """Learnings scoped a un modulo/path specifico via KG — per learnings generici usa check_learnings. Usa questo tool per learnings chirurgici su un file/modulo specifico prima di toccare codice in quella area.
         QUANDO USARLO: 'quali learnings esistono per api.db?' prima di toccare il DB module; scoping pre-deployment di un servizio specifico.
         QUANDO NON USARLO: NOT per ricerca semantica generica pre-azione -> usa check_learnings. NOT per context di un nodo -> usa graph_context.
         RESTITUISCE: list of {learning_id, title, prevention, severity, scope_match_score}."""
@@ -240,7 +263,7 @@ def register(mcp) -> None:
 
     @mcp.tool()
     async def graph_capabilities() -> dict[str, Any]:
-        """[Power-user] KG schema metadata per agent discovery (edge_types + node_kinds + prefixes + versions).
+        """KG schema metadata per agent discovery (edge_types + node_kinds + prefixes + versions).
         QUANDO USARLO: prima di costruire query graph_* o validare node_id pattern; cold-start agent discovery.
         QUANDO NON USARLO: per query topologiche -> usa graph_neighbors/impact/context.
         RESTITUISCE: {edge_types[], node_kinds[], node_prefixes[], schema_version}.

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/core/api/mcp/tools/learnings.py

@@ -47,10 +47,10 @@ def register(mcp) -> None:
         q: Annotated[str, Field(min_length=1, max_length=500)],
         module: str | None = None,
     ) -> dict[str, Any]:
-        """Search learnings DB (past post-mortems + prevention rules) for a risky action.
+        """Cosa sappiamo gia' / cosa ci ha morso: cerca nei learnings (post-mortem + regole di prevenzione) prima di una decisione o di un'azione.
 
-        QUANDO USARLO: PRIMA di qualunque azione production-affecting (deploy, migration, auth change, push to main, dependency upgrade) — Quality Gate 9.4. BOUNDARY: create_learning vs check_learnings = create scrive nuovo; check cerca rilevante PRE-azione rischiosa. BOUNDARY: check_learnings vs list_learnings = check = semantic match su situazione; list = enumerazione filtrata.
-        QUANDO NON USARLO: NOT quando hai gia' un file/module path e vuoi learnings scoped -> usa graph_pattern. NOT per scrivere un nuovo learning -> usa create_learning.
+        QUANDO USARLO: prima di qualunque azione production-affecting (deploy, migration, auth change, push, dependency upgrade); E prima di una DECISIONE o di un piano (per non ripetere errori noti e riusare cio' che ha funzionato). Non e' solo un gate pre-deploy: e' la memoria istituzionale a cui attingere quando ragioni. BOUNDARY: create_learning scrive nuovo; check_learnings = semantic match sulla situazione; list_learnings = enumerazione filtrata.
+        QUANDO NON USARLO: se hai gia' un file/module path e vuoi learnings scoped -> graph_pattern. Per scrivere un nuovo learning -> create_learning.
         RESTITUISCE: list of {id, title, prevention, severity, module} ranked per rilevanza."""
         try:
             async with acquire_db() as db:

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/core/api/routers/inbox.py

@@ -1,6 +1,7 @@
 # v1.1.0 - 2026-04-14 - Single-writer: reclassify_inbox_items uses get_write_db (batch 5/6)
 from __future__ import annotations
 
+import asyncio
 import logging
 import time
 from collections import defaultdict
@@ -62,6 +63,20 @@ from core.api.services.inbox_triage import (
 
 logger = logging.getLogger(__name__)
 
+
+# Strong refs to fire-and-forget on-read deep-research sweeps so the event loop
+# does not garbage-collect them mid-flight; discarded when each completes.
+_background_sweeps: set[asyncio.Task] = set()
+
+
+def _on_sweep_done(task: asyncio.Task) -> None:
+    _background_sweeps.discard(task)
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is not None:
+        logger.warning("on-read digest deep-research sweep failed: %s", exc)
+
 router = APIRouter(prefix="/api/v1/inbox", tags=["inbox"])
 
 # ---------------------------------------------------------------------------
@@ -306,13 +321,26 @@ async def get_current_digest_items(
     db: aiosqlite.Connection = Depends(get_db),
 ) -> list[dict]:
     workspace_id = user.workspace_id or "ws_default"
-    return await list_digest_items(
+    items = await list_digest_items(
         db,
         workspace_id,
         state="visible",
         domain_key=domain_key,
         limit=limit,
     )
+    # On-read safety net (A): kick off deepening of any visible item still
+    # missing deep research, non-blocking, so it is ready by the time the user
+    # opens it. Idempotent + lock-guarded (no overlap with the scheduler sweep).
+    from core.api.services.inbox_digest_deep_research import (
+        sweep_visible_missing_deep_research,
+    )
+
+    sweep_task = asyncio.create_task(
+        sweep_visible_missing_deep_research(workspace_id=workspace_id)
+    )
+    _background_sweeps.add(sweep_task)
+    sweep_task.add_done_callback(_on_sweep_done)
+    return items
 
 
 @router.get("/digest/overflow")

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/core/api/routers/learnings.py

@@ -46,6 +46,8 @@ from core.api.use_cases.learnings import (  # noqa: F401  (re-export surface)
     VALID_CATEGORIES,
     VALID_SEVERITIES,
     LearningCheckResponse,
+    LearningHistoryLink,
+    LearningHistoryResponse,
     LearningResponse,
     _extract_check_terms,
     _learning_match_score,
@@ -158,13 +160,20 @@ async def check_learnings(
         None, description="Filter by module (exact or LIKE match)"
     ),
     deep: bool = Query(False, description="Attach KG context to each result (Phase 7.0)"),
+    as_of: str | None = Query(
+        None,
+        description=(
+            "Point-in-time audit (Track 2 #1). ISO timestamp; returns learnings live "
+            "at that instant. Only effective when MARVIS_TEMPORAL_MEMORY is enabled."
+        ),
+    ),
     user: UserInfo = Depends(get_current_user_or_agent),
     db: aiosqlite.Connection = Depends(get_db),
 ) -> LearningCheckResponse:
     """Search learnings relevant to a keyword/module. Used by MCP before risky actions."""
     ctx = CallerContext.from_user_info(user, is_human_session=False)
     try:
-        result = await uc.check_learnings(ctx, db, query=q, module=module)
+        result = await uc.check_learnings(ctx, db, query=q, module=module, as_of=as_of)
     except ServiceError as e:
         raise to_http(e)
 
@@ -194,6 +203,13 @@ async def list_learnings(
     limit: int = Query(50, ge=1, le=200),
     offset: int = Query(0, ge=0),
     deep: bool = Query(False, description="Attach KG context (aggregate deferred to Phase 7.1)"),
+    as_of: str | None = Query(
+        None,
+        description=(
+            "Point-in-time audit (Track 2 #1). ISO timestamp; lists learnings live "
+            "at that instant. Only effective when MARVIS_TEMPORAL_MEMORY is enabled."
+        ),
+    ),
     user: UserInfo = Depends(get_current_user_or_agent),
     db: aiosqlite.Connection = Depends(get_db),
 ) -> list[LearningResponse]:
@@ -225,22 +241,49 @@ async def list_learnings(
             limit=limit,
             offset=offset,
             visible_projects=visible_projects,
+            as_of=as_of,
         )
     except ServiceError as e:
         raise to_http(e)
 
 
+@router.get("/{learning_id}/history", response_model=LearningHistoryResponse)
+async def get_learning_history(
+    learning_id: str,
+    user: UserInfo = Depends(get_current_user_or_agent),
+    db: aiosqlite.Connection = Depends(get_db),
+) -> LearningHistoryResponse:
+    """Walk a learning's supersede chain (Track 2 #1 audit trail, READ-ONLY).
+
+    Returns every link (the row + each ``superseded_by`` hop) with valid_from /
+    invalid_at / supersede_reason. Always walks the full chain regardless of the
+    ``MARVIS_TEMPORAL_MEMORY`` flag — this is the deliberate audit surface.
+    """
+    ctx = CallerContext.from_user_info(user, is_human_session=False)
+    try:
+        return await uc.get_learning_history(ctx, db, learning_id=learning_id)
+    except ServiceError as e:
+        raise to_http(e)
+
+
 @router.get("/{learning_id}", response_model=LearningResponse)
 async def get_learning(
     learning_id: str,
     deep: bool = Query(False, description="Attach KG context (Phase 7.0)"),
+    as_of: str | None = Query(
+        None,
+        description=(
+            "Point-in-time audit (Track 2 #1). ISO timestamp; returns the row iff it "
+            "was live at that instant. Only effective when MARVIS_TEMPORAL_MEMORY is enabled."
+        ),
+    ),
     user: UserInfo = Depends(get_current_user_or_agent),
     db: aiosqlite.Connection = Depends(get_db),
 ) -> LearningResponse:
     """Get a single learning by ID."""
     ctx = CallerContext.from_user_info(user, is_human_session=False)
     try:
-        result = await uc.get_learning(ctx, db, learning_id=learning_id)
+        result = await uc.get_learning(ctx, db, learning_id=learning_id, as_of=as_of)
     except ServiceError as e:
         raise to_http(e)
 

{marvisx_cli-0.3.7b3 → marvisx_cli-0.3.8b2}/core/api/routers/search.py

@@ -96,6 +96,14 @@ async def search(
         description="True (default): RRF fusion semantic + KG FTS5. False: semantic-only (legacy v1.5 behavior).",
     ),
     limit: int = Query(20, ge=1, le=50),
+    as_of: str | None = Query(
+        None,
+        description=(
+            "Point-in-time audit (Track 2 #1). ISO timestamp; reconstructs the "
+            "learnings live at that instant. Only effective when "
+            "MARVIS_TEMPORAL_MEMORY is enabled; ignored otherwise."
+        ),
+    ),
     user: UserInfo = Depends(get_current_user_or_agent),
 ) -> SearchResponse:
     """Hybrid (default) or semantic search across the KG and embedding index."""
@@ -104,7 +112,7 @@ async def search(
 
     ctx = CallerContext.from_user_info(user, is_human_session=False)
     try:
-        return await uc.search(ctx, q=q, hybrid=hybrid, limit=limit)
+        return await uc.search(ctx, q=q, hybrid=hybrid, limit=limit, as_of=as_of)
     except ServiceError as e:
         raise to_http(e)