feat: route mine through the source-adapter registry (--source)

Wire `cmd_mine` to the RFC 002 source-adapter registry: when `--source NAME`
resolves a registered adapter, mine runs its `ingest()` and files each
`DrawerRecord` through a `PalaceContext` (the §1.2 incremental loop, under the
palace lock). Opt-in and non-breaking — absent `--source`, the legacy `--mode`
dispatch runs unchanged. This wires the seam RFC 002 §3.3/§9 reserve; the
scaffolding (BaseSourceAdapter, registry, PalaceContext) was already complete.

Adds `_mine_via_source_adapter`, the `--source` flag, and a conformance test
(registry-routes-and-files / dry-run / unknown-adapter-exits).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: joshuafontany

mempalace/cli.py

@@ -545,6 +545,79 @@ def _maybe_run_mine_after_init(args, cfg) -> None:
         sys.exit(1)
 
 
+def _mine_via_source_adapter(args, palace_path):
+    """Route ``mine --source NAME`` through the RFC 002 source-adapter registry.
+
+    Opt-in seam: when an explicit ``--source`` names a registered adapter, mine
+    resolves it from ``mempalace.sources.registry``, runs its ``ingest()``, and
+    files each ``DrawerRecord`` through a ``PalaceContext``. When no ``--source``
+    is given, ``cmd_mine`` keeps its legacy ``--mode`` dispatch — the
+    filesystem/conversations miners have not moved onto the contract yet, so the
+    registry path stays opt-in and changes no existing behavior. This wires the
+    registry the spec reserves.
+    """
+    from .knowledge_graph import KnowledgeGraph
+    from .palace import MineAlreadyRunning, get_collection, mine_palace_lock
+    from .sources.base import DrawerRecord, SourceItemMetadata, SourceRef
+    from .sources.context import PalaceContext
+    from .sources.registry import get_adapter, resolve_adapter_for_source
+
+    name = resolve_adapter_for_source(explicit=args.source)
+    try:
+        adapter = get_adapter(name)
+    except KeyError as exc:
+        print(f"mempalace: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+    # Routing precedence (§2.5): explicit --wing flows to the adapter via
+    # SourceRef.options; the adapter honors it. Secrets never go here (§2.2).
+    options = {}
+    if getattr(args, "wing", None):
+        options["wing"] = args.wing
+    ref = SourceRef(local_path=os.path.abspath(os.path.expanduser(args.dir)), options=options)
+
+    filed = 0
+    skipped = 0
+    try:
+        with mine_palace_lock(palace_path):
+            collection = get_collection(palace_path, create=True)
+            kg = KnowledgeGraph(db_path=os.path.join(palace_path, "knowledge_graph.sqlite3"))
+            ctx = PalaceContext(
+                drawer_collection=collection,
+                knowledge_graph=kg,
+                palace_path=palace_path,
+                config=MempalaceConfig(),
+                adapter_name=getattr(adapter, "name", name),
+                adapter_version=getattr(adapter, "adapter_version", ""),
+            )
+
+            skip_item = False
+            for result in adapter.ingest(source=ref, palace=ctx):
+                if isinstance(result, SourceItemMetadata):
+                    skip_item = False
+                    ctx._skip_requested = False
+                    existing = collection.get(where={"source_file": result.source_file}, limit=1)
+                    metas = (existing or {}).get("metadatas") or []
+                    if adapter.is_current(item=result, existing_metadata=metas[0] if metas else None):
+                        ctx.skip_current_item()
+                        skip_item = True
+                elif isinstance(result, DrawerRecord):
+                    if skip_item or ctx._skip_requested:
+                        skipped += 1
+                        continue
+                    if not args.dry_run:
+                        ctx.upsert_drawer(result)
+                    filed += 1
+            adapter.close()
+    except MineAlreadyRunning as exc:
+        print(f"mempalace: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    verb = "Would file" if args.dry_run else "Drawers filed:"
+    tail = f"  (skipped {skipped} up-to-date)" if skipped else ""
+    print(f"  source={name}  {verb} {filed}{tail}")
+
+
 def cmd_mine(args):
     palace_path = os.path.expanduser(args.palace) if args.palace else MempalaceConfig().palace_path
     include_ignored = []
@@ -555,6 +628,10 @@ def cmd_mine(args):
         print("mempalace: --background requires --daemon", file=sys.stderr)
         sys.exit(2)
 
+    if getattr(args, "source", None) and getattr(args, "daemon", False):
+        print("mempalace: --source does not support --daemon yet", file=sys.stderr)
+        sys.exit(2)
+
     if getattr(args, "daemon", False):
         payload = {
             "source": args.dir,
@@ -582,6 +659,12 @@ def cmd_mine(args):
             llm_provider=None,
         )
 
+    # RFC 002 source-adapter seam: an explicit --source routes mine through the
+    # registry; absent it, the legacy --mode dispatch below runs unchanged.
+    if getattr(args, "source", None):
+        _mine_via_source_adapter(args, palace_path)
+        return
+
     from .palace import MineAlreadyRunning, MineValidationError
 
     try:
@@ -1813,6 +1896,16 @@ def main():
             "mempalace[extract])"
         ),
     )
