dataflow-inventory.json

{
  "schema_version": 1,
  "generated_at_utc": "2026-07-22T00:45:46Z",
  "repository": "DeepResearchForecast",
  "git_commit": "fcf7378b2e2fabcfd836fb6e2c512fe153c6727c",
  "scope": "Material current producer-to-receiver boundaries plus every Flask HTTP route, mapped from the current working tree atop the recorded git commit. DeerFlow 2 is the live Stage-1 subsystem, including the default single shared actor-intelligence Track B; generated deployment copies are not double-counted. Optional, compatibility, and pre-cutover surfaces are labeled. DeerFlow 1.x and unrelated future-architecture proposals are excluded.",
  "record_counts": {
    "material_flows": 95,
    "flask_http_interfaces": 101
  },
  "status_legend": {
    "live-default*": "Part of canonical current code under checked-in defaults; for a registered command or route this means exposed under defaults, not invoked during every pipeline. A suffix states the precise stage or condition.",
    "live-conditional*": "Current code used only when the named mode, platform, or condition applies; a suffix states that condition.",
    "config-gated*": "Current implementation disabled or inactive under checked-in defaults; a suffix states the gate.",
    "manual-compat*": "Callable compatibility/debug/operator surface outside the canonical unified UI path; a suffix states any extra condition.",
    "ephemeral*": "Process/browser state that is not authoritative after restart.",
    "pre-cutover*": "Checked-in DRF2 scaffold, not current production authority."
  },
  "flows": [
    {
      "id": "flow.ingress.research_form",
      "status": "live-default",
      "plane": "client/control",
      "producer": "ResearchView research form",
      "transport": "HTTPS/JSON POST",
      "payload": "prompt, mode, depth, optional max_rounds, target/research language and optional model. The backend accepts project_name, but the current ResearchView has no project-name control and does not send it",
      "receiver": "POST /api/research/run",
      "persistence": "None before admission",
      "source": "frontend/src/views/ResearchView.vue:408; frontend/src/api/research.js:20; backend/app/api/research.py:43"
    },
    {
      "id": "flow.ingress.non_idempotent_admission",
      "status": "live-default",
      "plane": "client/control",
      "producer": "Frontend API client",
      "transport": "Single non-retried POST",
      "payload": "One run creation command",
      "receiver": "Research blueprint admission validation",
      "persistence": "Request is not replayed by the client",
      "source": "frontend/src/api/research.js:20; backend/app/api/research.py:43"
    },
    {
      "id": "flow.control.provider_preflight",
      "status": "live-default",
      "plane": "control",
      "producer": "Research admission",
      "transport": "In-process service call",
      "payload": "Mode and optional selected DeerFlow model plus shared system readiness constraints. Depth/language are validated/used elsewhere but are not passed into this preflight call",
      "receiver": "Shared provider/system preflight",
      "persistence": "Sanitized failure returned to client; no pipeline on failure",
      "source": "backend/app/api/research.py:35-119; backend/scripts/preflight.py:1-300"
    },
    {
      "id": "flow.control.pipeline_creation",
      "status": "live-default",
      "plane": "control",
      "producer": "PipelineOrchestrator.start",
      "transport": "Atomic filesystem state plus daemon thread creation",
      "payload": "PipelineState, options, safety-policy pin and task metadata; full mode creates six StageState records while research_only creates one",
      "receiver": "PipelineManager and _run_pipeline daemon thread",
      "persistence": "uploads/pipelines/<id>/pipeline_state.json. run.json is not written by start()",
      "source": "backend/app/services/pipeline_orchestrator.py:189-407,4400-4456"
    },
    {
      "id": "flow.control.run_snapshot",
      "status": "live-default-best-effort",
      "plane": "control/reproducibility",
      "producer": "Pipeline daemon after _run entry",
      "transport": "Best-effort atomic JSON write separate from admission",
      "payload": "Run/reproducibility metadata captured after the asynchronous owner has started",
      "receiver": "Operators and later reconstruction tooling; it is not lifecycle authority",
      "persistence": "uploads/pipelines/<id>/run.json",
      "source": "backend/app/services/pipeline_orchestrator.py:6607-6620,7912-7917"
    },
    {
      "id": "flow.control.admission_response",
      "status": "live-default",
      "plane": "client/control",
      "producer": "Research blueprint",
      "transport": "HTTP JSON response",
      "payload": "pipeline_id, task_id, mode, initial status",
      "receiver": "ResearchView",
      "persistence": "Active pipeline ID in browser localStorage",
      "source": "backend/app/api/research.py:102-119; frontend/src/views/ResearchView.vue:408-442"
    },
    {
      "id": "flow.control.status_poll",
      "status": "live-default",
      "plane": "client/control",
      "producer": "ResearchView adaptive poll generation",
      "transport": "HTTP GET polling",
      "payload": "pipeline_id",
      "receiver": "Durable pipeline status endpoint",
      "persistence": "Reads pipeline_state.json; UI keeps ephemeral snapshot",
      "source": "frontend/src/views/ResearchView.vue:460-690; backend/app/api/research.py:299-308"
    },
    {
      "id": "flow.control.progress_poll",
      "status": "live-default",
      "plane": "client/control",
      "producer": "ResearchView progress poller",
      "transport": "HTTP GET scope=full then bounded scope=tail",
      "payload": "pipeline_id, scope and tail limits",
      "receiver": "Research progress reader",
      "persistence": "Exact progress events remain on disk; UI merges revisions ephemerally",
      "source": "frontend/src/api/research.js:142-160,220-226; backend/app/api/research.py:775-825"
    },
    {
      "id": "flow.control.visibility_pause",
      "status": "ephemeral",
      "plane": "client/control",
      "producer": "Browser visibility event",
      "transport": "DOM event/generation token",
      "payload": "Visible/hidden state and poll generation",
      "receiver": "ResearchView poll scheduler",
      "persistence": "None",
      "source": "frontend/src/views/ResearchView.vue:460-603; frontend/src/utils/liveProgress.js:1-96"
    },
    {
      "id": "flow.client.dossier_reception",
      "status": "live-default-after-research",
      "plane": "client/reception",
      "producer": "GET /api/research/<pipeline_id>/dossier",
      "transport": "Axios application envelope after the Axios transport wrapper is removed",
      "payload": "Current handoff report, actors, sources, timeline, quantitative/contested evidence, markets, charts and has_report",
      "receiver": "Embedded DossierViewer in ResearchView",
      "persistence": "Server handoff files remain durable; Vue state is ephemeral",
      "source": "frontend/src/components/research/DossierViewer.vue:369-480; backend/app/api/research.py:350-401"
    },
    {
      "id": "flow.client.graph_reception",
      "status": "live-default-after-graph",
      "plane": "client/reception",
      "producer": "Graph data, neighborhood, node-detail and edge-detail routes",
      "transport": "Lazy Axios GET requests from the embedded graph panel",
      "payload": "Graph overview/full nodes and edges, bounded neighborhoods, detailed node facts and edge provenance",
      "receiver": "KnowledgeGraphView and detail panels",
      "persistence": "Graph database/position store remain durable; browser layout/detail state is ephemeral",
      "source": "frontend/src/components/GraphPanel.vue:440-825; backend/app/api/graph.py:576-674"
    },
    {
      "id": "flow.client.simulation_fan_in",
      "status": "live-default-after-prepare",
      "plane": "client/reception",
      "producer": "Realtime profiles, posts, comments, agent statistics and run-status routes",
      "transport": "Promise.allSettled fan-in, refreshed about every ten seconds only while the runner is live",
      "payload": "Partial/final personas, social feed, engagement statistics and aggregate simulation status",
      "receiver": "Embedded SimulationView",
      "persistence": "Simulation directories/platform databases remain durable; merged Vue snapshot is ephemeral",
      "source": "frontend/src/components/research/SimulationView.vue:492-570; backend/app/api/simulation.py:1064-1168,1746-1798,1998-2187"
    },
    {
      "id": "flow.client.report_fan_in",
      "status": "live-default-after-report-start",
      "plane": "client/reception",
      "producer": "Report detail, forecast, visualization manifest and root-shaped partial-section routes",
      "transport": "Axios fan-in; about three-second report/partial polling until a final body exists",
      "payload": "Publication-gated report/forecast/viz data or root-level sections/done progress snapshots",
      "receiver": "ForecastReport embedded in ResearchView; legacy /report route remains separately routable",
      "persistence": "Report directory remains durable; displayed section/report state is ephemeral",
      "source": "frontend/src/components/research/ForecastReport.vue:302-373,827-897; backend/app/api/report.py:354-424,1115-1205,1439-1531"
    },
    {
      "id": "flow.client.history_and_controls",
      "status": "live-default",
      "plane": "client/control",
      "producer": "Research history plus cancel/resume/continue/delete/clean commands",
      "transport": "Axios GET/POST/DELETE; mutation responses update durable state and the active UI selection",
      "payload": "Pipeline summaries, control acknowledgements, conflicts and new/current task identity",
      "receiver": "ResearchView history and action controls",
      "persistence": "PipelineState is authoritative; selected history item and active ID are browser state",
      "source": "frontend/src/views/ResearchView.vue:605-751; frontend/src/api/research.js:35-141; backend/app/api/research.py:125-316"
    },
    {
      "id": "flow.client.settings",
      "status": "live-default",
      "plane": "client/control/configuration",
      "producer": "SettingsMenu and GET/POST/test /api/settings/llm",
      "transport": "Axios application envelopes; the connectivity probe does not persist, while settings update atomically rewrites .env and refreshes Config/os.environ for later work",
      "payload": "Sanitized provider/model/base URL/key-presence settings or an ephemeral connectivity result",
      "receiver": "SettingsMenu and subsequent backend provider construction",
      "persistence": "Repository-root .env for saved settings; browser modal state and probes are ephemeral",
      "source": "frontend/src/components/research/SettingsMenu.vue:89-200; backend/app/api/settings.py:25-187; backend/app/config.py:846-919"
    },
    {
      "id": "flow.client.research_translation_export",
      "status": "live-conditional-user-requested-language-export",
      "plane": "client/reception/research",
      "producer": "Research dossier translation daemon/status files and shared document-PDF exporter",
      "transport": "Process-local inflight set plus daemon thread for translation; direct file response for PDF",
      "payload": "Target language, source hash, translated Markdown/audit/status or lang-selected dossier PDF",
      "receiver": "DossierViewer translation/export controls",
      "persistence": "Research translation/status/audit files and cached PDF; no cross-process lease or startup reconciliation",
      "source": "backend/app/api/research.py:403-635; frontend/src/components/research/DossierViewer.vue:491-610"
    },
    {
      "id": "flow.client.legacy_pending_upload",
      "status": "manual-compat-ephemeral",
      "plane": "client/legacy",
      "producer": "Legacy Home file picker and simulation requirement",
      "transport": "Vue reactive pendingUpload singleton followed by navigation to /process/new and synchronous multipart ontology request",
      "payload": "PDF/Markdown/text files plus requirement; lost on browser refresh before upload",
      "receiver": "Legacy MainView and POST /api/graph/ontology/generate",
      "persistence": "Ephemeral before the multipart request; project/files become durable only after backend materialization",
      "source": "frontend/src/store/pendingUpload.js:1-33; frontend/src/views/Home.vue:121-333; frontend/src/views/MainView.vue:180-340"
    },
    {
      "id": "flow.control.stage_update",
      "status": "live-default",
      "plane": "control",
      "producer": "Stage updater callback",
      "transport": "In-process callback plus atomic state write",
      "payload": "stage status/progress/message, global progress, heartbeat and partial artifact pointers",
      "receiver": "PipelineState, TaskManager and status/progress consumers",
      "persistence": "pipeline_state.json; TaskManager is ephemeral",
      "source": "backend/app/services/pipeline_orchestrator.py:5384-5436"
    },
    {
      "id": "flow.control.stage_completion",
      "status": "live-default",
      "plane": "control",
      "producer": "_complete_stage",
      "transport": "Atomic state transition",
      "payload": "completed status, 100 percent progress, timestamps and final artifacts",
      "receiver": "Next stage or terminal pipeline logic",
      "persistence": "pipeline_state.json and manifest",
      "source": "backend/app/services/pipeline_orchestrator.py:5438-5470"
    },
    {
      "id": "flow.control.final_health_completion",
      "status": "live-default-after-report",
      "plane": "control/terminal",
      "producer": "PipelineOrchestrator after the primary REPORT stage and optional seed sidecar",
      "transport": "In-process deliverable assertion followed by atomic pipeline-state save and TaskManager completion",
      "payload": "Primary report/forecast health, optional ensemble outcome, terminal IDs and global_progress=100",
      "receiver": "Durable PipelineState completed status, same-process TaskManager result and status/progress clients",
      "persistence": "pipeline_state.json is authoritative; TaskManager completion is process-ephemeral",
      "source": "backend/app/services/pipeline_orchestrator.py:9126-9155"
    },
    {
      "id": "flow.control.stage_failure",
      "status": "live-default",
      "plane": "control",
      "producer": "Stage exception handler",
      "transport": "Atomic failure state plus telemetry flush",
      "payload": "failed stage, error, timestamp and terminal task context",
      "receiver": "Status API, resume logic and operator",
      "persistence": "pipeline_state.json and telemetry artifacts",
      "source": "backend/app/services/pipeline_orchestrator.py:6178-6185,9175-9186"
    },
    {
      "id": "flow.control.artifact_manifest",
      "status": "live-default",
      "plane": "control/evidence",
      "producer": "Stage artifact recorder",
      "transport": "Filesystem hashing and atomic JSON write",
      "payload": "logical artifact name, path, producing stage, bytes, SHA-256 and schema status",
      "receiver": "Deep-link API and reuse validator",
      "persistence": "handoff/manifest.json and PipelineState.artifacts",
      "source": "backend/app/services/pipeline_orchestrator.py:5929-5983,6124-6176"
    },
    {
      "id": "flow.control.reuse_validation",
      "status": "live-default",
      "plane": "control/evidence",
      "producer": "Resume/stage entry",
      "transport": "Manifest/schema/hash and health checks",
      "payload": "Prior completed-stage artifacts and current contract expectations",
      "receiver": "Reuse-or-rerun decision",
      "persistence": "Existing artifacts retained or stage state reset",
      "source": "backend/app/services/pipeline_orchestrator.py:6189-6235"
    },
    {
      "id": "flow.control.cancel",
      "status": "live-default",
      "plane": "control",
      "producer": "POST /api/research/<id>/cancel",
      "transport": "Serialized mutation and threading.Event",
      "payload": "Pipeline cancellation intent",
      "receiver": "Research process-group watcher, stage checkpoints, SimulationRunner stop and terminal handler",
      "persistence": "Cancelled pipeline/stage/run status",
      "source": "backend/app/api/research.py:125-137; backend/app/services/pipeline_orchestrator.py:4459-4493,9157-9169"
    },
    {
      "id": "flow.control.resume",
      "status": "live-default",
      "plane": "control",
      "producer": "POST /api/research/<id>/resume",
      "transport": "Provider preflight, durable state inspection and new daemon thread",
      "payload": "Existing pipeline ID and optional force flag",
      "receiver": "Same PipelineState lineage at first invalid/failed stage",
      "persistence": "Reused validated artifacts; reset active stage; new owner/heartbeat",
      "source": "backend/app/api/research.py:140-174; backend/app/services/pipeline_orchestrator.py:4584-4688"
    },
    {
      "id": "flow.control.continue_research_only",
      "status": "live-default",
      "plane": "control",
      "producer": "POST /api/research/<id>/continue",
      "transport": "Durable state mutation and daemon thread",
      "payload": "Completed research_only pipeline",
      "receiver": "Ontology stage of same pipeline",
      "persistence": "Research contract retained; later stages set pending",
      "source": "backend/app/api/research.py:177-209; backend/app/services/pipeline_orchestrator.py:4691-4754"
    },
    {
      "id": "flow.control.scenario_fork",
      "status": "live-conditional",
      "plane": "control",
      "producer": "POST /api/research/<id>/scenario",
      "transport": "New pipeline state sharing base lineage",
      "payload": "Scenario label, config overrides, injected events and/or as_of shift",
      "receiver": "Outer prepare orchestrator, which may mutate simulation_config.json only after SimulationManager has validated its base outputs and set READY, then records the authorized mutation for resealing",
      "persistence": "New pipeline ID; references to base project/graph/handoff; post-READY scenario overlay in the final simulation_config.json. Before PREPARE completes, the orchestrator rebuilds and immediately validates the complete simulation-config/cast/context/role seal and persists its replacement hashes",
      "source": "backend/app/api/research.py:212-250; backend/app/services/pipeline_orchestrator.py:4757-4821,7472-7577,11636-11728; backend/app/services/simulation_manager.py:1318-1350"
    },
    {
      "id": "flow.control.startup_recovery",
      "status": "live-default-in-production",
      "plane": "control/operations",
      "producer": "Flask app startup",
      "transport": "Durable-state scan plus verified process inspection",
      "payload": "Persisted running pipelines, owner/heartbeat/process/report evidence",
      "receiver": "Salvage-complete, terminate verified orphan, or mark failed/recoverable logic",
      "persistence": "Corrected pipeline state and cleanup results",
      "source": "backend/app/__init__.py:54-81; backend/app/services/pipeline_orchestrator.py:4117-4395"
    },
    {
      "id": "flow.research.stage_command",
      "status": "live-default",
      "plane": "research",
      "producer": "Pipeline research stage",
      "transport": "Mode-0600 temporary prompt file plus subprocess argv/environment",
      "payload": "Question/prediction requirement, private prompt path, output directory, model, depth, language, thread/resume/extraction flags, evidence-only/global-synthesis/effective-dual-track/native-child controls, optional synthesis-manifest input and optional existing-KG MCP environment",
      "receiver": "deerflow_bridge/deerflow_research.py in a new process group",
      "persistence": "Prompt file is temporary; progress and outputs go to candidate research directory",
      "source": "backend/app/services/pipeline_orchestrator.py:1326-1812,7919-8238"
    },
    {
      "id": "flow.research.tracked_runtime_sync",
      "status": "live-default",
      "plane": "research/deployment",
      "producer": "Backend stale-bridge guard and setup overlay",
      "transport": "File comparison/copy",
      "payload": "Tracked bridge entry point, providers, tools, patches, skills and middleware plus base-runtime provenance: an optional separately supplied local DeerFlow 2 source drop or the pinned upstream fallback revision",
      "receiver": "Generated deer-flow runtime",
      "persistence": "Gitignored runtime tree; repeated setup retains the assembled base and existing runtime config.yaml while refreshing the applicable tracked integration overlay",
      "source": "setup.sh:571-703; backend/app/services/pipeline_orchestrator.py:758-859,1018-1032"
    },
    {
      "id": "flow.research.agent_prompt",
      "status": "live-default",
      "plane": "research",
      "producer": "Bridge prompt builder",
      "transport": "DeerFlow streamed turn",
      "payload": "Question, prediction contract, depth/language rules, source policy, current gaps, market context and allowed tools",
      "receiver": "Embedded DeerFlow 2 lead agent and scoped child agents; the current Stage-1 path does not traverse the native HTTP gateway",
      "persistence": "Thread/checkpoint messages and progress log",
      "source": "deerflow_bridge/deerflow_research.py:2054-2439,6255-6380"
    },
    {
      "id": "flow.research.search",
      "status": "live-default",
      "plane": "research/external",
      "producer": "Lead/subagent search tool call",
      "transport": "Provider HTTP/API through normalized search layer",
      "payload": "Query, result limit, provider/source policy and budget identity",
      "receiver": "Firecrawl, Exa, Jina or configured search backend",
      "persistence": "Normalized result metadata, budget/provider telemetry and cache where applicable",
      "source": "deerflow_bridge/search_tools.py:324-575; deerflow_bridge/research_budget.py:620-940"
    },
    {
      "id": "flow.research.fetch",
      "status": "live-default",
      "plane": "research/external",
      "producer": "Lead/subagent fetch tool call",
      "transport": "Cached/single-flight provider fetch or direct HTTP fallback",
      "payload": "Validated URL and source policy",
      "receiver": "Firecrawl/Jina/direct fetcher",
      "persistence": "Content cache, fetched-source registry, URL/content hashes and provider/budget telemetry",
      "source": "deerflow_bridge/cached_fetch.py:425-825; deerflow_bridge/research_budget.py:500-758"
    },
    {
      "id": "flow.research.tool_observation",
      "status": "live-default",
      "plane": "research",
      "producer": "Search/fetch/market/MCP tool",
      "transport": "DeerFlow ToolMessage/stream event",
      "payload": "Normalized result, control failure or budget denial",
      "receiver": "Lead/subagent next model turn and evidence accumulator",
      "persistence": "Progress log, thread state, worker notes and evidence pack",
      "source": "deerflow_bridge/deerflow_research.py:976-1197,6255-6380"
    },
    {
      "id": "flow.research.fanout_absorption",
      "status": "live-conditional-bridge-only-when-native-delegation-does-not-own-breadth",
      "plane": "research",
      "producer": "Scoped research workers",
      "transport": "Bounded futures plus parent absorption prompt/evidence merge",
      "payload": "KIQ-specific notes and fetched-source records",
      "receiver": "Parent research thread/evidence synthesis; this bridge fan-out is suppressed when harness-native subagent delegation owns the breadth plane",
      "persistence": "Worker notes and shared fetched-source registry",
      "source": "deerflow_bridge/deerflow_research.py:6435-6626"
    },
    {
      "id": "flow.research.harness_subagent_roundtrip",
      "status": "live-conditional-default-enabled",
      "plane": "research/deerflow2",
      "producer": "DeerFlow 2 lead agent task tool",
      "transport": "SubagentExecutor with isolated child state, bounded child model/tool loop, then task ToolMessage reception",
      "payload": "Scoped research task, selected child prompt/skills/tools and inherited run context; terminal child text/status/usage returns to the parent",
      "receiver": "Parent Stage-1 lead-agent loop and evidence accumulator",
      "persistence": "Child graph state is ephemeral; returned text is checkpointed in the parent and shared-workspace files can persist",
      "source": "deer-flow-2.0.0/backend/packages/harness/deerflow/subagents/executor.py:341-650; deerflow_bridge/deerflow_research.py:10953-10972; deerflow_bridge/patches/apply_subagent_overlays.py:1-184"
    },
    {
      "id": "flow.research.context_summarization",
      "status": "live-conditional",
      "plane": "research/deerflow2",
      "producer": "DeerFlow 2 summarization middleware after the configured 80K-token trigger",
      "transport": "One summary-model invocation over the complete discarded span, retaining the most recent 16K tokens verbatim",
      "payload": "Checkpointed conversation history, skill-preservation context and forecast-evidence-ledger summary prompt",
      "receiver": "Rewritten lead-agent message state used by the next model turn",
      "persistence": "Compressed message history in the thread checkpoint; the current run model is inherited when no summary model is named",
      "source": "deerflow_bridge/config.yaml:1293-1367; deerflow_bridge/patches/apply_lead_agent_overlays.py:8-88; deerflow_bridge/patches/middlewares/summarization_middleware.py:133-219"
    },
    {
      "id": "flow.research.existing_kg_mcp",
      "status": "live-conditional",
      "plane": "research/deerflow2/external",
      "producer": "Fork, continue or resume-with-graph research admission with a durable graph_id and RESEARCH_MCP_KG enabled",
      "transport": "Injected DeerFlow extensions configuration and DRF_MCP_KG_GRAPH_ID, then stdio MCP tool request/response",
      "payload": "Read/query requests over the existing backend knowledge graph and normalized tool observations",
      "receiver": "Track-A lead/subagent model loop; the tool-free global-synthesis manifest branch does not attach this MCP",
      "persistence": "Tool observations in Stage-1 progress/checkpoint/evidence; the existing graph remains the graph-stage authority",
      "source": "backend/app/services/pipeline_orchestrator.py:1374-1548; deerflow_bridge/deerflow_research.py:10660-11021"
    },
    {
      "id": "flow.research.parallel_tracks",
      "status": "live-default-configurable",
      "plane": "research/control",
      "producer": "Parallel research coordinator",
      "transport": "ThreadPoolExecutor launching independent bridge subprocesses",
      "payload": "Three angle-specific evidence-only Track-A lane commands under checked-in defaults: broad baseline; base rates/analogs; incentives/contrarian/markets. Exactly the lane-0 broad baseline also receives dual_track=true and owns the one shared Track-B actor-intelligence producer; the other lanes receive dual_track=false. Every lane retains an isolated thread/output directory and the shared question/contract",
      "receiver": "Three sealed evidence packs plus the baseline lane's required actor dossier, coverage audit, optional final judge and current-attempt hashes, then the version-3 manifest-bound global synthesis child",
      "persistence": "Per-lane evidence_pack.md, sources.json and meta.json; baseline actor_dossier.md, actor_dossier_coverage.json and optional actor_dossier_judge.json; evidence_synthesis_manifest.json",
      "source": "backend/app/services/pipeline_orchestrator.py:1341-1487,2974-2980,7400-7757; backend/app/config.py:1114-1146"
    },
    {
      "id": "flow.research.global_synthesis",
      "status": "live-default-configurable",
      "plane": "research",
      "producer": "Sealed version-3 evidence_synthesis_manifest.json after all accepted Track-A lanes and the baseline Track-B actor dossier",
      "transport": "Fresh manifest-bound DeerFlow 2 child with tools disabled, subagents disabled, dual-track disabled and global-synthesis mode enabled",
      "payload": "Accepted evidence-only Track-A packs, a unified citation namespace, and one required actor descriptor binding exact dossier, coverage, baseline-source, search-result-receipt, family-projection and optional exact-input judge bytes. Every Tier-1/2 actor is routed as one bounded all-dimensions block; the cast-wide owner receives all blocks or fails closed",
      "receiver": "One tool-free global outline/section/stitch synthesis and report judge/refinement path, a deterministic actor-local visible-claim/citation/family coverage audit, then one structured-extraction owner",
      "persistence": "evidence_synthesis_manifest.json version 3, final research_report.md/judge, actor_dossier.md/coverage/optional judge, actor family projection and structured artifacts",
      "source": "backend/app/services/pipeline_orchestrator.py:4314-4734; deerflow_bridge/deerflow_research.py:9850-10850,12948-13420"
    },
    {
      "id": "flow.research.actor_track",
      "status": "live-default-one-shared-baseline",
      "plane": "research",
      "producer": "The broad baseline evidence lane's isolated Track-B actor/ontology thread",
      "transport": "One streamed landscape turn, one always-scheduled streamed cast-wide completion pass, tool-free dossier synthesis, then a default-on bounded judge/gap-research/resynthesis loop on one exact Track-B lane/thread/purpose",
      "payload": "A force-ranked exact-enum Tier-1/2 cast across 17 actor-intelligence dimensions. Each admitted claim binds a supporting quote/span to a current Track-B fetch receipt and content hash, keeps source publication time separate from claim-valid time, and records epistemic type, status, horizon, confidence, dependencies, contradictions and qualifiers. Critical gaps require two distinct query-bound producer search-result receipts; unsupported slots remain typed evidence gaps",
      "receiver": "Deterministic semantic coverage/behavior-family/identity audit and ten-dimension exact-input dossier judge, then baseline artifact gates and the version-3 global synthesis manifest",
      "persistence": "actor_dossier.md, actor_dossier_coverage.json with search-result receipts and family projection, optional actor_dossier_judge.json, actor_intelligence_lineage.json, Track-B checkpoint/progress and current-attempt hashes",
      "source": "deerflow_bridge/deerflow_research.py:12794-13420"
    },
    {
      "id": "flow.research.actor_dossier_quality_gate",
      "status": "live-default-one-shared-baseline",
      "plane": "research/evidence",
      "producer": "Track-B dossier candidates",
      "transport": "Deterministic quote/receipt-bound 17-dimension and five-family audit plus default-on ten-dimension tool-free judge and at most two targeted streamed gap-research/resynthesis rounds; a changed candidate is rejudged against the exact bytes it saw",
      "payload": "Exact dossier bytes, current Track-B fetch and search-result ledgers, semantic actor/alias namespace, typed gap attempts, canonical relationship and claim projection hashes, visible family claims and finite judge scores for cast correctness, salience, depth, relationships, history, grounding, contradictions, ontology readiness, forward behavior and cast-wide accountability",
      "receiver": "Baseline lane publication gate, current-attempt meta binding and global-synthesis manifest writer",
      "persistence": "Exact actor_dossier_coverage.json bytes/hash, search-result receipt hash, behavior-family projection hash and optional exact-input actor_dossier_judge.json; explicit final FAIL, malformed/non-finite/stale scorecard or failed deterministic audit yields no dossier",
      "source": "deerflow_bridge/deerflow_research.py:10713-10850,12852-13420; backend/app/services/pipeline_orchestrator.py:3849-4734"
    },
    {
      "id": "flow.research.report_judge_loop",
      "status": "live-default-for-deep",
      "plane": "research/evidence",
      "producer": "Research report synthesis",
      "transport": "Tool-free judge, targeted streamed top-up, patch/resynthesis and rejudge",
      "payload": "Exact candidate bytes, scorecard rubric and named gaps",
      "receiver": "Final accepted research report or explicit quality-gate failure",
      "persistence": "Bound report/judge pair and refinement candidates",
      "source": "deerflow_bridge/deerflow_research.py:6876-7755"
    },
    {
      "id": "flow.research.structured_contract",
      "status": "live-default",
      "plane": "research/evidence",
      "producer": "Final global research report plus the checksum-admitted shared actor dossier",
      "transport": "Tool-free structured extraction plus deterministic validation",
      "payload": "Whole-document-sanitized, explicitly delimited report and dossier evidence plus strict actor/source/relationship/timeline/quantitative/contested schemas, including quote/receipt-bound claims, causal relationship attributes and typed gap-attempt objects",
      "receiver": "Research contract artifact writers",
      "persistence": "actors.json, sources.json, timeline.json, quantitative.json, contested.json and extraction failure artifacts",
      "source": "deerflow_bridge/deerflow_research.py:7200-7800,10713-10850"
    },
    {
      "id": "flow.research.actor_intelligence_contract",
      "status": "live-default",
      "plane": "research/evidence",
      "producer": "One structured-extraction owner followed by persist_final_actor_intelligence_contract",
      "transport": "Deterministic NFKC semantic-identity assignment, quote/receipt/source normalization, exact tiering, 17-dimension typed completion, canonical causal relationship identity and manifest-last exact-file/lineage sealing",
      "payload": "Extracted actors, relationships and sources plus exact final report/dossier bytes. Each claim retains claim, evidence type, source publication and claim-valid time, horizon, status, confidence, exact support, dependencies, contradictions and qualifiers; relationship identity also binds valence, polarity, sign, strength, grade, since, until and lag",
      "receiver": "actors.json consumers in ontology, graph and PREPARE; research contract validator/promoter",
      "persistence": "Nested actor-intelligence/v1 per actor plus top-level ordered/multiset identity, claim, family, relationship, source-receipt, report/dossier and lineage seals; actor_intelligence_lineage.json binds question/run/depth/attempt/lane/thread/checkpoint; research_contract_manifest.json fingerprints every promoted sibling",
      "source": "deerflow_bridge/deerflow_research.py:3563-4300; backend/app/services/pipeline_orchestrator.py:3849-4734"
    },
    {
      "id": "flow.research.prediction_markets",
      "status": "live-conditional",
      "plane": "research/external",
      "producer": "Question/hot topics/actor names and market-query generator",
      "transport": "Read-only Gamma/CLOB HTTP plus relevance model gate",
      "payload": "Short queries, candidate markets, probabilities, volume and price history",
      "receiver": "Research report pricing block and forecast market anchoring",
      "persistence": "prediction_markets.json, prediction_market_candidates.jsonl and market_price_history.json",
      "source": "deerflow_bridge/deerflow_research.py:9149-10299; backend/app/utils/prediction_markets.py:314-395"
    },
    {
      "id": "flow.research.charts",
      "status": "live-conditional-default-enabled",
      "plane": "research/evidence",
      "producer": "Validated quantitative/timeline/market artifacts",
      "transport": "Deterministic chart renderer",
      "payload": "Chart specifications and datasets",
      "receiver": "Research report references, dossier UI and later report stage",
      "persistence": "handoff/charts.json, charts/ and datasets/",
      "source": "deerflow_bridge/deerflow_research.py:10304-10525; backend/app/services/pipeline_orchestrator.py:5929-5951"
    },
    {
      "id": "flow.research.contract_promotion",
      "status": "live-default",
      "plane": "research/control",
      "producer": "Validated research candidate directory",
      "transport": "Staged sealed-copy validation and atomic promotion with rollback retention; manifest written last",
      "payload": "Report, shared actor dossier/coverage/optional judge, actor_intelligence_lineage.json, normalized actor-intelligence/v1 actors, sources, timeline, quantitative, contested, markets, charts, budget and metadata, each admitted by exact size/hash, semantic seal, checkpoint-lineage and judge checks",
      "receiver": "Canonical pipeline handoff directory and ontology stage",
      "persistence": "handoff/research_contract_manifest.json and named research artifacts",
      "source": "backend/app/services/pipeline_orchestrator.py:3849-4734"
    },
    {
      "id": "flow.ontology.project_materialization",
      "status": "live-default",
      "plane": "knowledge",
      "producer": "Sealed research contract",
      "transport": "Create-or-reuse project handling plus in-process project manager/file writes",
      "payload": "Sealed research report and project metadata for a new project; reused projects are not refreshed from the new report before ontology generation",
      "receiver": "New project record and extracted text; research_report.md is recorded in project.files metadata but is not copied into the project files/ directory",
      "persistence": "uploads/projects/<id>/project.json and extracted_text.txt for a newly created project; files/ contains only actually copied project files",
      "source": "backend/app/services/pipeline_orchestrator.py:8257-8274; backend/app/models/project.py:133-178,279-283"
    },
    {
      "id": "flow.ontology.generation",
      "status": "live-default",
      "plane": "knowledge",
      "producer": "OntologyGenerator",
      "transport": "Application chat_json plus deterministic normalization",
      "payload": "Research report/dossier plus bounded actor context and ontology schema contract",
      "receiver": "Project ontology and graph stage",
      "persistence": "project.json and handoff/ontology.json",
      "source": "backend/app/services/ontology_generator.py:520-675; backend/app/services/pipeline_orchestrator.py:8555-8600"
    },
    {
      "id": "flow.ontology.actor_intelligence_projection",
      "status": "live-default-with-legacy-compatibility",
      "plane": "knowledge",
      "producer": "Sealed actors.json actor-intelligence/v1 contract",
      "transport": "Deterministic _actors_to_context projection; no additional model call before OntologyGenerator",
      "payload": "For current v1, structural actor identity/type plus bounded canonical quote/receipt-bound dimension claims and redacted typed-gap summaries only; flat role, stance, description, memory, situation brief, hot topics and unsealed relationships are excluded. The historical bounded rendering remains only for unversioned legacy actors",
      "receiver": "OntologyGenerator additional_context, which chooses actor-relevant entity and edge types",
      "persistence": "Projection is transient; complete claims remain authoritative in actors.json and the resulting ontology persists in project.json/handoff/ontology.json",
      "source": "backend/app/services/pipeline_orchestrator.py:6021-6245"
    },
    {
      "id": "flow.graph.actor_seed",
      "status": "live-default",
      "plane": "knowledge",
      "producer": "Sealed normalized research actors.json with stable actor IDs and nested actor-intelligence/v1",
      "transport": "One strict dry-plan drives deterministic GraphBuilder writes, actor-graph-seed-manifest/v1 and physical readback. Whole records are sanitized/delimited before Graphiti embedding/LLM surfaces; canonical stable UUIDs bypass model identity rewriting",
      "payload": "Structural actor IDs/names/aliases plus only canonical quote/receipt-bound dimension claims and relationships. Node/edge attributes preserve actor/relationship/claim IDs and hashes, endpoints/direction, evidence/status/confidence, source refs, quote/span, receipt/content hashes and causal attributes; flat behavior fields are unreachable",
      "receiver": "Deterministic graph nodes/edges followed by strict post-seed, post-resolution/prune and reuse readback",
      "persistence": "Configured graph backend plus handoff/actor_graph_seed_manifest.json; partial writes, UUID collisions, overwritten attrs/endpoints or missing seeds fail current v1",
      "source": "backend/app/services/graph_builder.py:510-1650; backend/app/services/pipeline_orchestrator.py:6246-6400"
    },
    {
      "id": "flow.graph.episode_ingestion",
      "status": "live-default",
      "plane": "knowledge",
      "producer": "Configured prose-source selector/chunker: default dossier_only selects actor_dossier.md when present, otherwise falls back to the sealed report; explicit both combines them",
      "transport": "Graphiti episode API via sync-to-async runtime",
      "payload": "Whole-document-sanitized research evidence split into timestamped, explicitly delimited text chunks with ontology and source identity; it may enrich graph evidence but cannot replace sealed current-v1 actor seeds",
      "receiver": "Graphiti extraction/dedup model and graph store",
      "persistence": "Episodes, nodes, edges and extraction metadata",
      "source": "backend/app/config.py:462-465; backend/app/services/pipeline_orchestrator.py:800-900; backend/app/services/graphiti_client/runtime.py:900-1100"
    },
    {
      "id": "flow.graph.model_extraction",
      "status": "live-default",
      "plane": "knowledge/model",
      "producer": "Graphiti",
      "transport": "AppGraphitiLLMClient to application provider",
      "payload": "Entity/edge/dedup prompt and target JSON schema",
      "receiver": "Graphiti extraction pipeline",
      "persistence": "Extracted graph facts and telemetry",
      "source": "backend/app/services/graphiti_client/llm_adapter.py:139-246"
    },
    {
      "id": "flow.graph.embedding",
      "status": "live-default",
      "plane": "knowledge/model",
      "producer": "Graphiti embedding requests",
      "transport": "Local sentence-transformers batch encode",
      "payload": "Normalized cache-miss text",
      "receiver": "Graph similarity/search indexes",
      "persistence": "Memory/SQLite embedding cache and graph vectors",
      "source": "backend/app/services/graphiti_client/embedder.py:255-362"
    },
    {
      "id": "flow.graph.persistence",
      "status": "live-default",
      "plane": "knowledge/store",
      "producer": "Graphiti runtime",
      "transport": "FalkorDB server, embedded FalkorDB Lite, or Kuzu driver",
      "payload": "Graphs, nodes, edges, episodes, communities and indexes",
      "receiver": "Graph API, prepare stage and report graph tools",
      "persistence": "uploads/graphiti_db or configured external backend; UI positions stored separately",
      "source": "backend/app/services/graphiti_client/runtime.py:113-125,260-336; backend/app/services/graph_builder.py:329-419"
    },
    {
      "id": "flow.graph.enrichment",
      "status": "live-default-mixed-with-config-gated-subpasses",
      "plane": "knowledge",
      "producer": "Completed graph",
      "transport": "Always-attempted integrity/centrality work plus default-on entity resolution and pruning; community/chokepoint subpasses are config-gated and default-off",
      "payload": "Graph structure, ontology and per-subpass configuration",
      "receiver": "Cleaned graph and structural priors by default; canonical seed nodes win entity resolution, validated aliases may collapse only into their seeded actor and relationship UUIDs/attrs/endpoints survive rewiring",
      "persistence": "Graph store, graph metadata, post-resolution actor-graph-seed readback and handoff/communities.json when generated. Reuse requires manifest identity plus physical readback or rebuilds",
      "source": "backend/app/services/zep_entity_resolver.py:300-500; backend/app/services/graphiti_client/runtime.py:1600-2050; backend/app/services/pipeline_orchestrator.py:6246-6400"
    },
    {
      "id": "flow.prepare.cast_merge",
      "status": "live-default",
      "plane": "simulation/prepare",
      "producer": "Sealed normalized research actors plus structural graph metadata",
      "transport": "Current-v1 matched-only stable-ID/alias selection independent of zero, tiny, default or oversized cast caps; legacy unversioned inputs retain graph-fill compatibility",
      "payload": "Every eligible dossier actor exactly once with stable identity and nested intelligence. An unmatched graph row or missing sealed pack fails current v1; stand-ins/generic graph personas are legacy-only",
      "receiver": "Curated simulation roster",
      "persistence": "actor_cast_manifest.json with integrity metadata",
      "source": "backend/app/services/simulation_manager.py:321-522"
    },
    {
      "id": "flow.prepare.actor_context",
      "status": "live-default-for-researched-cast",
      "plane": "simulation/prepare/evidence",
      "producer": "Selected researched actors plus exact final research report",
      "transport": "Deterministic build_actor_context_artifacts followed by immediate exact sealed-byte reload and validation. Nested actor-intelligence/v1 is accepted only with the required top-level contract, exact final-report hash, full actor roster/dimension/count bindings and valid producer hashes; unsupported explicit versions fail closed",
      "payload": "Per-actor identity and all 17 intelligence dimensions, complete six-field typed gap audit, epistemic separation between documented evidence/actor knowledge/analyst inference/contested claims, actor-anchored report sections, relationships, events, quantitative facts and public shared context. Actor-visible content is bounded/redacted; exact queries/result/receipt IDs remain modeler-only",
      "receiver": "actor-role/v2 compiler, persona generator and simulation-config projection for the same selected actor",
      "persistence": "actor_context/<actor_id>.json and actor_context_manifest.json (actor-context/v1 / actor-context-manifest/v1), binding exact actors/report/actor-ID hashes and every pack path, byte hash and roster count",
      "source": "backend/app/services/actor_context.py:160-300,1049-1600; backend/app/services/simulation_manager.py:650-900"
    },
    {
      "id": "flow.prepare.actor_role_projection",
      "status": "live-default-for-researched-cast-with-sealed-v1-compatibility",
      "plane": "simulation/prepare/evidence",
      "producer": "actor-intelligence/v1 actor row plus its sealed actor-context/v1 pack",
      "transport": "Deterministic sanitized actor-role/v2 builder/compiler and adjacent role-manifest writer; no new model call",
      "payload": "Identity, values, incentives, motivations, capabilities/constraints, source-bound public relationships, decision triggers, current/future/investment plans, likely actions, red lines and knowledge boundary. All typed gaps persist in modeler uncertainty; actor text receives redacted summaries only. Complete report/dossier/source/context/cast provenance is sealed",
      "receiver": "Exact current-v1 role-only Reddit base/final system composition and newline-normalized Twitter user_char; no graph, persona LLM, rule or stub overlay can replace it",
      "persistence": "actor-role-manifest/v2 adjacent to each platform profile, binding role contract, context file/hash/manifest/report, compiled fragment hash, full runtime-field hash, transformations and roster/cast/profile hashes. Genuine sealed actor-role/v1 is read-only compatibility: it validates the original exact profile bytes and sealed runtime fragment hashes without recompiling through v2, and it cannot require actor context",
      "source": "backend/app/services/actor_role_prompt.py:160-1200; backend/app/services/oasis_profile_generator.py:62-120,2255-2520"
    },
    {
      "id": "flow.prepare.personas",
      "status": "live-default",
      "plane": "simulation/prepare",
      "producer": "OasisProfileGenerator",
      "transport": "Current actor-intelligence/v1 branches before graph retrieval, persona LLM, rule fallback and generic stubs; unversioned legacy actors retain the historical one-logical-persona-operation path",
      "payload": "Current v1 uses only the sealed actor-role/v2 behavior bytes. Reddit loader-required demographic placeholders are empty and its generated template is replaced; Twitter receives the exact role with required newline normalization. Structural name/type/bio fields carry no current-v1 behavior",
      "receiver": "Reddit deterministic role-only base system message and Twitter user_char, with platform role manifests binding exact serialized fields",
      "persistence": "twitter_profiles.csv, reddit_profiles.json, twitter_profiles_roles.json, reddit_profiles_roles.json and later reddit_runtime_system_messages.json final-byte attestation",
      "source": "backend/app/services/oasis_profile_generator.py:62-120,2255-3000; backend/scripts/run_parallel_simulation.py:573-700"
    },
    {
      "id": "flow.prepare.config",
      "status": "live-default",
      "plane": "simulation/prepare",
      "producer": "SimulationConfigGenerator",
      "transport": "Canonical shared calls receive only validated public actor-context; current-v1 per-agent behavior is deterministic and skips the profile/config LLM. Unversioned legacy retains graph/report/LLM/rule behavior",
      "payload": "Question, rounds, seed, temporal policy and sealed actor packs. Each current-v1 agent gets a 1,800-character actor-config-context/v1 behavior projection plus a separate exact typed actor-config-evidence-gap-audit/v1 capped at 64 KiB; private/inference/contested rows, flat role/stance/influence/memory, raw graph/report, unsealed relationships/events and fabricated demographics are excluded",
      "receiver": "SimulationManager base-config validator; after READY the outer orchestrator may apply an authorized scenario overlay and/or WorldState seed before SimulationRunner receives the ID",
      "persistence": "simulation_config.json plus simulation_config_manifest.json binding exact config, cast, context and platform-role manifests; state stores both hashes. Activity is neutral/source-bound, shared world is explicit-public only, relationships are public verified/actor-stated only, actor-local rows affect only their owner and scheduled events require public source bindings. Any authorized post-READY mutation triggers a complete rebuild and immediate validation of the seal before PREPARE completion",
      "source": "backend/app/services/simulation_config_generator.py:448-900,1892-3000,3336-3500; backend/app/services/simulation_manager.py:52-214,1240-1452; backend/app/services/pipeline_orchestrator.py:11545-11728"
    },
    {
      "id": "flow.prepare.ready_gate",
      "status": "live-default",
      "plane": "simulation/prepare",
      "producer": "SimulationManager actor-context/role/cast/profile/base-config validators",
      "transport": "Deterministic validation/state transition",
      "payload": "Exact actor-context packs, report/actors/actor-ID provenance, cast, both platform role/profile manifests, final runtime fields, simulation_config.json and simulation_config_manifest.json. Current-v1 missing/tampered config or any unmatched profile fails before READY; an authorized scenario-overlay or WorldState-seed mutation is admitted only through a complete reseal and immediate revalidation. Scenario-event replay is count-preserving and idempotent",
      "receiver": "Simulation state READY, followed when necessary by the outer orchestrator's authorized mutation/reseal gate before the run stage",
      "persistence": "state.json records context/role/config contract versions, counts, exact config+manifest hashes and validated artifacts; authorized post-READY mutations replace those hashes only after the rebuilt closure validates. Completed read-only reuse independently validates that state-bound seal, remains byte-identical and is never resealed",
      "source": "backend/app/services/simulation_manager.py:52-214,900-1100,1240-1452; backend/app/services/pipeline_orchestrator.py:7472-7577,11545-11728; backend/app/services/actor_context.py:1426-1601"
    },
    {
      "id": "flow.run.launch",
      "status": "live-default",
      "plane": "simulation/run",
      "producer": "SimulationRunner.start",
      "transport": "New-session Python subprocess",
      "payload": "Before every start/resume, exact READY state, context/cast/platform role/profile manifests and simulation-config seal are revalidated. The expected config manifest hash is passed as --config-seal; direct child validates adjacent state/manifest/config, then hashes the exact bytes it loads against the validated config SHA. Missing/tampered artifacts, check/use drift or any v2 downgrade fail closed",
      "receiver": "run_parallel_simulation.py",
      "persistence": "run_state.json, process identity, simulation.log",
      "source": "backend/app/services/simulation_runner.py:450-850; backend/scripts/run_parallel_simulation.py:1256-1331,4830-4847"
    },
    {
      "id": "flow.run.actor_rounds",
      "status": "live-default",
      "plane": "simulation/run/model",
      "producer": "Per-platform active-agent scheduler",
      "transport": "OASIS env.step with LLMAction through CAMEL/provider adapter",
      "payload": "For each selected actor, Twitter loads the manifest-bound newline-normalized actor-role/v2 user_char. Reddit replaces OASIS synthetic demographics with a deterministic structural wrapper plus the exact sealed role, then appends only sealed public world/calendar blocks; final effective _system_message bytes must match and are attested before model execution. Platform memory/state/tool schema remain dependency-owned runtime context",
      "receiver": "That actor's OASIS/CAMEL model receives its source-bound, epistemically local role on every active decision turn; selected actions reach Twitter or Reddit",
      "persistence": "reddit_runtime_system_messages.json, platform SQLite databases, action JSONL, checkpoints and telemetry",
      "source": "backend/app/services/oasis_profile_generator.py:62-120; backend/scripts/run_parallel_simulation.py:573-700,3500-4800"
    },
    {
      "id": "flow.run.platform_events",
      "status": "live-default",
      "plane": "simulation/run",
      "producer": "OASIS Twitter/Reddit environment",
      "transport": "Platform DB writes and action trace extraction",
      "payload": "Posts, comments, likes, follows, searches, interviews and other actions",
      "receiver": "Action logger, metrics, decision channel, API readers and runner monitor",
      "persistence": "twitter_actions.jsonl, reddit_actions.jsonl and platform SQLite databases",
      "source": "backend/scripts/run_parallel_simulation.py:3547-4715; backend/app/services/simulation_runner.py:1610-2075"
    },
    {
      "id": "flow.run.inband_decision_channel",
      "status": "live-default-when-seeded",
      "plane": "simulation/run/model",
      "producer": "Paired per-round Twitter/Reddit action buffers",
      "transport": "Batched application chat_json",
      "payload": "Unique actor roster, round evidence and seed scenarios; model output is only agent_id/scenario/magnitude/confidence, after which commitments and status are constructed deterministically",
      "receiver": "Decision parser and shared serial WorldState",
      "persistence": "Round decisions and decision-channel telemetry",
      "source": "backend/scripts/run_parallel_simulation.py:2834-3214; backend/app/services/decision_channel.py:213-305"
    },
    {
      "id": "flow.run.world_state",
      "status": "live-default-when-channel-active",
      "plane": "simulation/run",
      "producer": "Deterministically constructed committed decisions; abstained, silent, failed and missing outcomes do not advance state",
      "transport": "Serial WorldState.step",
      "payload": "Scenario commitments, inertia, entropy/calendar controls and round status",
      "receiver": "Projected diagnostic outcome state and next-round period context",
      "persistence": "world_state_trajectory.json, decisions.jsonl and world_digest.jsonl",
      "source": "backend/app/services/worldstate.py:81-304; backend/scripts/run_parallel_simulation.py:2989-3169"
    },
    {
      "id": "flow.run.posthoc_decision_fallback",
      "status": "live-conditional",
      "plane": "simulation/run/model",
      "producer": "Completed action logs only when the script-level _inband_traj_written flag is false; partial/incomplete existing in-band files are not inspected as a fallback trigger",
      "transport": "Parallel roster elicitation followed by serial WorldState evolution",
      "payload": "Social-simulation evidence grouped by round and actor",
      "receiver": "Same diagnostic world-state contract used by report stage",
      "persistence": "Decision artifacts and world-state trajectory",
      "source": "backend/app/services/decision_channel.py:535-775; backend/scripts/run_parallel_simulation.py:4700-4767"
    },
    {
      "id": "flow.run.ipc_command",
      "status": "live-conditional",
      "plane": "simulation/run/control",
      "producer": "Simulation interview/env API",
      "transport": "File-based command queue and response polling",
      "payload": "command_id, interview/env command, target actor/platform and prompt",
      "receiver": "Persistent live simulation subprocess",
      "persistence": "ipc_commands, ipc_responses and optional ipc_telemetry.jsonl",
      "source": "backend/app/services/simulation_ipc.py:30-250; backend/scripts/run_parallel_simulation.py:800-1010"
    },
    {
      "id": "flow.run.monitor",
      "status": "live-default",
      "plane": "simulation/run/control",
      "producer": "SimulationRunner monitor thread",
      "transport": "Two-second file/process/platform polling",
      "payload": "Action offsets, process status and platform terminal events; platform simulation_end events establish success even while the process remains alive for interview commands, and premature process exit is failure",
      "receiver": "run_state.json, progress callback and pipeline run stage",
      "persistence": "Run progress/status and final terminal reason",
      "source": "backend/app/services/simulation_runner.py:780-958"
    },
    {
      "id": "flow.run.summary",
      "status": "live-default",
      "plane": "simulation/run/evidence",
      "producer": "SimulationRunner terminal summarizer",
      "transport": "Deterministic read/aggregation and atomic JSON write",
      "payload": "Action logs, derived agent statistics/timeline/top posts, run_state coverage/error state, LLM health, dynamics/config metadata and optional communities; decision/WorldState artifacts are not read into this aggregate",
      "receiver": "Simulation health/reuse checks and simulation status/detail APIs; this file is not passed directly into the ReportAgent constructor",
      "persistence": "run_summary.json",
      "source": "backend/app/services/simulation_runner.py:1834-2106"
    },
    {
      "id": "flow.report.evidence_bundle",
      "status": "live-default",
      "plane": "forecast/publication",
      "producer": "Pipeline report stage",
      "transport": "In-process ReportAgent construction",
      "payload": "Graph ID, simulation ID, original question, situation brief, actors, sources, research report, scenario label, optional base-simulation ID, quantitative/contested/timeline evidence and structural graph priors. No run_summary/result/action payload is copied into the constructor",
      "receiver": "ReportAgent constructor, which retrieves graph and selected simulation detail through services using those IDs and loads market/current-price material plus ambient or pinned policy/config through its own managers",
      "persistence": "Report metadata/progress initialized under reports/<id>",
      "source": "backend/app/services/pipeline_orchestrator.py:8983-9155"
    },
    {
      "id": "flow.report.spine",
      "status": "live-default",
      "plane": "forecast/publication/model",
      "producer": "Report evidence loaders plus the separate pre-prose probability-spine builder",
      "transport": "Deterministic report-evidence normalization plus forecast-spine LLM draw(s)",
      "payload": "Report prose/tools can receive research, graph and labeled simulation diagnostics. Under default diagnostic_only, the probability spine separately receives research actor forecast inputs, situation brief, base rates/scenarios, markets and horizon/as-of with the simulation signal pack explicitly empty. Historical calibration is not a spine input",
      "receiver": "The wider report evidence spine feeds outline/sections; the pre-prose probability spine feeds the structured scenario contract",
      "persistence": "Report metadata and forecast-spine side data",
      "source": "backend/app/services/report_agent.py:9991-10147; backend/app/services/forecast_extractor.py:2780-3040"
    },
    {
      "id": "flow.report.outline_sections",
      "status": "live-default",
      "plane": "forecast/publication/model",
      "producer": "Evidence spine and outline model",
      "transport": "Bounded section workers using native tools or ReAct, then critique/revision/repair",
      "payload": "Section plans, evidence, graph/search/statistics/interview tools and citation rules",
      "receiver": "Ordered report section assembler",
      "persistence": "outline/progress, section_NN.md, agent and console logs",
      "source": "backend/app/services/report_agent.py:8843-10419"
    },
    {
      "id": "flow.report.tool_roundtrip",
      "status": "live-conditional-default-enabled",
      "plane": "forecast/publication/model",
      "producer": "Report section model",
      "transport": "Native tool call or textual ReAct action",
      "payload": "Graph search/statistics, web/search where allowed, or simulation interview request",
      "receiver": "Tool executor; observation returned to next section-model turn",
      "persistence": "Agent log/tool trace and resulting section evidence",
      "source": "backend/app/services/report_agent.py:9360-9960; backend/app/services/zep_tools.py:1600-2470"
    },
    {
      "id": "flow.report.progressive_sections",
      "status": "live-default",
      "plane": "client/publication",
      "producer": "ReportAgent section persistence",
      "transport": "Filesystem plus HTTP polling",
      "payload": "Progress, completed sections and current partial section",
      "receiver": "ForecastReport progressive renderer",
      "persistence": "Report progress and section files; UI state ephemeral",
      "source": "backend/app/api/report.py:1337-1584; frontend/src/components/research/ForecastReport.vue:832-897"
    },
    {
      "id": "flow.report.structured_forecast",
      "status": "live-default",
      "plane": "forecast/publication/model",
      "producer": "Pinned pre-prose probability spine plus post-assembly binary/market finalization; final report prose only on the no-spine fallback",
      "transport": "Pinned-spine reuse, binary draws, exact/near market matching, conditional divergence enforcement and deterministic reconciliation; post-hoc scenario extraction/critique is fallback-only and premortem is config-gated/default-off",
      "payload": "Question, horizon/as-of, pinned scenarios, research evidence/base rates and eligible market candidates. Default diagnostic_only excludes simulation from probability inputs; simulation can enter only under a separately promoted legacy policy",
      "receiver": "Forecast schema validator and publication gate",
      "persistence": "forecast.json and forecast audit/rationale fields",
      "source": "backend/app/services/forecast_extractor.py:646-720,970-1025,1720-1880,2285-3525"
    },
    {
      "id": "flow.report.citation_lint",
      "status": "live-default",
      "plane": "forecast/publication",
      "producer": "Assembled report and structured forecast",
      "transport": "Deterministic lint, citation stabilization and reference reconciliation",
      "payload": "Markdown, forecast, source registry and section metadata",
      "receiver": "Final audit and persistence",
      "persistence": "Citation map/audit/lint metadata and corrected report",
      "source": "backend/app/services/report_agent.py:10421-10437"
    },
    {
      "id": "flow.report.final_audit",
      "status": "live-default",
      "plane": "forecast/publication",
      "producer": "Exact final Markdown and forecast bytes",
      "transport": "Read-only deterministic audit and hashing",
      "payload": "Final artifacts, policy/contract requirements and referenced assets",
      "receiver": "Publication gate",
      "persistence": "final audit with artifact fingerprints",
      "source": "backend/app/services/report_agent.py:7340-7544,10439-10445"
    },
    {
      "id": "flow.report.persistence",
      "status": "live-default",
      "plane": "forecast/publication/store",
      "producer": "Report finalizer",
      "transport": "Atomic/content-addressed file writes",
      "payload": "Full report, metadata, forecast, citations, audit, sections, logs, telemetry and visualizations",
      "receiver": "Report APIs, frontend and export/feedback services",
      "persistence": "uploads/reports/<report_id>/",
      "source": "backend/app/services/report_agent.py:10469-10549,10712-10776,12991-13010"
    },
    {
      "id": "flow.report.publication_gate",
      "status": "live-default",
      "plane": "forecast/publication",
      "producer": "Report API serializer",
      "transport": "Publication-policy evaluation before response",
      "payload": "Completion/partial state, safety policy, artifact hashes, structured contracts and final audit",
      "receiver": "Frontend, download and optional v1 forecast clients",
      "persistence": "No new artifact; body/forecast suppressed when not publishable",
      "source": "backend/app/services/report_agent.py:11171-11334; backend/app/api/report.py:24-55"
    },
    {
      "id": "flow.report.translation",
      "status": "live-default-enabled-after-final-audit-language-conditional-plus-publishable-manual-api",
      "plane": "forecast/publication/model",
      "producer": "Eligible finalized English/Chinese primary under default REPORT_BILINGUAL=true after its audit (even if the primary audit failed), or a later manual request that requires a publishable primary; research-dossier translation is a separate process-local flow",
      "transport": "Automatic in-process bounded parallel translation units, or manual API cross-process lease/daemon task; both paths perform language audit/repair",
      "payload": "Markdown units, protected citations/data and target language",
      "receiver": "Opposite-language audited sidecar; exposure requires both primary and variant publication gates. Language/provider availability can make the automatic attempt inapplicable or failed without replacing the source",
      "persistence": "full_report.<lang>.md and translation status/audit sidecars",
      "source": "backend/app/api/report.py:555-796; backend/app/services/report_agent.py:6050-6685,10447-10455,10988-10991,11171-11205"
    },
    {
      "id": "flow.report.exports",
      "status": "live-conditional-default-enabled",
      "plane": "forecast/publication",
      "producer": "Publication-gated report",
      "transport": "Deterministic lazy builders and PDF subprocess/toolchain with locks/cache",
      "payload": "Sealed report bytes, language and exact dependency hashes",
      "receiver": "Markdown/PDF/brief/digest download clients",
      "persistence": "Content-addressed PDF/manifests, exec brief and digest files",
      "source": "backend/app/api/report.py:507-1115; backend/app/services/report_agent.py:12189-12310"
    },
    {
      "id": "flow.feedback.forecast_ledger",
      "status": "live-default",
      "plane": "feedback/evaluation",
      "producer": "Forecast finalization before final audit/publication, so a row can represent a later-unpublishable or duplicate raw report",
      "transport": "Append-only JSONL write",
      "payload": "Report ID, horizon/resolution date, scenarios/probabilities, confidence and unresolved status; current writer does not include objective_signals",
      "receiver": "Production ledger readers; no atomic linkage guarantees later publication or resolution",
      "persistence": "uploads/pipelines/_forecast_ledger/ledger.jsonl",
      "source": "backend/app/services/forecast_ledger.py:22-108; backend/app/services/report_agent.py:3086-3112"
    },
    {
      "id": "flow.feedback.resolution_monitor",
      "status": "config-gated-manual-cron",
      "plane": "feedback/evaluation",
      "producer": "Standalone resolution monitor",
      "transport": "Report/ledger reads plus read-only market HTTP",
      "payload": "Anchored binaries, current prices, market resolution state and manual due dates",
      "receiver": "Price history, resolution ledger, needs_manual result/Markdown section and monitor report",
      "persistence": "price_track.jsonl, _forecast_ledger/resolutions.jsonl and monitor_report.md",
      "source": "backend/scripts/resolution_monitor.py:1-704; backend/app/services/forecast_ledger.py:322-410"
    },
    {
      "id": "flow.feedback.manual_resolution",
      "status": "manual-compat-default-off",
      "plane": "feedback/evaluation",
      "producer": "POST /api/v1/resolve/<report_id>",
      "transport": "Backtest scoring and atomic JSON write",
      "payload": "Known outcome/resolution data for one publishable forecast",
      "receiver": "Brier/log-loss result and v1 forecast response",
      "persistence": "reports/<id>/resolved.json",
      "source": "backend/app/api/sdk.py:283-356; backend/app/services/backtest.py:41-70"
    },
    {
      "id": "flow.feedback.calibration",
      "status": "live-conditional",
      "plane": "feedback/evaluation",
      "producer": "Production ledger rows only when they themselves contain resolved outcomes; current manual resolved.json and market resolutions.jsonl paths do not update those rows",
      "transport": "Deterministic scoring/summary and optional logit recalibration fitting",
      "payload": "Forecast probabilities and known outcomes",
      "receiver": "Later ReportAgent historical-calibration/confidence annotation when eligible resolved production rows exist; it does not alter the already-derived pinned probabilities, and the current automatic outcome join is otherwise disconnected",
      "persistence": "Calibration summary/ledger state; evaluation rows remain in a separate evaluation ledger",
      "source": "backend/app/services/forecast_ledger.py:112-310; backend/app/services/backtest.py:188-237"
    },
    {
      "id": "flow.feedback.golden_eval",
      "status": "manual-compat",
      "plane": "feedback/evaluation",
      "producer": "Golden evaluation CLI",
      "transport": "Offline deterministic scoring",
      "payload": "Golden outcomes plus forecast file/evaluation ledger",
      "receiver": "Evaluation report and isolated evaluation ledger",
      "persistence": "_evaluation_ledger; never production calibration",
      "source": "backend/scripts/golden_eval.py:1-522; backend/app/services/forecast_ledger.py:112-184"
    },
    {
      "id": "flow.feedback.scheduled_rerun",
      "status": "config-gated-default-off",
      "plane": "feedback/operations",
      "producer": "Standalone scheduler daemon/tick or external cron",
      "transport": "Schedule-state scan then fresh PipelineOrchestrator.start",
      "payload": "Due prompt/options, concurrency/max-run limits and prior pipeline ID",
      "receiver": "New canonical pipeline and completion watcher",
      "persistence": "uploads/schedules/<id>/schedule.json and run history",
      "source": "backend/scripts/scheduled_rerun.py:157-295,556-780"
    },
    {
      "id": "flow.feedback.drift",
      "status": "config-gated-default-off",
      "plane": "feedback/operations",
      "producer": "Scheduled pipeline completion watcher",
      "transport": "Deterministic prior/new artifact comparison and optional webhook",
      "payload": "Forecast scenarios/probabilities, actor set and graph communities",
      "receiver": "Schedule drift history and external webhook",
      "persistence": "schedule.json drift_history",
      "source": "backend/scripts/scheduled_rerun.py:303-536,735-780"
    },
    {
      "id": "flow.feedback.multiseed",
      "status": "config-gated-inactive-at-default-one",
      "plane": "forecast/evaluation",
      "producer": "Primary report completion",
      "transport": "Bounded executor running extra prepare/run/report lanes",
      "payload": "Deterministic additional seeds and shared base evidence",
      "receiver": "Seed-specific reports and ensemble aggregator",
      "persistence": "handoff/ensemble_checkpoint.json and ensemble_forecast.json; primary report bytes remain sealed",
      "source": "backend/app/services/pipeline_orchestrator.py:4964-5175,9128-9138"
    },
    {
      "id": "flow.operations.telemetry",
      "status": "live-default",
      "plane": "operations",
      "producer": "LLM/model/stage/subprocess instrumentation",
      "transport": "ContextVars, process meter and bridge telemetry rollup",
      "payload": "Run/stage/provider/model calls, tokens, latency, cost estimates, errors and degradation flags",
      "receiver": "Run/stage telemetry snapshots and operator diagnostics",
      "persistence": "Pipeline/report/simulation telemetry artifacts",
      "source": "backend/app/utils/telemetry.py:19-229; backend/app/services/pipeline_orchestrator.py:6493-6698"
    },
    {
      "id": "flow.operations.supervisor",
      "status": "manual-compat",
      "plane": "operations",
      "producer": "scripts/start.sh",
      "transport": "Shell process management and HTTP readiness probes",
      "payload": "Frontend/backend start/stop/status command and environment",
      "receiver": "Flask/Vite processes and browser",
      "persistence": "PID files and frontend/backend logs",
      "source": "scripts/start.sh:193-693; package.json:5-19"
    },
    {
      "id": "flow.migration.drf2",
      "status": "pre-cutover",
      "plane": "migration",
      "producer": "Two distinct drf2 targets: a chat-native lead/custom-agent topology and a deterministic six-stage driver",
      "transport": "Chat topology uses KG/simulation stdio MCP; driver uses persistent Runs API slash-skill lead runs and KG MCP through skills. Its simulation HTTP client is provisional and has no matching implemented HTTP server adapter",
      "payload": "Custom-agent/skill exchanges or manifest-backed six-stage artifact contracts and deterministic gates",
      "receiver": "DRF2 chat thread/engine tools or deterministic run directory/manifest",
      "persistence": "drf2 state/manifest artifacts; not canonical live pipeline state",
      "source": "drf2/config/config.yaml:207-422; drf2/config/extensions_config.json:1-40; drf2/driver/pipeline.py:166-336; drf2/driver/harness_client.py:56-295; drf2/README.md:151-173"
    }
  ],
  "http_interfaces": [
    {"method":"GET","path":"/health","status":"live-default","input":"None","output":"Backend health JSON","owner":"backend/app/__init__.py:151"},

    {"method":"POST","path":"/api/research/run","status":"live-default","input":"JSON prompt, mode, optional project_name, depth, max_rounds, language/research_language and model","output":"Accepted pipeline_id, task_id, mode and initial status, or preflight/validation error","owner":"backend/app/api/research.py:43"},
    {"method":"POST","path":"/api/research/<pipeline_id>/cancel","status":"live-default","input":"Pipeline ID","output":"Cancellation acknowledgement/current state","owner":"backend/app/api/research.py:125"},
    {"method":"POST","path":"/api/research/<pipeline_id>/resume","status":"live-default","input":"Pipeline ID and optional JSON force","output":"Same pipeline restarted from reusable boundary or conflict/error","owner":"backend/app/api/research.py:140"},
    {"method":"POST","path":"/api/research/<pipeline_id>/continue","status":"live-default","input":"Completed research_only pipeline ID","output":"Same pipeline continued from ontology or state error","owner":"backend/app/api/research.py:177"},
    {"method":"POST","path":"/api/research/<pipeline_id>/scenario","status":"live-conditional","input":"JSON scenario label, overrides, injected events and/or as_of","output":"New fork pipeline/task IDs and lineage","owner":"backend/app/api/research.py:212"},
    {"method":"DELETE","path":"/api/research/<pipeline_id>","status":"live-default","input":"Terminated pipeline ID and optional dependent/force policy","output":"Deletion result or dependency/live-state conflict","owner":"backend/app/api/research.py:253"},
    {"method":"POST","path":"/api/research/clean","status":"live-default","input":"Optional JSON statuses, normally failed/cancelled","output":"Counts/IDs cleaned","owner":"backend/app/api/research.py:280"},
    {"method":"GET","path":"/api/research/status/<pipeline_id>","status":"live-default","input":"Pipeline ID","output":"Durable aggregate PipelineState with no-cache headers","owner":"backend/app/api/research.py:299"},
    {"method":"GET","path":"/api/research/list","status":"live-default","input":"None","output":"Recent durable pipeline summaries","owner":"backend/app/api/research.py:311"},
    {"method":"GET","path":"/api/research/preflight","status":"live-default","input":"Provider/model/environment query context","output":"Shared readiness result without starting a pipeline","owner":"backend/app/api/research.py:316"},
    {"method":"GET","path":"/api/research/<pipeline_id>/dossier","status":"live-default","input":"Pipeline ID","output":"Current handoff snapshot: report, actors, sources, timeline, quantitative/contested evidence, markets and charts; this route does not itself revalidate the research seal","owner":"backend/app/api/research.py:350"},
    {"method":"POST","path":"/api/research/<pipeline_id>/dossier/translations/<lang>","status":"live-conditional","input":"Pipeline ID and en/zh-like target language; no retry request body","output":"Accepted/deduplicated process-local translation task state","owner":"backend/app/api/research.py:514"},
    {"method":"GET","path":"/api/research/<pipeline_id>/dossier/translations/<lang>","status":"live-conditional","input":"Pipeline ID and language","output":"Translated research Markdown and audit/status","owner":"backend/app/api/research.py:551"},
    {"method":"GET","path":"/api/research/<pipeline_id>/dossier/pdf","status":"live-conditional","input":"Pipeline ID and optional lang query","output":"Research PDF through the shared exporter; this route does not itself enforce the research-contract seal","owner":"backend/app/api/research.py:584"},
    {"method":"PUT","path":"/api/research/<pipeline_id>/dossier","status":"live-conditional","input":"State-eligible pipeline ID plus replacement report/actors payload","output":"Atomically updated dossier contract or validation/state error","owner":"backend/app/api/research.py:638"},
    {"method":"GET","path":"/api/research/<pipeline_id>/artifact/<name>","status":"live-default","input":"Pipeline ID and logical artifact name resolved from PipelineState.artifacts","output":"Parsed JSON or safe text/file artifact content","owner":"backend/app/api/research.py:701"},
    {"method":"GET","path":"/api/research/<pipeline_id>/progress","status":"live-default","input":"Pipeline ID, scope=tail|full and bounded limits","output":"Exact full or bounded-tail progress event snapshot","owner":"backend/app/api/research.py:775"},

    {"method":"GET","path":"/api/graph/project/<project_id>","status":"manual-compat","input":"Project ID","output":"Project record including ontology/graph state","owner":"backend/app/api/graph.py:35"},
    {"method":"GET","path":"/api/graph/project/list","status":"manual-compat","input":"None/list query","output":"Project summaries","owner":"backend/app/api/graph.py:54"},
    {"method":"DELETE","path":"/api/graph/project/<project_id>","status":"manual-compat","input":"Project ID","output":"Project deletion result","owner":"backend/app/api/graph.py:69"},
    {"method":"POST","path":"/api/graph/project/<project_id>/reset","status":"manual-compat","input":"Project ID","output":"Project graph-build state reset result","owner":"backend/app/api/graph.py:88"},
    {"method":"POST","path":"/api/graph/ontology/generate","status":"manual-compat","input":"Multipart files and/or requirement/project metadata","output":"Synchronous completed project, ontology, file and extracted-text-length data","owner":"backend/app/api/graph.py:121"},
    {"method":"POST","path":"/api/graph/build","status":"manual-compat","input":"JSON project_id and graph-build options","output":"Async graph task/graph ID state","owner":"backend/app/api/graph.py:259"},
    {"method":"GET","path":"/api/graph/task/<task_id>","status":"manual-compat","input":"Task ID","output":"In-process graph task status/progress/result","owner":"backend/app/api/graph.py:533"},
    {"method":"GET","path":"/api/graph/tasks","status":"manual-compat","input":"None","output":"Current graph task summaries","owner":"backend/app/api/graph.py:552"},
    {"method":"GET","path":"/api/graph/data/<graph_id>","status":"live-default","input":"Graph ID and optional top_k, min_degree, slim and full queries","output":"Nodes, edges, metadata/counts and optional full fields/positions","owner":"backend/app/api/graph.py:576"},
    {"method":"GET","path":"/api/graph/data/<graph_id>/neighbors/<node_uuid>","status":"live-default","input":"Graph/node IDs and optional depth and slim queries","output":"Bounded neighborhood subgraph","owner":"backend/app/api/graph.py:621"},
    {"method":"GET","path":"/api/graph/data/<graph_id>/node/<node_uuid>","status":"live-default","input":"Graph/node IDs","output":"Full node fields omitted from slim list","owner":"backend/app/api/graph.py:642"},
    {"method":"GET","path":"/api/graph/data/<graph_id>/edge/<edge_uuid>","status":"live-default","input":"Graph/edge IDs","output":"Full edge fact, episode, attributes and timestamps","owner":"backend/app/api/graph.py:659"},
    {"method":"POST","path":"/api/graph/gc","status":"manual-compat","input":"Optional JSON retain count","output":"Stale unreferenced graph collection result","owner":"backend/app/api/graph.py:676"},
    {"method":"DELETE","path":"/api/graph/delete/<graph_id>","status":"manual-compat","input":"Graph ID","output":"Graph deletion result; route has no dependency/reference-conflict guard","owner":"backend/app/api/graph.py:700"},

    {"method":"GET","path":"/api/simulation/entities/<graph_id>","status":"manual-compat","input":"Graph ID and filters","output":"Filtered graph entities for simulation selection","owner":"backend/app/api/simulation.py:47"},
    {"method":"GET","path":"/api/simulation/entities/<graph_id>/<entity_uuid>","status":"manual-compat","input":"Graph and entity IDs","output":"Entity detail","owner":"backend/app/api/simulation.py:92"},
    {"method":"GET","path":"/api/simulation/entities/<graph_id>/by-type/<entity_type>","status":"manual-compat","input":"Graph ID and entity type","output":"Entities of requested type","owner":"backend/app/api/simulation.py:125"},
    {"method":"POST","path":"/api/simulation/create","status":"manual-compat","input":"JSON project_id, optional graph_id, enable_twitter and enable_reddit","output":"New simulation ID and initial manager state","owner":"backend/app/api/simulation.py:164"},
    {"method":"POST","path":"/api/simulation/prepare","status":"manual-compat","input":"JSON simulation_id plus optional entity_types, use_llm_for_profiles, parallel_profile_count and force_regenerate; project/graph/report/actors resolve from the simulation lineage","output":"Async task/preparing state or already-ready response; preparation seals per-actor context/role/profile/config artifacts before READY, otherwise returns the exact contract/coverage error","owner":"backend/app/api/simulation.py:399"},
    {"method":"POST","path":"/api/simulation/prepare/status","status":"manual-compat","input":"JSON preparation task/simulation ID","output":"Preparation progress, profiles/config previews and errors","owner":"backend/app/api/simulation.py:678"},
    {"method":"GET","path":"/api/simulation/<simulation_id>","status":"manual-compat","input":"Simulation ID","output":"Durable simulation manager state","owner":"backend/app/api/simulation.py:791"},
    {"method":"GET","path":"/api/simulation/list","status":"manual-compat","input":"Optional filters","output":"Simulation summaries","owner":"backend/app/api/simulation.py:824"},
    {"method":"GET","path":"/api/simulation/history","status":"manual-compat","input":"Optional limit query","output":"Simulation history enriched with project detail","owner":"backend/app/api/simulation.py:912"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/profiles","status":"manual-compat","input":"Simulation ID","output":"Final OASIS profiles and role metadata","owner":"backend/app/api/simulation.py:1026"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/profiles/realtime","status":"live-default","input":"Simulation ID and optional platform query","output":"Profiles generated so far and preparation progress","owner":"backend/app/api/simulation.py:1064"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/config/realtime","status":"manual-compat","input":"Simulation ID","output":"Configuration generated so far and progress","owner":"backend/app/api/simulation.py:1174"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/config","status":"manual-compat","input":"Simulation ID","output":"Final simulation_config content","owner":"backend/app/api/simulation.py:1294"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/config/download","status":"manual-compat","input":"Simulation ID","output":"Simulation config file download","owner":"backend/app/api/simulation.py:1330"},
    {"method":"GET","path":"/api/simulation/script/<script_name>/download","status":"manual-compat","input":"Allowlisted backend script name","output":"Simulation runner script download","owner":"backend/app/api/simulation.py:1359"},
    {"method":"POST","path":"/api/simulation/generate-profiles","status":"manual-compat","input":"JSON graph/actor/profile-generation options","output":"Generated OASIS profiles without creating a simulation","owner":"backend/app/api/simulation.py:1413"},
    {"method":"POST","path":"/api/simulation/start","status":"manual-compat","input":"JSON simulation_id plus optional platform (twitter/reddit/parallel), max_rounds, enable_graph_memory_update and force","output":"Run accepted/current state only after runner revalidates actor-context and all prepared platform role/profile seals; otherwise provenance, missing-artifact, downgrade, coverage or ordinary validation conflict","owner":"backend/app/api/simulation.py:1487"},
    {"method":"POST","path":"/api/simulation/stop","status":"manual-compat","input":"JSON simulation_id","output":"Stop acknowledgement and updated run state","owner":"backend/app/api/simulation.py:1685"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/run-status","status":"live-default","input":"Simulation ID","output":"Realtime aggregate run status/progress","owner":"backend/app/api/simulation.py:1746"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/run-status/detail","status":"manual-compat","input":"Simulation ID and optional platform query","output":"Detailed run status including action data","owner":"backend/app/api/simulation.py:1804"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/actions","status":"manual-compat","input":"Simulation ID and pagination/platform filters","output":"Agent action history","owner":"backend/app/api/simulation.py:1904"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/timeline","status":"manual-compat","input":"Simulation ID and optional start_round/end_round queries","output":"Actions/events aggregated by round/time period","owner":"backend/app/api/simulation.py:1958"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/agent-stats","status":"live-default","input":"Simulation ID","output":"Per-agent action/engagement statistics","owner":"backend/app/api/simulation.py:1998"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/posts","status":"live-default","input":"Simulation ID plus platform/pagination filters","output":"Simulated posts","owner":"backend/app/api/simulation.py:2027"},
    {"method":"GET","path":"/api/simulation/<simulation_id>/comments","status":"live-default","input":"Simulation ID plus platform/post/pagination filters","output":"Simulated comments","owner":"backend/app/api/simulation.py:2105"},
    {"method":"POST","path":"/api/simulation/interview","status":"live-conditional","input":"JSON simulation_id, agent_id, prompt and optional platform","output":"One live-environment actor interview response","owner":"backend/app/api/simulation.py:2191"},
    {"method":"POST","path":"/api/simulation/interview/batch","status":"live-conditional","input":"JSON simulation_id and interview list","output":"Per-platform/per-agent batch interview results","owner":"backend/app/api/simulation.py:2320"},
    {"method":"POST","path":"/api/simulation/interview/all","status":"live-conditional","input":"JSON simulation_id, shared prompt and platform/options","output":"Interview results for all eligible agents","owner":"backend/app/api/simulation.py:2458"},
    {"method":"POST","path":"/api/simulation/interview/history","status":"manual-compat","input":"JSON simulation_id and optional filters","output":"Persisted/collected interview history","owner":"backend/app/api/simulation.py:2561"},
    {"method":"POST","path":"/api/simulation/env-status","status":"live-conditional","input":"JSON simulation_id","output":"Persistent subprocess/platform/IPC environment status","owner":"backend/app/api/simulation.py:2633"},
    {"method":"POST","path":"/api/simulation/close-env","status":"live-conditional","input":"JSON simulation_id","output":"Environment close acknowledgement/status","owner":"backend/app/api/simulation.py:2698"},

    {"method":"POST","path":"/api/report/generate","status":"manual-compat","input":"JSON simulation_id, graph/project context, prompt and report options","output":"Independent async report task/report IDs","owner":"backend/app/api/report.py:78"},
    {"method":"POST","path":"/api/report/generate/status","status":"manual-compat","input":"JSON report/task ID","output":"Generation progress/result/error","owner":"backend/app/api/report.py:279"},
    {"method":"GET","path":"/api/report/<report_id>","status":"live-default","input":"Report ID","output":"Publication-gated report metadata/body/forecast links or suppressed body with gate state","owner":"backend/app/api/report.py:354"},
    {"method":"GET","path":"/api/report/<report_id>/forecast","status":"live-default","input":"Report ID","output":"Publication-gated structured forecast","owner":"backend/app/api/report.py:396"},
    {"method":"GET","path":"/api/report/by-simulation/<simulation_id>","status":"manual-compat","input":"Simulation ID","output":"Associated report summary/detail","owner":"backend/app/api/report.py:428"},
    {"method":"GET","path":"/api/report/list","status":"manual-compat","input":"Optional filters/pagination","output":"Report summaries","owner":"backend/app/api/report.py:467"},
    {"method":"GET","path":"/api/report/<report_id>/download","status":"live-default","input":"Report ID; no language/format query","output":"Publication-gated primary Markdown download","owner":"backend/app/api/report.py:507"},
    {"method":"GET","path":"/api/report/<report_id>/full_report.<lang>.md","status":"live-conditional","input":"Report ID and language","output":"Generated language-variant Markdown","owner":"backend/app/api/report.py:555"},
    {"method":"POST","path":"/api/report/<report_id>/translations/<lang>","status":"live-conditional","input":"Report ID and language; no retry request body","output":"Accepted/deduplicated publication-gated translation task","owner":"backend/app/api/report.py:602"},
    {"method":"GET","path":"/api/report/<report_id>/translations/<lang>/status","status":"live-conditional","input":"Report ID, language and optional task_id query","output":"Durable translation artifact/audit state plus live task progress","owner":"backend/app/api/report.py:750"},
    {"method":"GET","path":"/api/report/<report_id>/pdf","status":"live-conditional","input":"Report ID and optional language/query","output":"Publication-bound cached/generated PDF","owner":"backend/app/api/report.py:801"},
    {"method":"GET","path":"/api/report/<report_id>/exec-brief","status":"live-conditional","input":"Report ID and optional language","output":"Deterministic lazy executive brief Markdown","owner":"backend/app/api/report.py:870"},
    {"method":"GET","path":"/api/report/<report_id>/exec-brief.pdf","status":"live-conditional","input":"Report ID and optional language","output":"Executive brief PDF","owner":"backend/app/api/report.py:930"},
    {"method":"GET","path":"/api/report/<report_id>/digest","status":"live-conditional","input":"Report ID","output":"Deterministic short newsletter-style digest","owner":"backend/app/api/report.py:989"},
    {"method":"GET","path":"/api/report/<report_id>/charts/<path:filename>","status":"live-default","input":"Report ID and safe PNG/SVG/JPG/JPEG/GIF/WebP/HTML chart path","output":"Validated chart or interactive visualization file","owner":"backend/app/api/report.py:1043"},
    {"method":"GET","path":"/api/report/<report_id>/viz-manifest","status":"live-default","input":"Report ID","output":"Normalized legacy or schema-v2 visualization manifest","owner":"backend/app/api/report.py:1115"},
    {"method":"DELETE","path":"/api/report/<report_id>","status":"manual-compat","input":"Report ID","output":"Deletion result","owner":"backend/app/api/report.py:1207"},
    {"method":"POST","path":"/api/report/chat","status":"manual-compat","input":"JSON report/context identifier, message and chat_history","output":"ReportAgent answer, optionally evidence-grounded revised answer","owner":"backend/app/api/report.py:1235"},
    {"method":"GET","path":"/api/report/<report_id>/progress","status":"manual-compat","input":"Report ID","output":"Realtime report progress/status","owner":"backend/app/api/report.py:1337"},
    {"method":"GET","path":"/api/report/<report_id>/sections","status":"manual-compat","input":"Report ID","output":"Completed section list/content","owner":"backend/app/api/report.py:1378"},
    {"method":"GET","path":"/api/report/<report_id>/sections-partial","status":"live-default","input":"Report ID; no revision cursor","output":"Root-shaped response with sections and done for polling","owner":"backend/app/api/report.py:1439"},
    {"method":"GET","path":"/api/report/<report_id>/section/<int:section_index>","status":"manual-compat","input":"Report ID and section index","output":"One section and status/metadata","owner":"backend/app/api/report.py:1535"},
    {"method":"GET","path":"/api/report/check/<simulation_id>","status":"manual-compat","input":"Simulation ID","output":"Whether a report exists and its status/ID","owner":"backend/app/api/report.py:1585"},
    {"method":"GET","path":"/api/report/<report_id>/agent-log","status":"manual-compat","input":"Report ID and optional tail query","output":"Detailed ReportAgent log snapshot","owner":"backend/app/api/report.py:1642"},
    {"method":"GET","path":"/api/report/<report_id>/agent-log/stream","status":"manual-compat","input":"Report ID","output":"Complete current agent log as one JSON response, despite stream-compatible name","owner":"backend/app/api/report.py:1701"},
    {"method":"GET","path":"/api/report/<report_id>/console-log","status":"manual-compat","input":"Report ID and optional tail query","output":"Report console log snapshot","owner":"backend/app/api/report.py:1737"},
    {"method":"GET","path":"/api/report/<report_id>/console-log/stream","status":"manual-compat","input":"Report ID","output":"Complete current console log as one JSON response","owner":"backend/app/api/report.py:1783"},
    {"method":"POST","path":"/api/report/tools/search","status":"manual-compat","input":"JSON graph_id/query/search options","output":"Graph search tool result for debugging","owner":"backend/app/api/report.py:1819"},
    {"method":"POST","path":"/api/report/tools/statistics","status":"manual-compat","input":"JSON graph_id/statistics options","output":"Graph statistics tool result for debugging","owner":"backend/app/api/report.py:1867"},

    {"method":"GET","path":"/api/settings/llm","status":"live-default","input":"None","output":"Sanitized current LLM provider/model settings without secrets","owner":"backend/app/api/settings.py:25"},
    {"method":"POST","path":"/api/settings/llm","status":"live-default","input":"JSON provider/model/base URL/key and related settings","output":"Validated/persisted sanitized configuration or error","owner":"backend/app/api/settings.py:30"},
    {"method":"POST","path":"/api/settings/llm/test","status":"live-default","input":"Ephemeral provider configuration","output":"Connectivity/model probe result; configuration is not persisted","owner":"backend/app/api/settings.py:151"},

    {"method":"POST","path":"/api/v1/run","status":"config-gated-default-off","input":"Stable JSON run contract","output":"pipeline_id, task_id, mode and status","owner":"backend/app/api/sdk.py:76"},
    {"method":"GET","path":"/api/v1/status/<pipeline_id>","status":"config-gated-default-off","input":"Pipeline ID","output":"Durable aggregate pipeline status","owner":"backend/app/api/sdk.py:156"},
    {"method":"GET","path":"/api/v1/list","status":"config-gated-default-off","input":"None","output":"Recent pipeline summaries","owner":"backend/app/api/sdk.py:173"},
    {"method":"GET","path":"/api/v1/dossier/<pipeline_id>","status":"config-gated-default-off","input":"Pipeline ID","output":"Research report and structured dossier/source/timeline artifacts","owner":"backend/app/api/sdk.py:186"},
    {"method":"GET","path":"/api/v1/forecast/<report_id>","status":"config-gated-default-off","input":"Report ID","output":"Publication-gated machine forecast plus optional manual resolution","owner":"backend/app/api/sdk.py:238"},
    {"method":"POST","path":"/api/v1/resolve/<report_id>","status":"config-gated-default-off","input":"Known outcome/resolution JSON","output":"Brier/log-loss scoring and persisted resolution record","owner":"backend/app/api/sdk.py:283"}
  ]
}