refactor: unify data preparations and research input snapshots

backend/app/research_access/contracts.py

@@ -7,6 +7,7 @@ from pydantic import Field, model_validator
 
 from ..backtests.contracts import Candidate, SimulationSettings
 from ..catalog.contracts import CatalogFilters, Scope
+from ..preparations.contracts import PreparationReference
 from ..research.workspace_contracts import TemplateSpec
 from ..schemas import Contract
 
@@ -54,8 +55,24 @@ class Provenance(Contract):
     parent_run_id: RunId | None = None
 
 
+class PreparationSearch(Contract):
+    q: str = Field(default="", max_length=300)
+    scope_key: str | None = None
+    limit: int = Field(default=25, ge=1, le=100)
+    offset: int = Field(default=0, ge=0)
+
+
+class PreparationRead(Contract):
+    id: str = Field(min_length=1, max_length=36)
+    version: int = Field(ge=1)
+    q: str = Field(default="", max_length=300)
+    limit: int = Field(default=25, ge=1, le=100)
+    offset: int = Field(default=0, ge=0)
+
+
 class Submit(Contract):
     name: str = Field(min_length=1, max_length=200)
+    preparation_refs: list[PreparationReference] = Field(default_factory=list, max_length=20)
     candidates: list[DirectCandidate] = Field(min_length=1, max_length=100)
     idempotency_key: Identifier
     duplicate_policy: Literal["reject", "rerun"] = "reject"

backend/app/research_access/service.py

@@ -118,6 +118,17 @@ class ResearchAccess:
         return {"job_id": job.id, "status": job.status, "action": job.kind,
                 "read_with": "get_worldquant_connection", "web_url": f"{self.public_origin}/"}
 
+    async def preparations(self, args):
+        from ..preparations.service import Preparations
+        return await Preparations(self.db).list(args.q, args.scope_key, args.limit, args.offset)
+
+    async def preparation(self, args):
+        from ..preparations.service import Preparations
+        service = Preparations(self.db)
+        row = await service.get(args.id, args.version, lock=True)
+        return {"collection": await service.output(row),
+                "fields": await service.members(row.id, args.q, None, args.limit, args.offset)}
+
     async def catalog(self, args):
         data = await Catalog(self.db).search(args.filters, args.dataset_id)
         return {**data, "scope": args.filters.model_dump(include={"region", "universe", "delay", "instrument_type"}),
@@ -298,7 +309,8 @@ class ResearchAccess:
         # preserve_source prevents the Chatbox-specific generating context rewriting MCP provenance.
         backtests = Backtests(self.db, provenance)
         preview = await backtests.preview(PreviewInput(inline=DraftInput(
-            name=args.name, source=source, candidates=args.candidates)), preserve_source=True)
+            name=args.name, source=source, candidates=args.candidates,
+            preparation_refs=args.preparation_refs)), preserve_source=True)
         result = await backtests.start(StartInput(preview_id=preview["preview_id"],
             idempotency_key="mcp-" + str(uuid4())))
         result = {**result, "input_digest": digest, "batch_count": preview["batch_count"],