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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marvisx-cli
-Version: 0.3.7b3
+Version: 0.3.8b1
 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.8b1}/core/api/config.py

@@ -439,6 +439,55 @@ 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"
+    )
+
+    # 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.8b1}/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.8b1}/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)
 

marvisx_cli-0.3.8b1/core/api/services/chunking.py

@@ -0,0 +1,277 @@
+# v1.0.0 - 2026-06-04 - Track 2 #4: fixed-size prose chunker (flag MARVIS_CHUNKING)
+"""Pure, model-free fixed-size prose chunker (Track 2 #4).
+
+Splits a prose document into fixed-size, overlapping, sentence-aware windows
+BEFORE it is embedded, so a long handoff/plan no longer collapses to a single
+over-compressed CLS vector (the embedder is a 32k-context ModernBert with CLS
+pooling — there is no truncation pressure, the motivation is over-compression,
+not truncation; see the roadmap "Research Insights — #4").
+
+Design constraints (all load-bearing):
+
+* **Model-free + pure.** No ONNX session, no model load, no I/O. The only
+  dependency is a *tokenizer* injected by the caller (``tokenizer`` param), so
+  this is unit-testable with a FAKE tokenizer and the real path reuses Granite's
+  already-loaded Rust ``tokenizers.Tokenizer`` (no second tokenizer, no second
+  model). The tokenizer is only asked for ``encode(text)`` exposing ``.ids`` and
+  ``.offsets`` (per-token ``(char_start, char_end)`` into the ORIGINAL string —
+  exactly what the Rust ``tokenizers`` package returns).
+* **UTF-8 BYTE offsets.** ``span_start`` / ``span_end`` are byte offsets into the
+  original text encoded as UTF-8, NOT character indices. Byte offsets round-trip
+  losslessly through multibyte Italian accents (à/è/ù) for the #2 span-citation
+  layer: ``text.encode("utf-8")[span_start:span_end].decode("utf-8")`` reproduces
+  the chunk content exactly.
+* **Sentence-aware.** Window edges snap to the nearest sentence boundary within a
+  ``±boundary_slack_tokens`` slack, so a chunk rarely cuts mid-sentence. The
+  splitter is a punkt-lite regex (no spaCy / nltk — those are host-pressure wheel
+  bloat; at ~15% overlap an imperfect boundary heals across the overlap).
+* **Per-chunk content hash.** ``content_hash`` = sha256 of the chunk's byte span,
+  so a re-index re-embeds only the chunks that actually changed (editing one
+  paragraph churns ~1-2 chunks, not the whole doc).
+
+Scope: PROSE ONLY. Code is already chunked per-symbol in
+``core/cli/_index_source.py`` (``_embed_symbols``); a token windower over code
+would split mid-symbol and break the KG anchors. This module is never invoked on
+code.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+from typing import Protocol, Sequence, runtime_checkable
+
+__all__ = [
+    "Chunk",
+    "TokenizerLike",
+    "chunk_prose",
+    "DEFAULT_TARGET_TOKENS",
+    "DEFAULT_OVERLAP_TOKENS",
+]
+
+# Mirror of the F2 EMBEDDING_* knobs: defaults chosen for retrieval precision
+# (recall peaks ~400 tokens per the Chroma/firecrawl ablation), ~15% overlap.
+DEFAULT_TARGET_TOKENS = 400
+DEFAULT_OVERLAP_TOKENS = 64
+DEFAULT_BOUNDARY_SLACK_TOKENS = 32
+
+
+@dataclass(frozen=True, slots=True)
+class Chunk:
+    """One prose chunk.
+
+    ``span_start`` / ``span_end`` are UTF-8 BYTE offsets into the ORIGINAL text
+    (half-open ``[start, end)``). ``content_hash`` is the sha256 hex of the chunk
+    byte span — the idempotency key (re-embed only changed chunks).
+    """
+
+    chunk_idx: int
+    span_start: int
+    span_end: int
+    content_hash: str
+
+
+@runtime_checkable
+class TokenizerLike(Protocol):
+    """Minimal surface of the Rust ``tokenizers.Tokenizer`` this chunker needs.
+
+    The real Granite tokenizer (``tokenizers.Tokenizer.from_file(...)``) satisfies
+    this: ``encode(text)`` returns an ``Encoding`` whose ``.offsets`` is a list of
+    ``(char_start, char_end)`` tuples — one per token — into the ORIGINAL string.
+    A FAKE tokenizer in tests implements the same two attributes, so the chunker
+    is exercised with zero model load.
+    """
+
+    def encode(self, text: str) -> "EncodingLike": ...
+
+
+@runtime_checkable
+class EncodingLike(Protocol):
+    ids: Sequence[int]
+    # (char_start, char_end) per token, into the ORIGINAL (unencoded) string.
+    offsets: Sequence[tuple[int, int]]
+
+
+# Punkt-lite sentence splitter: a boundary is sentence-final punctuation
+# (. ! ? plus their typographic variants … ; and the IT/EN newline) followed by
+# whitespace. Intentionally simple — overlap heals the misses (an abbreviation
+# like "es." that splits early is recovered in the next window's prefix).
+_SENTENCE_END = re.compile(r"[.!?…;\n]+[\s\"')\]]*")
+
+
+def _utf8_byte_offsets(text: str) -> list[int]:
+    """Map char index -> UTF-8 byte offset (length == len(text) + 1).
+
+    ``out[i]`` = byte offset where character ``i`` starts; ``out[len(text)]`` =
+    total byte length. Computed once per doc so char→byte conversion of every
+    token offset is O(1). Multibyte-safe: an accented char advances the byte
+    cursor by its UTF-8 width (2 for à/è/ù), so byte spans round-trip losslessly.
+    """
+    out = [0] * (len(text) + 1)
+    byte = 0
+    for i, ch in enumerate(text):
+        out[i] = byte
+        byte += len(ch.encode("utf-8"))
+    out[len(text)] = byte
+    return out
+
+
+def _sentence_boundary_chars(text: str) -> list[int]:
+    """Character indices that are sentence boundaries (end of a sentence).
+
+    Returns the char index just AFTER each sentence-final punctuation run (i.e. a
+    valid place to start the next chunk). Always includes 0 and len(text) so the
+    snap logic has terminal anchors.
+    """
+    bounds = {0, len(text)}
+    for m in _SENTENCE_END.finditer(text):
+        bounds.add(m.end())
+    return sorted(bounds)
+
+
+def _snap_to_boundary(
+    token_char_pos: int,
+    boundaries: Sequence[int],
+    *,
+    text_char_pos_window: tuple[int, int],
+    slack_chars: int,
+) -> int:
+    """Snap a proposed cut (char index) to the nearest sentence boundary in slack.
+
+    ``token_char_pos`` is the char index the token-window would cut at. If a
+    sentence boundary lies within ``±slack_chars`` AND inside the allowed window
+    ``text_char_pos_window`` (so we never snap past the doc edge or before the
+    chunk start), use the closest one; otherwise keep the token cut (hard split).
+    """
+    lo, hi = text_char_pos_window
+    best = token_char_pos
+    best_dist = slack_chars + 1
+    for b in boundaries:
+        if b < lo or b > hi:
+            continue
+        dist = abs(b - token_char_pos)
+        if dist <= slack_chars and dist < best_dist:
+            best = b
+            best_dist = dist
+    return best
+
+
+def chunk_prose(
+    text: str,
+    tokenizer: TokenizerLike,
+    *,
+    target_tokens: int = DEFAULT_TARGET_TOKENS,
+    overlap_tokens: int = DEFAULT_OVERLAP_TOKENS,
+    boundary_slack_tokens: int = DEFAULT_BOUNDARY_SLACK_TOKENS,
+) -> list[Chunk]:
+    """Split ``text`` into fixed-size, overlapping, sentence-aware prose chunks.
+
+    Windowing is in TOKEN space (reusing the injected tokenizer's per-token char
+    offsets), so the window size is stable across mixed IT/EN text where char
+    windows over/under-fill. Each window edge is snapped to the nearest sentence
+    boundary within ``±boundary_slack_tokens`` (converted to a char slack via the
+    local token density). Span offsets are emitted as UTF-8 BYTE offsets.
+
+    Returns ``[]`` for empty/whitespace-only input. A short doc (<= target_tokens)
+    yields a single chunk covering the whole byte range.
+    """
+    if not text or not text.strip():
+        return []
+    if target_tokens <= 0:
+        raise ValueError("target_tokens must be > 0")
+    if overlap_tokens < 0 or overlap_tokens >= target_tokens:
+        # overlap must leave forward progress; clamp defensively rather than loop.
+        overlap_tokens = max(0, min(overlap_tokens, target_tokens - 1))
+
+    enc = tokenizer.encode(text)
+    offsets = list(enc.offsets)
+    n_tokens = len(offsets)
+    byte_at = _utf8_byte_offsets(text)
+    total_bytes = byte_at[len(text)]
+
+    # Degenerate: tokenizer produced no usable offsets → one chunk, whole doc.
+    if n_tokens == 0:
+        return [
+            Chunk(
+                chunk_idx=0,
+                span_start=0,
+                span_end=total_bytes,
+                content_hash=_hash_byte_span(text, 0, total_bytes),
+            )
+        ]
+
+    boundaries = _sentence_boundary_chars(text)
+    stride = target_tokens - overlap_tokens  # > 0 (overlap clamped above)
+
+    # Mean chars/token for this doc → convert the token-space slack to char slack
+    # for the boundary snap (the boundary list is in char space).
+    mean_chars_per_token = max(1.0, len(text) / n_tokens)
+    slack_chars = int(round(boundary_slack_tokens * mean_chars_per_token))
+
+    chunks: list[Chunk] = []
+    chunk_idx = 0
+    tok_start = 0
+    while tok_start < n_tokens:
+        tok_end = min(tok_start + target_tokens, n_tokens)
+
+        # Char window for THIS chunk: start at the first token's char-start, end
+        # at the last covered token's char-end.
+        char_start = offsets[tok_start][0]
+        char_end = offsets[tok_end - 1][1]
+
+        is_last = tok_end >= n_tokens
+
+        # Snap the chunk START to a sentence boundary at/just-before it (only when
+        # this is NOT the first chunk — chunk 0 must begin at 0 to cover the head).
+        if chunk_idx > 0:
+            char_start = _snap_to_boundary(
+                char_start,
+                boundaries,
+                text_char_pos_window=(0, char_end),
+                slack_chars=slack_chars,
+            )
+
+        # Snap the chunk END to a sentence boundary near it (never on the last
+        # chunk — the tail must reach len(text) so no bytes are dropped).
+        if not is_last:
+            char_end = _snap_to_boundary(
+                char_end,
+                boundaries,
+                text_char_pos_window=(char_start + 1, len(text)),
+                slack_chars=slack_chars,
+            )
+
+        span_start = byte_at[char_start]
+        span_end = byte_at[char_end] if not is_last else total_bytes
+
+        if span_end > span_start:
+            chunks.append(
+                Chunk(
+                    chunk_idx=chunk_idx,
+                    span_start=span_start,
+                    span_end=span_end,
+                    content_hash=_hash_byte_span(text, span_start, span_end),
+                )
+            )
+            chunk_idx += 1
+
+        if is_last:
+            break
+        tok_start += stride
+
+    return chunks
+
+
+def _hash_byte_span(text: str, span_start: int, span_end: int) -> str:
+    """sha256 of the chunk's UTF-8 byte span (the per-chunk idempotency key)."""
+    raw = text.encode("utf-8")[span_start:span_end]
+    return hashlib.sha256(raw).hexdigest()
+
+
+def chunk_text_bytes(text: str, span_start: int, span_end: int) -> bytes:
+    """Round-trip helper: the exact bytes a chunk's byte span refers to.
+
+    ``chunk_text_bytes(text, c.span_start, c.span_end).decode("utf-8")`` is the
+    chunk content (used by the #2 citation resolver and by the round-trip test).
+    """
+    return text.encode("utf-8")[span_start:span_end]

