tradingcodex 0.1.0__py3-none-any.whl

tradingcodex_service/application/policy.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from tradingcodex_service.application.audit import write_policy_decision_if_available
+from tradingcodex_service.application.common import _number, _safe_read
+from tradingcodex_service.application.runtime import ensure_runtime_database, workspace_context_payload
+
+DEFAULT_MAX_SINGLE_ORDER_KRW = 100_000_000
+DEFAULT_ALLOWED_ADAPTERS = {"stub-execution", "paper-trading"}
+EXPLICIT_DENY_ACTIONS = {
+    "api_key.read",
+    "api_key.rotate",
+    "secret.read",
+    "broker.raw_api",
+    "broker_api.direct_call",
+    "approval.self_issue",
+    "approval_receipt.self_issue",
+    "execute_order",
+    "order.execute",
+    "trade.execute",
+    "trading.execute",
+    "cash.withdraw",
+    "cash.transfer",
+    "permissions.write",
+    "policy.write",
+    "mcp.tradingcodex.write_policy_and_execute",
+}
+
+@dataclass(frozen=True)
+class RuntimePolicy:
+    max_single_order_krw: int = DEFAULT_MAX_SINGLE_ORDER_KRW
+    allowed_adapters: frozenset[str] = frozenset(DEFAULT_ALLOWED_ADAPTERS)
+    source: tuple[str, ...] = ("default-runtime-policy",)
+
+
+def read_runtime_policy(workspace_root: Path | str) -> RuntimePolicy:
+    root = Path(workspace_root)
+    max_single_order = DEFAULT_MAX_SINGLE_ORDER_KRW
+    allowed_adapters = set(DEFAULT_ALLOWED_ADAPTERS)
+    source = [".tradingcodex/policies/access-policies.yaml", ".tradingcodex/config.yaml"]
+
+    access_text = _safe_read(root / ".tradingcodex" / "policies" / "access-policies.yaml")
+    max_match = re.search(r"order\.estimated_notional_krw\s*<=\s*(\d+)", access_text)
+    if max_match:
+        max_single_order = int(max_match.group(1))
+    brokers_match = re.search(r"order\.broker\s+in\s+\[([^\]]+)\]", access_text)
+    if brokers_match:
+        parsed = re.findall(r'"([^"]+)"', brokers_match.group(1))
+        if parsed:
+            allowed_adapters = set(parsed)
+
+    config_text = _safe_read(root / ".tradingcodex" / "config.yaml")
+    section = re.search(r"enabled_adapters:[ \t]*\n((?:[ \t]*-[ \t]*[A-Za-z0-9._-]+[ \t]*(?:\n|$))+)", config_text)
+    if section:
+        configured = set(re.findall(r"^[ \t]*-[ \t]*([A-Za-z0-9._-]+)[ \t]*$", section.group(1), flags=re.M))
+        if configured:
+            allowed_adapters &= configured
+
+    return RuntimePolicy(max_single_order, frozenset(allowed_adapters), tuple(source))
+
+
+def read_restricted_symbols(workspace_root: Path | str) -> set[str]:
+    text = _safe_read(Path(workspace_root) / ".tradingcodex" / "policies" / "restricted-list.yaml")
+    symbols: set[str] = set()
+    try:
+        ensure_runtime_database(workspace_root)
+        from apps.policy.models import RestrictedSymbol
+
+        symbols.update(symbol.upper() for symbol in RestrictedSymbol.objects.filter(active=True).values_list("symbol", flat=True))
+    except Exception:
+        pass
+    inline = re.search(r"restricted_symbols\s*:\s*\[([^\]]*)\]", text)
+    if inline:
+        for raw in inline.group(1).split(","):
+            symbol = raw.strip().strip("'\"")
+            if symbol:
+                symbols.add(symbol.upper())
+    block = re.search(r"restricted_symbols\s*:\s*\n((?:[ \t]*-[ \t]*[A-Za-z0-9_.:-]+[ \t]*(?:\n|$))+)", text)
+    if block:
+        symbols.update(symbol.upper() for symbol in re.findall(r"^[ \t]*-[ \t]*([A-Za-z0-9_.:-]+)[ \t]*$", block.group(1), flags=re.M))
+    symbols.update(symbol.upper() for symbol in re.findall(r"\bsymbol\s*:\s*['\"]?([A-Za-z0-9_.:-]+)['\"]?", text))
+    return symbols
+
+
+def evaluate_policy(workspace_root: Path | str, args: dict[str, Any]) -> dict[str, Any]:
+    ensure_runtime_database(workspace_root)
+    from apps.policy.services import capability_check, sync_builtin_principals_and_capabilities
+    from tradingcodex_service.application.orders import resolve_approval_receipt, resolve_order_intent
+
+    sync_builtin_principals_and_capabilities()
+    policy = read_runtime_policy(workspace_root)
+    order = resolve_order_intent(Path(workspace_root), args)
+    receipt = resolve_approval_receipt(Path(workspace_root), args, order)
+    principal_id = args.get("principal_id") or "unknown"
+    action = args.get("action") or "unknown"
+    reasons: list[str] = []
+    capability_allowed, capability_reasons = capability_check(principal_id, action, args.get("resource"))
+    if not capability_allowed:
+        reasons.extend(capability_reasons)
+
+    if action in EXPLICIT_DENY_ACTIONS:
+        reasons.append(f"explicit deny action: {action}")
+    if action.startswith(("broker_api.", "broker.")):
+        reasons.append("direct broker API actions are explicitly denied")
+    if "live" in action.lower() and re.search(r"order|execution|submit|broker", action.lower()):
+        reasons.append("live execution actions are disabled in the initial core")
+    if "live" in str(args.get("resource") or "").lower() and re.search(r"order|execution|submit|broker", action.lower()):
+        reasons.append("live execution resources are disabled in the initial core")
+    if action in {"approval.create", "approval_receipt.create"} and principal_id != "risk-manager":
+        reasons.append("only risk-manager can create approval receipts")
+    if action == "mcp.tradingcodex.submit_approved_order" and principal_id != "execution-operator":
+        reasons.append("only execution-operator can submit approved orders")
+    if order.get("broker") == "live" and not (Path(workspace_root) / ".tradingcodex" / "mcp" / "adapters" / "live.py").exists():
+        reasons.append("live broker adapter is not installed in this workspace")
+    if order.get("broker") and order["broker"] not in policy.allowed_adapters:
+        reasons.append(f"adapter not enabled: {order['broker']}")
+
+    notional = _number(order.get("estimated_notional_krw"))
+    if order.get("estimated_notional_krw") not in (None, "") and (notional is None or notional <= 0):
+        reasons.append("estimated_notional_krw must be a positive number")
+    elif notional is not None and notional > policy.max_single_order_krw:
+        reasons.append(f"estimated_notional_krw exceeds {policy.max_single_order_krw}")
+
+    if order.get("symbol") and str(order["symbol"]).upper() in read_restricted_symbols(workspace_root):
+        reasons.append(f"symbol is restricted: {order['symbol']}")
+    if args.get("require_approval_check") and receipt.get("valid") is not True:
+        reasons.append("approval_receipt.valid == false")
+
+    decision = "allow" if not reasons else "deny"
+    result = {
+        "decision": decision,
+        "reasons": reasons,
+        "enforced_by": ["TradingCodex MCP"],
+        "policy_source": list(policy.source),
+        "principal_id": principal_id,
+        "action": action,
+        "resource": args.get("resource"),
+        "db_canonical": True,
+        "workspace_context": workspace_context_payload(workspace_root),
+    }
+    write_policy_decision_if_available(workspace_root, result)
+    return result
+
+
+def simulate_policy(workspace_root: Path | str, args: dict[str, Any]) -> dict[str, Any]:
+    return evaluate_policy(workspace_root, args)