+    p_mine.add_argument(
+        "--source",
+        default=None,
+        metavar="NAME",
+        help=(
+            "RFC 002 source adapter to mine through (e.g. a third-party "
+            "mempalace-source-<name> package). Explicit selection only — no "
+            "auto-detect. Omit to use the legacy --mode dispatch."
+        ),
+    )
     p_mine.add_argument("--wing", default=None, help="Wing name (default: directory name)")
     p_mine.add_argument(
         "--no-gitignore",

tests/test_mine_source_registry.py

@@ -0,0 +1,90 @@
+"""RFC 002 source-adapter CLI seam: ``mine --source NAME`` routes through the
+registry and files adapter-authored ``DrawerRecord``s via ``PalaceContext``.
+
+This covers the seam wired into ``cmd_mine`` — the registry/ingest-loop path is
+opt-in and leaves the legacy ``--mode`` dispatch untouched.
+"""
+
+from __future__ import annotations
+
+from argparse import Namespace
+from typing import Iterator
+
+import pytest
+
+from mempalace.sources.base import (
+    AdapterSchema,
+    BaseSourceAdapter,
+    DrawerRecord,
+    FieldSpec,
+    IngestResult,
+    SourceItemMetadata,
+    SourceRef,
+)
+from mempalace.sources.registry import register, reset_adapters, unregister
+
+
+class _FakeAdapter(BaseSourceAdapter):
+    name = "fake-test"
+    adapter_version = "0.1.0"
+    capabilities = frozenset({"byte_preserving"})
+    supported_modes = frozenset({"whole_record"})
+    declared_transformations = frozenset()
+    default_privacy_class = "internal"
+
+    def ingest(self, *, source: SourceRef, palace) -> Iterator[IngestResult]:
+        yield SourceItemMetadata(source_file="fake://item/1", version="v1")
+        yield DrawerRecord(
+            content="the operator said the verb leads",
+            source_file="fake://item/1",
+            metadata={"wing": "wing_test", "room": "general", "lar_demo": "1"},
+        )
+
+    def describe_schema(self) -> AdapterSchema:
+        return AdapterSchema(
+            version="1.0",
+            fields={"lar_demo": FieldSpec(type="string", required=False, description="demo field")},
+        )
+
+
+@pytest.fixture
+def _fake_adapter():
+    register("fake-test", _FakeAdapter)
+    yield
+    reset_adapters()
+    unregister("fake-test")
+
+
+def test_mine_source_files_pre_annotated_record(tmp_dir, palace_path, _fake_adapter):
+    from mempalace.cli import _mine_via_source_adapter
+    from mempalace.palace import get_collection
+
+    args = Namespace(source="fake-test", dir=tmp_dir, wing=None, dry_run=False)
+    _mine_via_source_adapter(args, palace_path)
+
+    col = get_collection(palace_path, create=True)
+    got = col.get(where={"source_file": "fake://item/1"})
+    assert got["documents"] == ["the operator said the verb leads"]
+    meta = got["metadatas"][0]
+    assert meta["lar_demo"] == "1"  # adapter-authored metadata lands verbatim
+    assert meta["adapter_name"] == "fake-test"  # stamped by PalaceContext, not by the adapter
+    assert meta["adapter_version"] == "0.1.0"
+
+
+def test_mine_source_dry_run_files_nothing(tmp_dir, palace_path, _fake_adapter):
+    from mempalace.cli import _mine_via_source_adapter
+    from mempalace.palace import get_collection
+
+    args = Namespace(source="fake-test", dir=tmp_dir, wing=None, dry_run=True)
+    _mine_via_source_adapter(args, palace_path)
+
+    col = get_collection(palace_path, create=True)
+    assert col.get(where={"source_file": "fake://item/1"})["ids"] == []
+
+
+def test_mine_source_unknown_adapter_exits(tmp_dir, palace_path):
+    from mempalace.cli import _mine_via_source_adapter
+
+    args = Namespace(source="does-not-exist", dir=tmp_dir, wing=None, dry_run=False)
+    with pytest.raises(SystemExit):
+        _mine_via_source_adapter(args, palace_path)