marvisx_cli-0.3.8b1/core/api/services/dream_cycle.py

@@ -0,0 +1,213 @@
+# v1.0.0 - 2026-06-05 - Track 2 #1-S5: nightly dream-cycle consolidation (SHADOW/dry-run)
+"""Nightly dream-cycle consolidation — SHADOW / dry-run only (Track 2 #1-S5).
+
+Plan ``docs/plans/2026-06-04-track2-engine-moat-roadmap-plan.md`` (#1, sub-increment
+S5, lines 343/350). This is the *batch* analogue of the S3 write-time gate. Where S3
+decides ADD / NOOP / SUPERSEDE_CANDIDATE for ONE just-inserted learning, the dream
+cycle scans the WHOLE live learnings store and, for each near-match pair in the
+supersede band, writes a pending SUPERSEDE_CANDIDATE proposal into the SAME approval
+gate the brain cycle drains (``brain_memory_operations``, mig 129).
+
+DRY-RUN, NON-NEGOTIABLE. This module is SHADOW only — it ``propose``s, it NEVER
+``apply``s:
+  * it NEVER calls :func:`temporal_write.apply_supersede`;
+  * it NEVER sets ``invalid_at`` / ``superseded_by`` on any row;
+  * it NEVER deletes a learning (no NOOP-style hard-remove like the write path does).
+The verdict surfaces ONLY as a pending proposal for the human/Triage gate. Diffing
+those proposals against the gold set (and only then enabling an auto-apply
+high-confidence tier) is a deliberate, eval-gated, OFF-host follow-up — see plan
+lines 341/343.
+
+Reuses S3 verbatim (does NOT modify ``temporal_write`` / ``learnings``):
+  * :func:`temporal_write.decide_write_action` + the pinned 0.80 / 0.97 bands;
+  * :func:`temporal_write.propose_supersede_candidate` (the ``INSERT OR IGNORE`` on a
+    stable BLAKE2b ``operation_id`` is what makes a re-run idempotent — no duplicate
+    proposals);
+  * default vector source = :func:`temporal_write.fetch_learning_vector` +
+    :func:`temporal_write.fetch_live_neighbor_vectors`, which read PRE-COMPUTED
+    vectors back from the search-index mirror. **NO embedding model is EVER run.**
+
+Flag gate: the SAME ``settings.temporal_memory_enabled`` (alias
+``MARVIS_TEMPORAL_MEMORY``, default False). When OFF, :func:`run_dream_cycle_shadow`
+is a no-op that returns an empty report and scans nothing.
+
+Host-safety + testability: the neighbour/vector source is INJECTABLE via the
+``neighbor_provider`` callable. Tests pass FAKE vectors of known cosine through it,
+so the unit suite needs neither sqlite-vec nor a model. The default provider only
+reads mirrored bytes — still model-free.
+
+What this module deliberately does NOT do: it does NOT build or run a real nightly
+scheduler (cron/launchd), and it does NOT run a real cycle over the prod store.
+Wiring this STEP to the nightly schedule and flipping the (default-off)
+warehouse-consolidation pass on are separate, eval-gated, off-host steps. This is the
+pure batch step + its dry-run guarantee, unit-testable in isolation.
+"""
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+
+import aiosqlite
+
+from core.api.config import settings
+from core.api.services import temporal_write as tw
+
+# A neighbour provider resolves, for a given live learning id, the pair
+# ``(its_vector, [(neighbor_id, neighbor_vector), ...])`` that the PURE band decision
+# consumes. ``None`` for the vector means "no mirrored embedding yet" → skip that row
+# (mirrors the S3 write-path fallback: stay ADD, catch it on a later run). Injectable
+# so tests feed FAKE vectors and the default reads mirrored bytes — neither runs a model.
+NeighborProvider = Callable[
+    [aiosqlite.Connection, str, str],
+    Awaitable[tuple[list[float] | None, list[tuple[str, list[float]]]]],
+]
+
+
+@dataclass(frozen=True)
+class DreamCycleReport:
+    """Outcome of one SHADOW dream-cycle pass.
+
+    ``scanned``  — live learnings examined (``invalid_at IS NULL``).
+    ``proposed`` — DISTINCT supersede-candidate pairs proposed this pass (the pair is
+                   canonicalised by id, so the reverse-direction scan of the same pair
+                   does NOT double-count). On a fresh store this equals the rows added
+                   to the gate; on a re-run the gate's ``INSERT OR IGNORE`` on a stable
+                   ``operation_id`` keeps it duplicate-free, so re-running adds zero
+                   gate rows even though it re-proposes (``proposed`` may be > 0 again).
+    ``skipped``  — scanned learnings that produced NO new proposal: no mirrored vector
+                   yet, no neighbours, a non-band verdict (ADD / NOOP), or the closest
+                   neighbour forms a pair already proposed earlier in THIS pass.
+
+    Invariant: ``scanned == proposed + skipped``.
+    """
+
+    scanned: int
+    proposed: int
+    skipped: int
+
+
+async def _default_neighbor_provider(
+    db: aiosqlite.Connection,
+    workspace_id: str,
+    learning_id: str,
+) -> tuple[list[float] | None, list[tuple[str, list[float]]]]:
+    """Default vector source — reads PRE-COMPUTED vectors back. NEVER runs a model.
+
+    Mirrors the S3 write path exactly: pull the learning's own mirrored vector, then
+    its top-k LIVE (``invalid_at IS NULL``) neighbours via sqlite-vec kNN. Returns
+    ``(None, [])`` when the mirror isn't present yet so the caller skips the row.
+    """
+    new_vec = await tw.fetch_learning_vector(db, learning_id)
+    if new_vec is None:
+        return None, []
+    neighbors = await tw.fetch_live_neighbor_vectors(
+        db, workspace_id, new_vec, exclude_learning_id=learning_id
+    )
+    return new_vec, neighbors
+
+
+async def _live_learning_ids(
+    db: aiosqlite.Connection, workspace_id: str
+) -> list[tuple[str, str | None]]:
+    """All LIVE learnings (``invalid_at IS NULL``) for the workspace: (id, project).
+
+    Workspace-scoped with the same ``COALESCE(workspace_id, 'ws_default')`` default as
+    the S3 neighbour fetch, so a row and its neighbours live in one scope. Stable order
+    so a re-run walks the store identically.
+    """
+    cur = await db.execute(
+        """
+        SELECT id, project
+        FROM learnings
+        WHERE invalid_at IS NULL
+          AND COALESCE(workspace_id, 'ws_default') = ?
+        ORDER BY id
+        """,
+        [workspace_id],
+    )
+    rows = await cur.fetchall()
+    return [(row["id"], row["project"]) for row in rows]
+
+
+async def run_dream_cycle_shadow(
+    db: aiosqlite.Connection,
+    workspace_id: str,
+    *,
+    neighbor_provider: NeighborProvider | None = None,
+) -> DreamCycleReport:
+    """Scan the full LIVE learnings store and PROPOSE supersede candidates. DRY-RUN.
+
+    For each live learning, resolve ``(its_vector, live_neighbours)`` via the injected
+    ``neighbor_provider`` (default = mirrored-vector reader, no model), run the PURE
+    two-band cosine :func:`temporal_write.decide_write_action`, and on a
+    ``SUPERSEDE_CANDIDATE`` verdict write ONE pending proposal into the existing
+    approval gate via :func:`temporal_write.propose_supersede_candidate`.
+
+    SHADOW guarantee: this only ever PROPOSES. It NEVER calls ``apply_supersede``,
+    NEVER stamps ``invalid_at`` / ``superseded_by``, NEVER deletes a row — not even on
+    a NOOP verdict (the write path retires a brand-new duplicate; a batch pass over the
+    persisted store must not, so NOOP here is a skip).
+
+    Idempotency: the (old, new) pair is canonicalised by sorted id BEFORE proposing, so
+    scanning A→B and later B→A target the SAME proposal. Combined with
+    ``propose_supersede_candidate``'s stable ``operation_id`` + ``INSERT OR IGNORE``, a
+    re-run adds zero duplicate rows to the gate.
+
+    Flag OFF (``settings.temporal_memory_enabled`` False): no-op — returns an empty
+    report and scans nothing.
+    """
+    if not settings.temporal_memory_enabled:
+        return DreamCycleReport(scanned=0, proposed=0, skipped=0)
+
+    provider = neighbor_provider or _default_neighbor_provider
+
+    scanned = 0
+    proposed = 0
+    skipped = 0
+    seen_pairs: set[tuple[str, str]] = set()
+
+    for learning_id, project in await _live_learning_ids(db, workspace_id):
+        scanned += 1
+
+        new_vec, neighbors = await provider(db, workspace_id, learning_id)
+        if new_vec is None or not neighbors:
+            skipped += 1
+            continue
+
+        decision = tw.decide_write_action(new_vec, neighbors)
+        if (
+            decision.action is not tw.WriteAction.SUPERSEDE_CANDIDATE
+            or decision.neighbor_id is None
+        ):
+            # ADD (distinct) / NOOP (near-dup) verdicts produce no proposal in shadow.
+            skipped += 1
+            continue
+
+        # Canonicalise the pair by id so A→B and B→A collapse to ONE proposal. The
+        # in-run ``seen_pairs`` guard makes ``proposed`` count DISTINCT pairs this pass
+        # (the reverse-direction scan is a skip, not a second proposal); the persisted
+        # gate is *also* dedup'd by propose_supersede_candidate's stable operation_id +
+        # INSERT OR IGNORE, so a re-run across passes adds nothing either.
+        pair = tuple(sorted((learning_id, decision.neighbor_id)))
+        if pair in seen_pairs:
+            skipped += 1
+            continue
+        seen_pairs.add(pair)
+
+        a, b = pair
+        score = decision.score if decision.score is not None else 0.0
+        await tw.propose_supersede_candidate(
+            db,
+            old_id=a,
+            new_id=b,
+            score=score,
+            summary=(
+                f"Dream-cycle near-match between learnings '{a}' and '{b}' "
+                f"(cosine={score:.4f}) — confirm supersede or keep both."
+            ),
+            project=project,
+        )
+        proposed += 1
+
+    await db.commit()
+    return DreamCycleReport(scanned=scanned, proposed=proposed, skipped=skipped)