tradingcodex_service/application/portfolio.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from tradingcodex_service.application.common import now_iso
+from tradingcodex_service.application.runtime import active_profile_for_workspace, ensure_runtime_database, workspace_context_payload
+
+DEFAULT_PAPER_CASH_KRW = 100_000_000
+DEFAULT_PORTFOLIO_ID = "default-paper"
+DEFAULT_ACCOUNT_ID = "local-paper"
+DEFAULT_STRATEGY_ID = "default-strategy"
+
+def submit_paper_order(root: Path, order: dict[str, Any]) -> dict[str, Any]:
+    portfolio_id, account_id, strategy_id = portfolio_keys(order, root)
+    state = load_paper_portfolio_state(root, portfolio_id, account_id, strategy_id)
+    symbol = str(order["symbol"]).upper()
+    quantity = float(order["quantity"])
+    price = float(order["limit_price"])
+    notional = quantity * price
+    current = state.setdefault("positions", {}).get(symbol, {"quantity": 0, "average_price": 0, "currency": order.get("currency", "KRW")})
+    if order["side"] == "buy":
+        if float(state.get("cash_krw", 0)) < notional:
+            raise ValueError(f"insufficient paper cash: required {notional}, available {state.get('cash_krw', 0)}")
+        next_quantity = float(current.get("quantity", 0)) + quantity
+        current["average_price"] = 0 if next_quantity == 0 else ((float(current.get("quantity", 0)) * float(current.get("average_price", 0))) + notional) / next_quantity
+        current["quantity"] = next_quantity
+        state["cash_krw"] = float(state.get("cash_krw", 0)) - notional
+    else:
+        if float(current.get("quantity", 0)) < quantity:
+            raise ValueError(f"insufficient paper position: required {quantity}, available {current.get('quantity', 0)}")
+        current["quantity"] = float(current.get("quantity", 0)) - quantity
+        state["cash_krw"] = float(state.get("cash_krw", 0)) + notional
+        if current["quantity"] == 0:
+            current["average_price"] = 0
+    state["positions"][symbol] = current
+    state["updated_at"] = now_iso()
+    persist_paper_portfolio_state(root, state, portfolio_id, account_id, strategy_id, source="paper-trading")
+    return {
+        "adapter": "paper-trading",
+        "broker_order_id": f"paper-{order['id']}",
+        "status": "filled",
+        "filled_quantity": quantity,
+        "average_price": price,
+        "submitted_at": state["updated_at"],
+        "portfolio_id": portfolio_id,
+        "account_id": account_id,
+        "strategy_id": strategy_id,
+    }
+
+
+def portfolio_keys(args: dict[str, Any], workspace_root: Path | str | None = None) -> tuple[str, str, str]:
+    profile = active_profile_for_workspace(workspace_root)
+    return (
+        str(args.get("portfolio_id") or profile.get("portfolio_id") or DEFAULT_PORTFOLIO_ID),
+        str(args.get("account_id") or profile.get("account_id") or DEFAULT_ACCOUNT_ID),
+        str(args.get("strategy_id") or profile.get("strategy_id") or DEFAULT_STRATEGY_ID),
+    )
+
+
+def default_paper_portfolio_state(portfolio_id: str = DEFAULT_PORTFOLIO_ID, account_id: str = DEFAULT_ACCOUNT_ID, strategy_id: str = DEFAULT_STRATEGY_ID) -> dict[str, Any]:
+    return {
+        "cash_krw": DEFAULT_PAPER_CASH_KRW,
+        "positions": {},
+        "updated_at": now_iso(),
+        "portfolio_id": portfolio_id,
+        "account_id": account_id,
+        "strategy_id": strategy_id,
+        "source": "central-db",
+        "db_canonical": True,
+    }
+
+
+def load_paper_portfolio_state(
+    workspace_root: Path | str | None = None,
+    portfolio_id: str = DEFAULT_PORTFOLIO_ID,
+    account_id: str = DEFAULT_ACCOUNT_ID,
+    strategy_id: str = DEFAULT_STRATEGY_ID,
+) -> dict[str, Any]:
+    ensure_runtime_database(workspace_root)
+    from apps.portfolio.models import PortfolioSnapshot
+
+    snapshot = (
+        PortfolioSnapshot.objects.filter(
+            portfolio_id=portfolio_id,
+            account_id=account_id,
+            strategy_id=strategy_id,
+            source="paper-trading",
+        )
+        .order_by("-created_at", "-id")
+        .first()
+    )
+    if snapshot is None:
+        state = default_paper_portfolio_state(portfolio_id, account_id, strategy_id)
+        state["workspace_context"] = workspace_context_payload(workspace_root)
+        persist_paper_portfolio_state(workspace_root, state, portfolio_id, account_id, strategy_id, source="paper-trading")
+        return state
+    state = dict(snapshot.payload or {})
+    state.setdefault("cash_krw", 0)
+    state.setdefault("positions", {})
+    state.setdefault("updated_at", snapshot.created_at.isoformat())
+    state.update({
+        "portfolio_id": portfolio_id,
+        "account_id": account_id,
+        "strategy_id": strategy_id,
+        "source": "central-db",
+        "db_canonical": True,
+        "workspace_context": workspace_context_payload(workspace_root),
+    })
+    return state
+
+
+def persist_paper_portfolio_state(
+    workspace_root: Path | str | None,
+    state: dict[str, Any],
+    portfolio_id: str,
+    account_id: str,
+    strategy_id: str,
+    source: str = "paper-trading",
+) -> None:
+    ensure_runtime_database(workspace_root)
+    from apps.portfolio.models import CashBalance, PortfolioSnapshot, Position
+
+    state = dict(state)
+    state.update({
+        "portfolio_id": portfolio_id,
+        "account_id": account_id,
+        "strategy_id": strategy_id,
+        "source": "central-db",
+        "db_canonical": True,
+        "workspace_context": workspace_context_payload(workspace_root),
+    })
+    snapshot = PortfolioSnapshot.objects.create(
+        source=source,
+        portfolio_id=portfolio_id,
+        account_id=account_id,
+        strategy_id=strategy_id,
+        workspace_context=workspace_context_payload(workspace_root),
+        payload=state,
+    )
+    CashBalance.objects.create(
+        snapshot=snapshot,
+        currency="KRW",
+        amount=state.get("cash_krw", 0),
+        portfolio_id=portfolio_id,
+        account_id=account_id,
+        strategy_id=strategy_id,
+    )
+    for symbol, position in sorted((state.get("positions") or {}).items()):
+        if float(position.get("quantity", 0)) == 0:
+            continue
+        Position.objects.create(
+            snapshot=snapshot,
+            symbol=str(symbol).upper(),
+            quantity=position.get("quantity", 0),
+            average_price=position.get("average_price", 0),
+            currency=position.get("currency") or "KRW",
+            portfolio_id=portfolio_id,
+            account_id=account_id,
+            strategy_id=strategy_id,
+        )
+
+
+def list_positions(workspace_root: Path | str) -> dict[str, Any]:
+    portfolio_id, account_id, strategy_id = portfolio_keys({}, workspace_root)
+    return load_paper_portfolio_state(Path(workspace_root), portfolio_id, account_id, strategy_id)

tradingcodex_service/application/research.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from tradingcodex_service.application.common import _resolve_path, sanitize_id
+from tradingcodex_service.application.markdown_preview import split_markdown_frontmatter
+from tradingcodex_service.application.runtime import workspace_context_payload
+
+RESEARCH_FILE_ROOTS = (Path("trading/research"), Path("trading/reports"))
+SOURCE_SNAPSHOT_ROOT = Path("trading/research/source-snapshots")
+
+
+def list_workflow_artifacts(workspace_root: Path | str) -> dict[str, Any]:
+    root = Path(workspace_root)
+    files = []
+    for prefix in ["trading/research", "trading/reports", "trading/orders", "trading/approvals"]:
+        base = root / prefix
+        if base.exists():
+            files.extend(str(path.relative_to(root)) for path in base.rglob("*") if path.is_file() and path.name != ".gitkeep")
+    return {
+        "artifacts": sorted(files),
+        "research_artifacts": list_research_artifacts(root, {"include_markdown": False}).get("artifacts", []),
+        "workspace_native": True,
+        "workspace_context": workspace_context_payload(root),
+    }
+
+
+def create_research_artifact(workspace_root: Path | str, args: dict[str, Any]) -> dict[str, Any]:
+    root = Path(workspace_root)
+    markdown = args.get("markdown")
+    markdown_path = args.get("markdown_path") or args.get("markdown_file")
+    if not markdown and markdown_path:
+        markdown = _resolve_path(root, markdown_path).read_text(encoding="utf-8")
+    if not markdown:
+        raise ValueError("research artifact markdown is required")
+
+    source_document = split_markdown_frontmatter(str(markdown))
+    source_frontmatter = source_document.frontmatter
+    markdown_body = source_document.body or str(markdown)
+    artifact_type = str(args.get("artifact_type") or args.get("type") or source_frontmatter.get("artifact_type") or source_frontmatter.get("type") or "research_memo")
+    title = str(args.get("title") or source_frontmatter.get("title") or source_document.heading or args.get("artifact_id") or "Untitled research artifact")
+    symbol = str(args.get("symbol") or source_frontmatter.get("symbol") or "").upper()
+    content_hash = hashlib.sha256(markdown_body.encode("utf-8")).hexdigest()
+    artifact_id = str(args.get("artifact_id") or source_frontmatter.get("artifact_id") or f"{sanitize_id(artifact_type)}-{sanitize_id(symbol or title)}-{content_hash[:12]}")
+    metadata = args.get("metadata") if isinstance(args.get("metadata"), dict) else {}
+    created_by = str(args.get("created_by") or args.get("principal_id") or source_frontmatter.get("created_by") or "system")
+    existing = find_workspace_research_artifact(root, artifact_id)
+    if existing and existing.get("content_hash") != content_hash and not args.get("_append_version"):
+        raise ValueError("research artifact already exists in this workspace; use append_research_artifact_version to create a new version")
+
+    existing_version = _int_value(existing.get("version") if existing else None, default=0)
+    version = existing_version + 1 if args.get("_append_version") else existing_version or 1
+    export_path = str(args.get("export_path") or (existing.get("path") if existing else "") or default_research_export_path_from_values(artifact_id, artifact_type, metadata))
+    frontmatter = {
+        **source_frontmatter,
+        "artifact_id": artifact_id,
+        "artifact_type": artifact_type,
+        "universe": args.get("universe") or source_frontmatter.get("universe") or "public_equity",
+        "workflow_type": args.get("workflow_type") or source_frontmatter.get("workflow_type") or "",
+        "role": args.get("role") or metadata.get("role") or source_frontmatter.get("role") or _role_alias_from_actor(created_by),
+        "symbol": symbol,
+        "title": title,
+        "source_as_of": args.get("source_as_of") or source_frontmatter.get("source_as_of") or "",
+        "readiness_label": args.get("readiness_label") or source_frontmatter.get("readiness_label") or "",
+        "version": version,
+        "content_hash": content_hash,
+        "workspace_native": True,
+        "created_by": created_by,
+    }
+    path = _resolve_path(root, export_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(_render_research_markdown(frontmatter, markdown_body), encoding="utf-8")
+
+    result = {
+        "status": "updated" if existing else "stored",
+        "db_canonical": False,
+        "file_sot": True,
+        "workspace_native": True,
+        "artifact_id": artifact_id,
+        "version": version,
+        "content_hash": content_hash,
+        "export_path": path.relative_to(root).as_posix(),
+        "workspace_context": workspace_context_payload(root),
+    }
+    return result
+
+
+def append_research_artifact_version(workspace_root: Path | str, args: dict[str, Any]) -> dict[str, Any]:
+    if not args.get("artifact_id"):
+        raise ValueError("artifact_id is required")
+    current = get_research_artifact(workspace_root, {"artifact_id": args["artifact_id"]})
+    payload = {
+        **current,
+        **args,
+        "_append_version": True,
+        "metadata": args.get("metadata") or current.get("metadata") or {},
+        "export_path": args.get("export_path") or current.get("path") or current.get("export_path"),
+    }
+    if args.get("markdown"):
+        payload["markdown"] = args["markdown"]
+    elif args.get("markdown_path") or args.get("markdown_file"):
+        payload.pop("markdown", None)
+    else:
+        payload["markdown"] = current.get("markdown")
+    return create_research_artifact(workspace_root, payload)
+
+
+def get_research_artifact(workspace_root: Path | str, args: dict[str, Any]) -> dict[str, Any]:
+    artifact_id = args.get("artifact_id") or args.get("id")
+    if not artifact_id:
+        raise ValueError("artifact_id is required")
+    artifact = find_workspace_research_artifact(Path(workspace_root), str(artifact_id))
+    if not artifact:
+        raise ValueError(f"research artifact not found in workspace: {artifact_id}")
+    if args.get("include_markdown", True) is not False:
+        artifact["markdown"] = _read_research_markdown_body(Path(workspace_root) / artifact["path"])
+    return artifact
+
+
+def list_research_artifacts(workspace_root: Path | str, args: dict[str, Any] | None = None) -> dict[str, Any]:
+    args = args or {}
+    artifacts = list_workspace_research_artifacts(Path(workspace_root), include_markdown=args.get("include_markdown") is True)
+    for field in ["artifact_type", "universe", "workflow_type", "symbol", "readiness_label", "created_by"]:
+        value = args.get(field)
+        if value:
+            artifacts = [artifact for artifact in artifacts if str(artifact.get(field) or "").lower() == str(value).lower()]
+    limit = max(1, min(int(args.get("limit") or 50), 200))
+    return {
+        "db_canonical": False,
+        "file_sot": True,
+        "workspace_native": True,
+        "workspace_context": workspace_context_payload(workspace_root),
+        "artifacts": artifacts[:limit],
+    }
+
+
+def search_research_artifacts(workspace_root: Path | str, args: dict[str, Any]) -> dict[str, Any]:
+    query = str(args.get("query") or args.get("q") or "").strip()
+    if not query:
+        raise ValueError("query is required")
+    artifacts = list_workspace_research_artifacts(Path(workspace_root), include_markdown=True)
+    query_lower = query.lower()
+    artifacts = [
+        artifact
+        for artifact in artifacts
+        if query_lower in str(artifact.get("title") or "").lower()
+        or query_lower in str(artifact.get("symbol") or "").lower()
+        or query_lower in str(artifact.get("markdown") or "").lower()
+    ]
+    for field in ["universe", "artifact_type"]:
+        if args.get(field):
+            artifacts = [artifact for artifact in artifacts if str(artifact.get(field) or "").lower() == str(args[field]).lower()]
+    limit = max(1, min(int(args.get("limit") or 20), 100))
+    for artifact in artifacts:
+        artifact.pop("markdown", None)
+    return {
+        "query": query,
+        "db_canonical": False,
+        "file_sot": True,
+        "workspace_native": True,
+        "workspace_context": workspace_context_payload(workspace_root),
+        "artifacts": artifacts[:limit],
+    }
+
+
+def export_research_artifact_md(workspace_root: Path | str, args: dict[str, Any]) -> dict[str, Any]:
+    root = Path(workspace_root)
+    artifact_id = args.get("artifact_id") or args.get("id")
+    if not artifact_id:
+        raise ValueError("artifact_id is required")
+    artifact = get_research_artifact(root, {"artifact_id": artifact_id, "include_markdown": True})
+    target_rel = str(args.get("export_path") or artifact["path"])
+    target = _resolve_path(root, target_rel)
+    source = root / artifact["path"]
+    if target.resolve() != source.resolve():
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
+    return {
+        "status": "exported",
+        "artifact_id": artifact["artifact_id"],
+        "export_path": target.relative_to(root).as_posix(),
+        "db_canonical": False,
+        "file_sot": True,
+        "workspace_native": True,
+        "workspace_context": workspace_context_payload(root),
+    }
+
+
+def record_source_snapshot(workspace_root: Path | str, args: dict[str, Any]) -> dict[str, Any]:
+    root = Path(workspace_root)
+    recorded_at = datetime.now(timezone.utc).isoformat()
+    payload = {
+        "provider": args.get("provider") or "unknown",
+        "source_category": args.get("source_category") or args.get("category") or "unknown",
+        "as_of": args.get("as_of") or "",
+        "artifact_id": args.get("artifact_id") or "",
+        "warnings": args.get("warnings") if isinstance(args.get("warnings"), list) else [],
+        "payload": args.get("payload") if isinstance(args.get("payload"), dict) else {},
+        "created_by": args.get("principal_id") or args.get("created_by") or "system",
+        "recorded_at": recorded_at,
+        "workspace_native": True,
+    }
+    snapshot_id = _source_snapshot_id(payload)
+    rel_path = SOURCE_SNAPSHOT_ROOT / f"{snapshot_id}.json"
+    path = _resolve_path(root, rel_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({**payload, "snapshot_id": snapshot_id}, indent=2, ensure_ascii=False, sort_keys=True) + "\n", encoding="utf-8")
+    result = {
+        "status": "recorded",
+        "snapshot_id": snapshot_id,
+        "artifact_id": payload["artifact_id"],
+        "provider": payload["provider"],
+        "source_category": payload["source_category"],
+        "export_path": path.relative_to(root).as_posix(),
+        "db_canonical": False,
+        "file_sot": True,
+        "workspace_native": True,
+        "workspace_context": workspace_context_payload(root),
+    }
+    return result
+
+
+def list_workspace_research_artifacts(root: Path, *, include_markdown: bool = False) -> list[dict[str, Any]]:
+    records: list[dict[str, Any]] = []
+    for rel_root in RESEARCH_FILE_ROOTS:
+        base = root / rel_root
+        if not base.exists():
+            continue
+        for path in sorted(base.rglob("*.md")):
+            if path.name == ".gitkeep":
+                continue
+            records.append(_research_file_payload(root, path, include_markdown=include_markdown))
+    return sorted(records, key=lambda item: item["updated_at"], reverse=True)
+
+
+def find_workspace_research_artifact(root: Path, artifact_id: str) -> dict[str, Any] | None:
+    direct = root / artifact_id
+    if direct.exists() and direct.is_file():
+        return _research_file_payload(root, direct, include_markdown=False)
+    for artifact in list_workspace_research_artifacts(root, include_markdown=False):
+        if artifact["artifact_id"] == artifact_id or artifact["path"] == artifact_id:
+            return artifact
+    return None
+
+
+def _research_file_payload(root: Path, path: Path, *, include_markdown: bool = False) -> dict[str, Any]:
+    rel = path.relative_to(root).as_posix()
+    frontmatter, heading, body = _research_file_parts(path)
+    content_hash = hashlib.sha256(body.encode("utf-8")).hexdigest()
+    artifact_id = str(frontmatter.get("artifact_id") or rel)
+    payload = {
+        "artifact_id": artifact_id,
+        "path": rel,
+        "export_path": rel,
+        "artifact_type": str(frontmatter.get("artifact_type") or _infer_research_artifact_type(path)),
+        "universe": str(frontmatter.get("universe") or _infer_research_universe(path)),
+        "workflow_type": str(frontmatter.get("workflow_type") or ""),
+        "role": str(frontmatter.get("role") or ""),
+        "symbol": str(frontmatter.get("symbol") or ""),
+        "title": str(frontmatter.get("title") or heading or path.stem.replace("-", " ").title()),
+        "metadata": {},
+        "workspace_context": workspace_context_payload(root),
+        "source_as_of": str(frontmatter.get("source_as_of") or ""),
+        "readiness_label": str(frontmatter.get("readiness_label") or frontmatter.get("handoff_state") or "workspace-file"),
+        "created_by": str(frontmatter.get("created_by") or "workspace"),
+        "content_hash": str(frontmatter.get("content_hash") or content_hash),
+        "version": _int_value(frontmatter.get("version"), default=1),
+        "parent_artifact_id": str(frontmatter.get("parent_artifact_id") or ""),
+        "updated_at": datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc),
+        "created_at": datetime.fromtimestamp(path.stat().st_ctime, tz=timezone.utc),
+        "db_canonical": False,
+        "file_sot": True,
+        "workspace_native": True,
+    }
+    if include_markdown:
+        payload["markdown"] = body
+    return payload
+
+
+def _research_file_parts(path: Path) -> tuple[dict[str, Any], str, str]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception:
+        return {}, "", ""
+    document = split_markdown_frontmatter(text)
+    return document.frontmatter, document.heading, document.body
+
+
+def _read_research_markdown_body(path: Path) -> str:
+    return _research_file_parts(path)[2]
+
+
+def _render_research_markdown(frontmatter: dict[str, Any], markdown: str) -> str:
+    header = "---\n" + "\n".join(f"{key}: {json.dumps(value, ensure_ascii=False)}" for key, value in frontmatter.items()) + "\n---\n\n"
+    return header + markdown.rstrip() + "\n"
+
+
+def _int_value(value: Any, *, default: int) -> int:
+    try:
+        return int(value)
+    except Exception:
+        return default
+
+
+def _infer_research_universe(path: Path) -> str:
+    text = path.as_posix().lower()
+    if "crypto" in text:
+        return "public_crypto"
+    if "macro" in text:
+        return "macro"
+    return "workspace"
+
+
+def _infer_research_artifact_type(path: Path) -> str:
+    parts = path.as_posix().split("/")
+    if "reports" in parts:
+        index = parts.index("reports")
+        if len(parts) > index + 1:
+            return f"{parts[index + 1]}_report"
+        return "role_report"
+    if path.name.endswith(".evidence.md"):
+        return "evidence_pack"
+    return "research_handoff"
+
+
+def _role_alias_from_actor(actor: str) -> str:
+    return actor.replace("-analyst", "").replace("-manager", "").replace("-operator", "")
+
+
+def _source_snapshot_id(payload: dict[str, Any]) -> str:
+    base = "-".join(
+        filter(
+            None,
+            [
+                sanitize_id(str(payload.get("provider") or "unknown")),
+                sanitize_id(str(payload.get("source_category") or "unknown")),
+                sanitize_id(str(payload.get("artifact_id") or "")),
+            ],
+        )
+    )
+    digest = hashlib.sha256(json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8")).hexdigest()[:12]
+    return f"{base or 'source-snapshot'}-{digest}"
+
+
+def default_research_export_path_from_values(artifact_id: str, artifact_type: str, metadata: dict[str, Any]) -> str:
+    stem = sanitize_id(artifact_id)
+    role = metadata.get("role") if isinstance(metadata, dict) else ""
+    if artifact_type == "evidence_pack":
+        return f"trading/research/{stem}.evidence.md"
+    if role in {"fundamental", "technical", "news", "macro", "instrument", "valuation", "portfolio", "risk", "policy"}:
+        return f"trading/reports/{role}/{stem}.md"
+    return f"trading/research/{stem}.md"