yf176 commited on
Commit
038d10f
·
1 Parent(s): 0887bee

docs: define V8 agent contracts storage ACL and UI

Browse files
Files changed (1) hide show
  1. docs/polyhedraV8.0.md +628 -137
docs/polyhedraV8.0.md CHANGED
@@ -153,144 +153,259 @@ Permissions apply within the active session and the agent's effective ticker
153
  scope. Unlisted artifacts are inaccessible through the runtime file interface.
154
  All entries are filenames or filename templates relative to the session folder,
155
  including subdirectories. They are not logical artifact identifiers.
156
- `{ticker}` resolves only to tickers in the agent's effective scope; `{date}`
157
- identifies the artifact date within the session, including prior dates needed
158
- for delta comparisons. Listing returns only filenames allowed by `list`;
159
  reading their contents separately requires `read` permission.
160
 
161
  #### ACL Table
162
 
163
- These permissions are the V8.0 draft based on existing artifact usage. The
164
- table covers all 19 registered quant agents; it does not claim that runtime ACL
165
- enforcement is already implemented.
 
 
 
 
 
 
 
166
 
167
  | Agent | `read` | `create` | `edit` | `list` |
168
  |---|---|---|---|---|
169
- | `DataFetcher` | `[quant/raw/{ticker}_{date}.json, quant/raw/{ticker}_{date}_summary.md]` | `[quant/raw/{ticker}_{date}.json, quant/raw/{ticker}_{date}_summary.md]` | `[quant/raw/{ticker}_{date}.json, quant/raw/{ticker}_{date}_summary.md]` | `[quant/raw/{ticker}_{date}.json, quant/raw/{ticker}_{date}_summary.md]` |
170
- | `OptionsFlowWatcher` | `[]` | `[quant/options_flow_{date}.md]` | `[quant/options_flow_{date}.md]` | `[]` |
171
- | `TrendAnalyst` | `[quant/raw/{ticker}_{date}_summary.md]` | `[quant/trend_analysis_{date}.md]` | `[quant/trend_analysis_{date}.md]` | `[quant/raw/{ticker}_{date}_summary.md]` |
172
- | `SentimentAnalyst` | `[quant/raw/{ticker}_{date}_summary.md, quant/trend_analysis_{date}.md]` | `[quant/sentiment_analysis_{date}.md]` | `[quant/sentiment_analysis_{date}.md]` | `[quant/raw/{ticker}_{date}_summary.md]` |
173
- | `MarketEventWatcher` | `[quant/raw/{ticker}_{date}_summary.md, quant/trend_analysis_{date}.md]` | `[quant/market_events_{date}.md]` | `[quant/market_events_{date}.md]` | `[quant/raw/{ticker}_{date}_summary.md]` |
174
- | `MacroContextWatcher` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md]` | `[quant/macro_context_{date}.md]` | `[quant/macro_context_{date}.md]` | `[]` |
175
- | `UnusualEventDetector` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md]` | `[quant/unusual_events_{date}.md]` | `[quant/unusual_events_{date}.md]` | `[]` |
176
- | `EventRouter` | `[quant/unusual_events_{date}.md, quant/market_events_{date}.md, quant/options_flow_{date}.md]` | `[quant/event_route_{date}.md]` | `[quant/event_route_{date}.md]` | `[]` |
177
- | `BTCAnalyst` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md, quant/event_route_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md]` | `[quant/btc_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[quant/btc_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[]` |
178
- | `SPYAnalyst` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md, quant/event_route_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md]` | `[quant/spy_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[quant/spy_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[]` |
179
- | `QQQAnalyst` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md, quant/event_route_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md]` | `[quant/qqq_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[quant/qqq_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[]` |
180
- | `GLDAnalyst` | `[quant/market_events_{date}.md, quant/options_flow_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md, quant/event_route_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md]` | `[quant/gld_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[quant/gld_analysis_{date}.md, quant/asset_analysis_{date}.md]` | `[]` |
181
- | `QuantResearcher` | `[quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md, quant/asset_analysis_{date}.md, quant/macro_context_{date}.md, quant/unusual_events_{date}.md]` | `[quant/signals_{date}.md]` | `[quant/signals_{date}.md]` | `[]` |
182
- | `Backtester` | `[quant/signals_{date}.md, quant/raw/{ticker}_{date}_summary.md]` | `[quant/backtest_results_{date}.md]` | `[quant/backtest_results_{date}.md]` | `[quant/raw/{ticker}_{date}_summary.md]` |
183
- | `RiskAnalyst` | `[quant/backtest_results_{date}.md, quant/trend_analysis_{date}.md, quant/asset_analysis_{date}.md, quant/macro_context_{date}.md]` | `[quant/risk_assessment_{date}.md]` | `[quant/risk_assessment_{date}.md]` | `[]` |
184
- | `QuantStrategist` | `[quant/risk_assessment_{date}.md, quant/backtest_results_{date}.md, quant/sentiment_analysis_{date}.md, quant/signals_{date}.md, quant/asset_analysis_{date}.md, quant/macro_context_{date}.md, quant/strategist_performance.json]` | `[quant/trade_proposals_{date}.md, quant/strategist_performance.json]` | `[quant/trade_proposals_{date}.md, quant/strategist_performance.json]` | `[]` |
185
- | `Publisher` | `[quant/trade_proposals_{date}.md, quant/trend_analysis_{date}.md, quant/sentiment_analysis_{date}.md, quant/risk_assessment_{date}.md, quant/asset_analysis_{date}.md, quant/macro_context_{date}.md]` | `[quant/post_{date}.md]` | `[quant/post_{date}.md]` | `[]` |
186
- | `VizAgent` | `[quant/raw/{ticker}_{date}.json, quant/backtest_results_{date}.md, quant/risk_assessment_{date}.md]` | `[quant/viz/candlestick_{ticker}_{date}.png, quant/viz/rsi_macd_{ticker}_{date}.png, quant/viz/backtest_{date}.png, quant/viz/risk_heatmap_{date}.png, quant/viz/portfolio_pnl_{date}.png]` | `[quant/viz/candlestick_{ticker}_{date}.png, quant/viz/rsi_macd_{ticker}_{date}.png, quant/viz/backtest_{date}.png, quant/viz/risk_heatmap_{date}.png, quant/viz/portfolio_pnl_{date}.png]` | `[quant/raw/{ticker}_{date}.json]` |
187
- | `PortfolioMonitor` | `[]` | `[quant/portfolio_log_{date}.md]` | `[quant/portfolio_log_{date}.md]` | `[]` |
 
 
 
 
 
188
 
189
  #### Baseline File Permissions
190
 
191
- These lists extend the corresponding agent's `read` and `list` permissions
192
- above for session-delta runs. `{baseline}` is the runtime-selected existing
193
- baseline directory inside this session. `{date}` is the saved artifact date.
194
- No agent receives `create` or `edit` permission for baseline files. The
195
- runtime preserves those snapshots. Trade-state context uses the selected
196
- proposal or no-trade/watch file when available.
197
 
198
  | Agent | Additional `read` | Additional `list` |
199
  |---|---|---|
200
- | `DataFetcher` | `[quant/yolo_baselines/{baseline}/quant/raw/{ticker}_{date}_summary.md]` | `[quant/yolo_baselines/{baseline}/quant/raw/{ticker}_{date}_summary.md]` |
201
- | `OptionsFlowWatcher` | `[quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
202
- | `TrendAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
203
- | `SentimentAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
204
- | `MarketEventWatcher` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
205
- | `MacroContextWatcher` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
206
- | `UnusualEventDetector` | `[quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
207
- | `EventRouter` | `[quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
208
- | `BTCAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
209
- | `SPYAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
210
- | `QQQAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
211
- | `GLDAnalyst` | `[quant/yolo_baselines/{baseline}/quant/trend_analysis_{date}.md, quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
212
- | `QuantResearcher` | `[quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/backtest_results_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
213
- | `Backtester` | `[quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/backtest_results_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md]` | `[]` |
214
- | `RiskAnalyst` | `[quant/yolo_baselines/{baseline}/quant/backtest_results_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
215
- | `QuantStrategist` | `[quant/yolo_baselines/{baseline}/quant/signals_{date}.md, quant/yolo_baselines/{baseline}/quant/backtest_results_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md, quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md]` | `[]` |
216
- | `Publisher` | `[quant/yolo_baselines/{baseline}/quant/trade_proposals_{date}.md, quant/yolo_baselines/{baseline}/quant/no_trade_watch_{date}.md, quant/yolo_baselines/{baseline}/quant/post_{date}.md, quant/yolo_baselines/{baseline}/quant/risk_assessment_{date}.md]` | `[]` |
217
  | `VizAgent` | `[]` | `[]` |
218
  | `PortfolioMonitor` | `[]` | `[]` |
219
 
220
  #### Permission Boundaries
221
 
222
- - For dated files, `create` and `edit` refer to working outputs for the current run's date.
223
- Historical working files and baseline snapshots are read-only context.
224
- - Read permission does not add a Routing Table dependency or imply that an
225
- optional file is available. For example, current trend context is an optional
226
- input to `SentimentAnalyst` and `MarketEventWatcher` under the agreed routing.
227
- - `DataFetcher` no longer needs to read trend output solely to choose the next
228
- agent; that decision belongs to the Routing Table.
229
- - Helpers acting for an agent, including provider writers and committee
230
- tracking, use that agent's runtime-controlled permissions.
231
- - Writes to `quant/strategist_performance.json` are performed by the trusted
232
- performance tracker for `QuantStrategist`. LLM-emitted weights do not replace
233
- runtime-owned weights.
234
- - The shared `quant/asset_analysis_{date}.md` entries record the existing
235
- append behavior of all four asset analysts. Filename ACL alone cannot limit
236
- an edit to one analyst's section. Shared-file ownership and parallel writes
237
- must be settled with typed schemas and artifact storage before this ACL is
238
- implemented.
239
- - Shared reports may contain multiple tickers. Their filename permission alone
240
- does not enforce the effective ticker scope; the typed input contract must
241
- define the scope-filtered content exposed to each agent.
242
- - Session metadata, selected portfolio state, prior backtest state, and recent
243
- conversation context currently arrive through runtime inputs. These tables
244
- do not grant agents unrestricted access to `research_state.json` or
245
- `thread.jsonl`. Their allowed input fields remain part of the typed-schema
246
- discussion. Runtime state patches, traces, snapshots, and evidence-ledger
247
- writes remain runtime-owned.
248
- - Listing and RAG retrieval must observe the same session and filename
249
- permissions. Final storage changes must update these tables accordingly.
250
-
 
251
 
252
  #### File Content Reference
253
 
254
- This table explains the files referenced by the ACL above using their current
255
- contents and explicitly identified V8 changes. Exact typed schemas remain a
256
- separate design step. A listed filename describes an artifact contract, not a
257
- guarantee that a provider or agent successfully produced it in every run.
258
 
259
- | Filename relative to session folder | Format | Content | Purpose |
260
- |---|---|---|---|
261
- | `quant/raw/{ticker}_{date}.json` | JSON | Ticker and fetch timestamp; available daily OHLCV history; computed SMA-20, EMA-20, RSI-14, and MACD series; news records; earnings records where applicable; provider errors, partial-fetch indicators, and OHLCV quality metadata when present. | Structured fetched market dataset used to generate summaries and support downstream analysis. Despite the `raw` directory name, this file contains normalized data and computed indicators rather than an untouched API response. |
262
- | `quant/raw/{ticker}_{date}_summary.md` | Markdown | Ticker and fetch timestamp; data-quality notes and excluded rows when present; latest 10 available OHLCV rows; latest technical-indicator values; up to 15 news headlines with available sentiment fields; up to four quarterly earnings records where applicable; a prior-baseline summary excerpt during session-delta runs when available. | Readable market-data context for downstream agents, including context for comparing the current run with the previous baseline. |
263
- | `quant/trend_analysis_{date}.md` | Markdown | Technical interpretation of price structure, indicators, trend direction, and uncertainty; delta observations where available. | Technical context produced by TrendAnalyst. |
264
- | `quant/sentiment_analysis_{date}.md` | Markdown | News and earnings sentiment assessment, cited themes, sentiment/technical alignment, and insufficient-data notes. | Sentiment context produced by SentimentAnalyst. |
265
- | `quant/market_events_{date}.md` | Markdown | In-scope raw summary excerpts, optional existing trend context, check timestamp, and prior-session context. | Market context assembled by MarketEventWatcher; the current implementation does not fetch a separate event feed. |
266
- | `quant/options_flow_{date}.md` | Markdown | Options provider status and timestamp, sampled contracts and expirations, call/put volume, open interest, IV summaries, preliminary FLOW_CANDIDATE observations, and explicit data gaps. | Options evidence from OptionsFlowWatcher, distinguishing options-chain context from unsupported unusual-flow claims. |
267
- | `quant/macro_context_{date}.md` | Markdown | LLM macro main-line assessment, candidate drivers, relevance weights, confidence, uncertainty, and affected markets, or an explicit analysis-unavailable result. | Macro interpretation produced by MacroContextWatcher. |
268
- | `quant/unusual_events_{date}.md` | Markdown | LLM event candidates with event type, affected markets, significance, rationale, and missing evidence; a no-meaningful-event assessment where appropriate. | Event detection output from UnusualEventDetector. |
269
- | `quant/event_route_{date}.md` | Markdown | Currently selected symbols, selected analyst names, rationale, and delta context. V8 uses this output for event-to-ticker evidence assignments under the fixed Routing Table. | Evidence assignment output from EventRouter; it cannot activate agents in V8. |
270
- | `quant/btc_analysis_{date}.md` | Markdown | BTC market interpretation, weighted signals, confidence, setup hypothesis, confirmation/invalidation conditions, and recommended outcome or explicit analysis failure. | Individual output of BTCAnalyst. |
271
- | `quant/spy_analysis_{date}.md` | Markdown | SPY market interpretation, weighted signals, confidence, setup hypothesis, confirmation/invalidation conditions, and recommended outcome or explicit analysis failure. | Individual output of SPYAnalyst. |
272
- | `quant/qqq_analysis_{date}.md` | Markdown | QQQ market interpretation, weighted signals, confidence, setup hypothesis, confirmation/invalidation conditions, and recommended outcome or explicit analysis failure. | Individual output of QQQAnalyst. |
273
- | `quant/gld_analysis_{date}.md` | Markdown | GLD market interpretation, weighted signals, confidence, setup hypothesis, confirmation/invalidation conditions, and recommended outcome or explicit analysis failure. | Individual output of GLDAnalyst. |
274
- | `quant/asset_analysis_{date}.md` | Markdown | Combined ticker-labelled sections appended by the specialized analysts. | Shared specialized-analysis input for QuantResearcher, RiskAnalyst, QuantStrategist, and Publisher; write ownership remains a storage decision. |
275
- | `quant/signals_{date}.md` | Markdown | Named signal hypotheses, entry/exit conditions, confidence, falsification criteria, and run/delta updates. | QuantResearcher output for Backtester and strategy review. |
276
- | `quant/backtest_results_{date}.md` | Markdown | LLM-produced backtest assessment from supplied signals and market summaries, approximate metrics, assumptions, and limitations. | Backtester output for risk and strategy review; its presence alone does not establish an executed historical experiment. |
277
- | `quant/risk_assessment_{date}.md` | Markdown | Risk ratings, concentration/correlation and drawdown assessment, scenarios, and risk verdicts using available analysis and portfolio context. | RiskAnalyst output consumed before strategy decisions. |
278
- | `quant/trade_proposals_{date}.md` | Markdown | Strategy-review narrative, committee summary, prior proposal lifecycle updates, and paper-trading conclusions. Structured proposals also travel in the runtime agent output/state patch. | QuantStrategist's readable strategy result and prior trade-state context. |
279
- | `quant/no_trade_watch_{date}.md` | Markdown | Explicit no-trade or watch state when such a prior artifact exists. | Supported alternative baseline trade-state input; the ACL does not introduce a new writer for this file. |
280
- | `quant/strategist_performance.json` | JSON | Trusted member weights, vote history, weight-change history, and latest weighted aggregation. | Session-owned committee record maintained through the existing performance tracker. |
281
- | `quant/post_{date}.md` | Markdown | Finley's readable final market output, baseline/delta interpretation, and paper-trading disclaimer. | Publisher's user-facing result. |
282
- | `quant/portfolio_log_{date}.md` | Markdown | Timestamped open-position checks, available current prices, threshold breaches, missing-price notes, and alerts. | PortfolioMonitor's daily monitoring record. |
283
- | `quant/viz/candlestick_{ticker}_{date}.png` | PNG chart | Price candles, volume, and a moving-average overlay when usable source data exists. | Market-price visualization produced by VizAgent. |
284
- | `quant/viz/rsi_macd_{ticker}_{date}.png` | PNG chart | RSI and MACD panels based on available indicator data. | Technical-indicator visualization produced by VizAgent. |
285
- | `quant/viz/backtest_{date}.png` | PNG chart | Signal win-rate chart from parseable backtest metrics. | Backtest visualization produced by VizAgent. |
286
- | `quant/viz/risk_heatmap_{date}.png` | PNG chart | Risk verdicts rendered as a labelled risk-rating chart. | Risk visualization produced by VizAgent. |
287
- | `quant/viz/portfolio_pnl_{date}.png` | PNG chart | Currently position-size bars and entry-price markers from portfolio state. | Portfolio visualization produced by VizAgent; despite its filename, the current code does not calculate realized/unrealized P&L here. |
288
- | `quant/yolo_baselines/{baseline}/quant/...` | Same as saved file | Saved copies of the exact quant filenames enumerated in the Baseline File Permissions table, retaining each original file's content and relative path. | Read-only prior-run context. The ellipsis here describes that directory layout and is not an ACL wildcard. |
289
- | `research_state.json` | JSON | Runtime session state, including quant watchlist, portfolio, proposals, prior backtest state, and YOLO metadata. | Runtime-owned state source for selected typed agent inputs; not a blanket file permission. |
290
- | `thread.jsonl` | JSON Lines | Recorded conversation and agent messages for the session. | Runtime-owned conversation history; agent context must be filtered according to its allowed inputs. |
291
-
292
- Missing sections do not imply zero values or neutral evidence. Availability and
293
- data-quality metadata must be respected when consuming these files.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
294
 
295
  ### Typed Artifact Schemas
296
 
@@ -303,8 +418,295 @@ data-quality metadata must be respected when consuming these files.
303
  its ACL.
304
  - Human-readable markdown may remain as a rendered artifact, but markdown
305
  conventions alone are not the V8.0 machine contract.
306
- - Artifact storage details will be finalized after the dependency, ACL, and
307
- schema contracts are agreed.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
308
 
309
  ### Runtime And Product Boundaries
310
 
@@ -328,15 +730,100 @@ data-quality metadata must be respected when consuming these files.
328
 
329
  ### UI Visibility
330
 
331
- The V8.0 UI retains the current YOLO run experience and adds:
 
 
 
332
 
333
- 1. Current agent activation and completion state from the Routing Table.
334
- 2. The Routing Table using exact registered agent names.
335
- 3. ACL information showing which session artifacts each agent may read and
336
- produce.
 
 
 
337
 
338
- The UI must not present services, schemas, ACL entries, or dependency-engine
339
- internals as additional agents.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
340
 
341
  ---
342
 
@@ -432,13 +919,16 @@ applicable ticker scope.
432
 
433
  ---
434
 
435
- ## Remaining Contract Decisions
436
 
437
- The Routing Table and draft ACL rows now cover all registered quant agents.
438
- The remaining decisions are typed input/output schemas, shared-file ownership
439
- and ticker filtering, final artifact storage, and UI presentation. The tables
440
- are design specifications; runtime migration and enforcement are not yet
441
- implemented.
 
 
 
442
 
443
  ---
444
 
@@ -453,9 +943,10 @@ implemented.
453
  - [x] Define the complete Routing Table at the agent-dependency and scope level.
454
  - [x] Draft filename-based ACL rows and file-content references for all quant agents.
455
  - [x] Record baseline snapshot read permissions for session-delta context.
456
- - [ ] Finalize shared-file ownership and scope-filtered access with typed schemas.
457
- - [ ] Finalize the ACL contract for each quant agent after those decisions.
458
- - [ ] Define typed input and output artifact schemas for each quant agent.
459
- - [ ] Finalize artifact storage from the approved contracts.
460
- - [ ] Define UI presentation for dependency and ACL state.
461
- - [ ] Write the V8.0 implementation and verification plan.
 
 
153
  scope. Unlisted artifacts are inaccessible through the runtime file interface.
154
  All entries are filenames or filename templates relative to the session folder,
155
  including subdirectories. They are not logical artifact identifiers.
156
+ `{ticker}` resolves only to tickers in the agent's effective scope. Run IDs
157
+ resolve to the current run or the explicitly selected read-only source run. Listing returns only filenames allowed by `list`;
 
158
  reading their contents separately requires `read` permission.
159
 
160
  #### ACL Table
161
 
162
+ This is the V8.0 filename contract for all 19 registered quant agents.
163
+ It supersedes the earlier date-based draft. It is a PRD specification;
164
+ runtime enforcement has not been implemented.
165
+
166
+ Every entry below is a complete session-relative filename template.
167
+ `{run_id}` is the runtime-selected current run. For a separate visualization
168
+ request, read entries bind to its selected source run and create/edit entries
169
+ bind to the visualization run; these bindings are fixed before activation.
170
+ A required dependency must be present; optional reads confer no scheduling
171
+ dependency. Missing optional files remain explicit gaps.
172
 
173
  | Agent | `read` | `create` | `edit` | `list` |
174
  |---|---|---|---|---|
175
+ | `DataFetcher` | `[quant/runs/{run_id}/data_fetch.json, quant/runs/{run_id}/raw/{ticker}.json]` | `[quant/runs/{run_id}/data_fetch.json, quant/runs/{run_id}/data_fetch.md, quant/runs/{run_id}/raw/{ticker}.json, quant/runs/{run_id}/raw/{ticker}_summary.md]` | `[quant/runs/{run_id}/data_fetch.json, quant/runs/{run_id}/data_fetch.md, quant/runs/{run_id}/raw/{ticker}.json, quant/runs/{run_id}/raw/{ticker}_summary.md]` | `[quant/runs/{run_id}/raw/{ticker}.json]` |
176
+ | `OptionsFlowWatcher` | `[]` | `[quant/runs/{run_id}/options_flow.json, quant/runs/{run_id}/options_flow.md]` | `[quant/runs/{run_id}/options_flow.json, quant/runs/{run_id}/options_flow.md]` | `[]` |
177
+ | `TrendAnalyst` | `[quant/runs/{run_id}/data_fetch.json, quant/runs/{run_id}/raw/{ticker}.json]` | `[quant/runs/{run_id}/trend_analysis.json, quant/runs/{run_id}/trend_analysis.md]` | `[quant/runs/{run_id}/trend_analysis.json, quant/runs/{run_id}/trend_analysis.md]` | `[quant/runs/{run_id}/raw/{ticker}.json]` |
178
+ | `SentimentAnalyst` | `[quant/runs/{run_id}/data_fetch.json, quant/runs/{run_id}/raw/{ticker}.json, quant/runs/{run_id}/trend_analysis.json]` | `[quant/runs/{run_id}/sentiment_analysis.json, quant/runs/{run_id}/sentiment_analysis.md]` | `[quant/runs/{run_id}/sentiment_analysis.json, quant/runs/{run_id}/sentiment_analysis.md]` | `[quant/runs/{run_id}/raw/{ticker}.json]` |
179
+ | `MarketEventWatcher` | `[quant/runs/{run_id}/data_fetch.json, quant/runs/{run_id}/raw/{ticker}.json, quant/runs/{run_id}/trend_analysis.json]` | `[quant/runs/{run_id}/market_events.json, quant/runs/{run_id}/market_events.md]` | `[quant/runs/{run_id}/market_events.json, quant/runs/{run_id}/market_events.md]` | `[quant/runs/{run_id}/raw/{ticker}.json]` |
180
+ | `MacroContextWatcher` | `[quant/runs/{run_id}/market_events.json, quant/runs/{run_id}/options_flow.json]` | `[quant/runs/{run_id}/macro_context.json, quant/runs/{run_id}/macro_context.md]` | `[quant/runs/{run_id}/macro_context.json, quant/runs/{run_id}/macro_context.md]` | `[]` |
181
+ | `UnusualEventDetector` | `[quant/runs/{run_id}/market_events.json, quant/runs/{run_id}/options_flow.json, quant/runs/{run_id}/macro_context.json]` | `[quant/runs/{run_id}/unusual_events.json, quant/runs/{run_id}/unusual_events.md]` | `[quant/runs/{run_id}/unusual_events.json, quant/runs/{run_id}/unusual_events.md]` | `[]` |
182
+ | `EventRouter` | `[quant/runs/{run_id}/unusual_events.json, quant/runs/{run_id}/market_events.json, quant/runs/{run_id}/options_flow.json]` | `[quant/runs/{run_id}/event_route.json, quant/runs/{run_id}/event_route.md]` | `[quant/runs/{run_id}/event_route.json, quant/runs/{run_id}/event_route.md]` | `[]` |
183
+ | `BTCAnalyst` | `[quant/runs/{run_id}/trend_analysis.json, quant/runs/{run_id}/event_route.json, quant/runs/{run_id}/market_events.json, quant/runs/{run_id}/macro_context.json, quant/runs/{run_id}/unusual_events.json, quant/runs/{run_id}/sentiment_analysis.json]` | `[quant/runs/{run_id}/btc_analysis.json, quant/runs/{run_id}/btc_analysis.md]` | `[quant/runs/{run_id}/btc_analysis.json, quant/runs/{run_id}/btc_analysis.md]` | `[]` |
184
+ | `SPYAnalyst` | `[quant/runs/{run_id}/trend_analysis.json, quant/runs/{run_id}/event_route.json, quant/runs/{run_id}/market_events.json, quant/runs/{run_id}/options_flow.json, quant/runs/{run_id}/macro_context.json, quant/runs/{run_id}/unusual_events.json, quant/runs/{run_id}/sentiment_analysis.json]` | `[quant/runs/{run_id}/spy_analysis.json, quant/runs/{run_id}/spy_analysis.md]` | `[quant/runs/{run_id}/spy_analysis.json, quant/runs/{run_id}/spy_analysis.md]` | `[]` |
185
+ | `QQQAnalyst` | `[quant/runs/{run_id}/trend_analysis.json, quant/runs/{run_id}/event_route.json, quant/runs/{run_id}/market_events.json, quant/runs/{run_id}/options_flow.json, quant/runs/{run_id}/macro_context.json, quant/runs/{run_id}/unusual_events.json, quant/runs/{run_id}/sentiment_analysis.json]` | `[quant/runs/{run_id}/qqq_analysis.json, quant/runs/{run_id}/qqq_analysis.md]` | `[quant/runs/{run_id}/qqq_analysis.json, quant/runs/{run_id}/qqq_analysis.md]` | `[]` |
186
+ | `GLDAnalyst` | `[quant/runs/{run_id}/trend_analysis.json, quant/runs/{run_id}/event_route.json, quant/runs/{run_id}/market_events.json, quant/runs/{run_id}/options_flow.json, quant/runs/{run_id}/macro_context.json, quant/runs/{run_id}/unusual_events.json, quant/runs/{run_id}/sentiment_analysis.json]` | `[quant/runs/{run_id}/gld_analysis.json, quant/runs/{run_id}/gld_analysis.md]` | `[quant/runs/{run_id}/gld_analysis.json, quant/runs/{run_id}/gld_analysis.md]` | `[]` |
187
+ | `QuantResearcher` | `[quant/runs/{run_id}/trend_analysis.json, quant/runs/{run_id}/sentiment_analysis.json, quant/runs/{run_id}/asset_analysis.json, quant/runs/{run_id}/macro_context.json, quant/runs/{run_id}/unusual_events.json]` | `[quant/runs/{run_id}/signals.json, quant/runs/{run_id}/signals.md]` | `[quant/runs/{run_id}/signals.json, quant/runs/{run_id}/signals.md]` | `[]` |
188
+ | `Backtester` | `[quant/runs/{run_id}/signals.json, quant/runs/{run_id}/raw/{ticker}.json]` | `[quant/runs/{run_id}/backtest_results.json, quant/runs/{run_id}/backtest_results.md]` | `[quant/runs/{run_id}/backtest_results.json, quant/runs/{run_id}/backtest_results.md]` | `[quant/runs/{run_id}/raw/{ticker}.json]` |
189
+ | `RiskAnalyst` | `[quant/runs/{run_id}/backtest_results.json, quant/runs/{run_id}/trend_analysis.json, quant/runs/{run_id}/asset_analysis.json, quant/runs/{run_id}/macro_context.json]` | `[quant/runs/{run_id}/risk_assessment.json, quant/runs/{run_id}/risk_assessment.md]` | `[quant/runs/{run_id}/risk_assessment.json, quant/runs/{run_id}/risk_assessment.md]` | `[]` |
190
+ | `QuantStrategist` | `[quant/runs/{run_id}/risk_assessment.json, quant/runs/{run_id}/backtest_results.json, quant/runs/{run_id}/sentiment_analysis.json, quant/runs/{run_id}/signals.json, quant/runs/{run_id}/asset_analysis.json, quant/runs/{run_id}/macro_context.json, quant/strategist_performance.json]` | `[quant/runs/{run_id}/trade_proposals.json, quant/runs/{run_id}/trade_proposals.md, quant/strategist_performance.json]` | `[quant/runs/{run_id}/trade_proposals.json, quant/runs/{run_id}/trade_proposals.md, quant/strategist_performance.json]` | `[]` |
191
+ | `Publisher` | `[quant/runs/{run_id}/trade_proposals.json, quant/runs/{run_id}/trend_analysis.json, quant/runs/{run_id}/sentiment_analysis.json, quant/runs/{run_id}/risk_assessment.json, quant/runs/{run_id}/asset_analysis.json, quant/runs/{run_id}/macro_context.json]` | `[quant/runs/{run_id}/post.json, quant/runs/{run_id}/post.md]` | `[quant/runs/{run_id}/post.json, quant/runs/{run_id}/post.md]` | `[]` |
192
+ | `VizAgent` | `[quant/runs/{run_id}/raw/{ticker}.json, quant/runs/{run_id}/backtest_results.json, quant/runs/{run_id}/risk_assessment.json]` | `[quant/runs/{run_id}/visualizations.json, quant/runs/{run_id}/visualizations.md, quant/runs/{run_id}/viz/candlestick_{ticker}.png, quant/runs/{run_id}/viz/rsi_macd_{ticker}.png, quant/runs/{run_id}/viz/backtest.png, quant/runs/{run_id}/viz/risk_heatmap.png, quant/runs/{run_id}/viz/portfolio_pnl.png]` | `[quant/runs/{run_id}/visualizations.json, quant/runs/{run_id}/visualizations.md, quant/runs/{run_id}/viz/candlestick_{ticker}.png, quant/runs/{run_id}/viz/rsi_macd_{ticker}.png, quant/runs/{run_id}/viz/backtest.png, quant/runs/{run_id}/viz/risk_heatmap.png, quant/runs/{run_id}/viz/portfolio_pnl.png]` | `[quant/runs/{run_id}/raw/{ticker}.json]` |
193
+ | `PortfolioMonitor` | `[]` | `[quant/runs/{run_id}/portfolio_log.json, quant/runs/{run_id}/portfolio_log.md]` | `[quant/runs/{run_id}/portfolio_log.json, quant/runs/{run_id}/portfolio_log.md]` | `[]` |
194
+
195
+ `edit` is limited to the owning agent's unpublished outputs during its current
196
+ activation. After valid outputs are published and dependency completion is
197
+ recorded, those files are read-only. Later runs use different paths.
198
+ The session-level performance file is the explicit exception described below.
199
 
200
  #### Baseline File Permissions
201
 
202
+ The following lists extend current-run permissions for session-delta context.
203
+ `{baseline_run_id}` is the prior completed YOLO run selected by the runtime
204
+ before activation. It cannot equal the current run ID or name a different
205
+ session. Each entry grants read-only access; no baseline file is editable.
206
+ These lists include prior outputs needed to perform the already specified
207
+ per-agent delta comparison.
208
 
209
  | Agent | Additional `read` | Additional `list` |
210
  |---|---|---|
211
+ | `DataFetcher` | `[quant/runs/{baseline_run_id}/raw/{ticker}.json]` | `[quant/runs/{baseline_run_id}/raw/{ticker}.json]` |
212
+ | `OptionsFlowWatcher` | `[quant/runs/{baseline_run_id}/options_flow.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
213
+ | `TrendAnalyst` | `[quant/runs/{baseline_run_id}/trend_analysis.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
214
+ | `SentimentAnalyst` | `[quant/runs/{baseline_run_id}/sentiment_analysis.json, quant/runs/{baseline_run_id}/trend_analysis.json, quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
215
+ | `MarketEventWatcher` | `[quant/runs/{baseline_run_id}/market_events.json, quant/runs/{baseline_run_id}/trend_analysis.json, quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
216
+ | `MacroContextWatcher` | `[quant/runs/{baseline_run_id}/macro_context.json, quant/runs/{baseline_run_id}/trend_analysis.json, quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
217
+ | `UnusualEventDetector` | `[quant/runs/{baseline_run_id}/unusual_events.json, quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
218
+ | `EventRouter` | `[quant/runs/{baseline_run_id}/event_route.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
219
+ | `BTCAnalyst` | `[quant/runs/{baseline_run_id}/btc_analysis.json, quant/runs/{baseline_run_id}/trend_analysis.json, quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
220
+ | `SPYAnalyst` | `[quant/runs/{baseline_run_id}/spy_analysis.json, quant/runs/{baseline_run_id}/trend_analysis.json, quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
221
+ | `QQQAnalyst` | `[quant/runs/{baseline_run_id}/qqq_analysis.json, quant/runs/{baseline_run_id}/trend_analysis.json, quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
222
+ | `GLDAnalyst` | `[quant/runs/{baseline_run_id}/gld_analysis.json, quant/runs/{baseline_run_id}/trend_analysis.json, quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
223
+ | `QuantResearcher` | `[quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/backtest_results.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
224
+ | `Backtester` | `[quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/backtest_results.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json]` | `[]` |
225
+ | `RiskAnalyst` | `[quant/runs/{baseline_run_id}/backtest_results.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
226
+ | `QuantStrategist` | `[quant/runs/{baseline_run_id}/signals.json, quant/runs/{baseline_run_id}/backtest_results.json, quant/runs/{baseline_run_id}/risk_assessment.json, quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json]` | `[]` |
227
+ | `Publisher` | `[quant/runs/{baseline_run_id}/trade_proposals.json, quant/runs/{baseline_run_id}/post.json, quant/runs/{baseline_run_id}/risk_assessment.json]` | `[]` |
228
  | `VizAgent` | `[]` | `[]` |
229
  | `PortfolioMonitor` | `[]` | `[]` |
230
 
231
  #### Permission Boundaries
232
 
233
+ - The runtime resolves filenames and effective ticker scope before supplying
234
+ an agent's input. Providers, prompt builders, renderers, and RAG use the same
235
+ permissions when acting on behalf of that agent.
236
+ - `read` permits only fields declared by the input schema. `list` exposes
237
+ filenames only. A returned filename grants no implicit content access.
238
+ - Optional inputs are captured when an agent activates. An optional producer
239
+ completing later does not change that activation's input. Prior evidence
240
+ is supplied as baseline context with its original run and timestamps.
241
+ - `DataFetcher` does not read trend output to choose the next agent.
242
+ - The four asset analysts write only their individual artifacts. The runtime
243
+ assembles `AssetAnalysisCollection` from their published outputs and writes
244
+ the aggregate. Consumers receive only records overlapping their own scope.
245
+ - The trusted performance tracker, acting for `QuantStrategist`, is the only
246
+ writer of `quant/strategist_performance.json`. LLM votes cannot edit weights.
247
+ Each run's strategy output retains the weights actually used and the
248
+ resulting updates; replay does not substitute the latest session weights.
249
+ - Session state, conversation logs, run records, RAG indexes, input snapshots,
250
+ traces, and evidence ledgers are runtime-owned. Agent inputs may receive
251
+ selected typed state fields, never unrestricted state or thread contents.
252
+ Provider credentials remain in the configured service layer and are not
253
+ artifact contents.
254
+ - Snapshotting an input or building an aggregate does not grant broader read
255
+ access. The original producer, artifact identity, record references, and
256
+ ticker restrictions remain attached to the data.
257
+ - The tables grant no access to arbitrary older runs. Explicit baseline
258
+ references and a visualization's selected source run are the exceptions.
259
+ Session RAG retrieval is filtered to those same permitted files.
260
+ - JSON filenames in both tables must match the declared producer schema.
261
+ Markdown renderings remain available to people through replay and downloads;
262
+ they are not automatically added to an agent's read permissions.
263
 
264
  #### File Content Reference
265
 
266
+ All paths are relative to the existing session folder. Each JSON/Markdown
267
+ pair below lists two explicit files: JSON contains the typed output, and
268
+ Markdown renders the same agent-owned content for the product and download.
 
269
 
270
+ | Filenames | Owner | Content |
271
+ |---|---|---|
272
+ | `quant/runs/{run_id}/data_fetch.json`, `quant/runs/{run_id}/data_fetch.md` | `DataFetcher` | DataFetcherOutput run manifest with availability, one ticker result per requested ticker, issues, and references to per-ticker data. |
273
+ | `quant/runs/{run_id}/options_flow.json`, `quant/runs/{run_id}/options_flow.md` | `OptionsFlowWatcher` | OptionsFlowWatcherOutput including sampled contracts, provider capabilities, context, flow candidates, supported unusual-flow claims, and sampling limits. |
274
+ | `quant/runs/{run_id}/trend_analysis.json`, `quant/runs/{run_id}/trend_analysis.md` | `TrendAnalyst` | TrendAnalystOutput with technical findings, evidence, and per-ticker delta. |
275
+ | `quant/runs/{run_id}/sentiment_analysis.json`, `quant/runs/{run_id}/sentiment_analysis.md` | `SentimentAnalyst` | SentimentAnalystOutput with source coverage, themes, earnings where applicable, sentiment, and uncertainty. |
276
+ | `quant/runs/{run_id}/market_events.json`, `quant/runs/{run_id}/market_events.md` | `MarketEventWatcher` | MarketEventWatcherOutput with observed data changes and already available news/catalysts; no invented external feed. |
277
+ | `quant/runs/{run_id}/macro_context.json`, `quant/runs/{run_id}/macro_context.md` | `MacroContextWatcher` | MacroContextWatcherOutput with the main line, weighted drivers, contradictions, and affected tickers. |
278
+ | `quant/runs/{run_id}/unusual_events.json`, `quant/runs/{run_id}/unusual_events.md` | `UnusualEventDetector` | UnusualEventDetectorOutput with meaningful events, suppression reasons, and monitoring conditions. |
279
+ | `quant/runs/{run_id}/event_route.json`, `quant/runs/{run_id}/event_route.md` | `EventRouter` | EventRouterOutput assigning event evidence to in-scope tickers without changing activation. |
280
+ | `quant/runs/{run_id}/btc_analysis.json`, `quant/runs/{run_id}/btc_analysis.md` | `BTCAnalyst` | BTCAnalystOutput for BTC only. |
281
+ | `quant/runs/{run_id}/spy_analysis.json`, `quant/runs/{run_id}/spy_analysis.md` | `SPYAnalyst` | SPYAnalystOutput for SPY only. |
282
+ | `quant/runs/{run_id}/qqq_analysis.json`, `quant/runs/{run_id}/qqq_analysis.md` | `QQQAnalyst` | QQQAnalystOutput for QQQ only. |
283
+ | `quant/runs/{run_id}/gld_analysis.json`, `quant/runs/{run_id}/gld_analysis.md` | `GLDAnalyst` | GLDAnalystOutput for GLD only. |
284
+ | `quant/runs/{run_id}/signals.json`, `quant/runs/{run_id}/signals.md` | `QuantResearcher` | QuantResearcherOutput with signal hypotheses, priorities, evidence, and lifecycle changes. |
285
+ | `quant/runs/{run_id}/backtest_results.json`, `quant/runs/{run_id}/backtest_results.md` | `Backtester` | BacktesterOutput with method, signal results, executed metrics when available, and limitations. |
286
+ | `quant/runs/{run_id}/risk_assessment.json`, `quant/runs/{run_id}/risk_assessment.md` | `RiskAnalyst` | RiskAnalystOutput with signal verdicts, portfolio risk, scenarios, and mitigations. |
287
+ | `quant/runs/{run_id}/trade_proposals.json`, `quant/runs/{run_id}/trade_proposals.md` | `QuantStrategist` | QuantStrategistOutput with proposals or no-trade/watch conclusions, votes, trusted weights, and prior proposal updates. |
288
+ | `quant/runs/{run_id}/post.json`, `quant/runs/{run_id}/post.md` | `Publisher` | PublisherOutput with Finley's readable result and proposal or no-proposal explanation. |
289
+ | `quant/runs/{run_id}/visualizations.json`, `quant/runs/{run_id}/visualizations.md` | `VizAgent` | VizAgentOutput manifest with chart references, sources, caption, and errors. |
290
+ | `quant/runs/{run_id}/portfolio_log.json`, `quant/runs/{run_id}/portfolio_log.md` | `PortfolioMonitor` | PortfolioMonitorOutput with position checks, quote provenance, thresholds, and alerts for one monitoring run. |
291
+ | `quant/runs/{run_id}/raw/{ticker}.json`, `quant/runs/{run_id}/raw/{ticker}_summary.md` | `DataFetcher` | MarketDataArtifact and its readable summary: normalized OHLCV, computed indicators, news, earnings, timestamps, and component quality. |
292
+ | `quant/runs/{run_id}/asset_analysis.json`, `quant/runs/{run_id}/asset_analysis.md` | Runtime aggregate | AssetAnalysisCollection preserving each analyst's producer and source reference. No additional analysis is generated. |
293
+ | `quant/runs/{run_id}/viz/candlestick_{ticker}.png` | `VizAgent` | Price candles, volume, and a moving-average overlay from validated data. |
294
+ | `quant/runs/{run_id}/viz/rsi_macd_{ticker}.png` | `VizAgent` | RSI and MACD plots from typed indicator series. |
295
+ | `quant/runs/{run_id}/viz/backtest.png` | `VizAgent` | Backtest metrics, with the source method clearly identified. |
296
+ | `quant/runs/{run_id}/viz/risk_heatmap.png` | `VizAgent` | Typed risk verdicts rendered as a risk-rating chart. |
297
+ | `quant/runs/{run_id}/viz/portfolio_pnl.png` | `VizAgent` | Existing position-size and entry-price visualization; its filename does not establish calculated P&L. |
298
+ | `quant/runs/{run_id}/inputs/{agent}.json` | Runtime | Exact ACL-filtered typed input used for an activation, including selected state, dependency identities, and baseline references; excludes secrets. `{agent}` is an exact registered name. |
299
+ | `yolo_runs/{run_id}.json` | Runtime | Existing replay record, extended with fixed routing plan, baseline run ID, artifact inventory, actual statuses, and resolved ACL/input references. Support runs carry their execution context and are excluded from the YOLO baseline selection. |
300
+ | `quant/evidence_ledger_{run_id}.json`, `quant/evidence_ledger_{run_id}.md` | Runtime | Existing evidence ledger filenames; records evidence actually used, excluded, or missing for that run. |
301
+ | `quant/strategist_performance.json` | Trusted tracker for `QuantStrategist` | Session-scoped current weights, vote history, and explainable changes. |
302
+ | `session.json`, `research_state.json`, `thread.jsonl`, `trace.jsonl` | Runtime | Existing session metadata, state, conversation, and append-only trace. Events and run references identify the relevant execution. |
303
+
304
+ Historical runs have the same layout with their own concrete run IDs. They
305
+ are read-only; this does not require a duplicate directory of baseline copies.
306
+
307
+ ### Artifact Storage
308
+
309
+ #### Layout And Ownership
310
+
311
+ V8.0 keeps the existing session folder and introduces one directory per run:
312
+
313
+ ```text
314
+ <session>/
315
+ session.json
316
+ research_state.json
317
+ thread.jsonl
318
+ trace.jsonl
319
+ yolo_runs/
320
+ <run_id>.json
321
+ quant/
322
+ strategist_performance.json
323
+ evidence_ledger_<run_id>.json
324
+ evidence_ledger_<run_id>.md
325
+ runs/
326
+ <run_id>/
327
+ inputs/
328
+ DataFetcher.json
329
+ TrendAnalyst.json
330
+ ... other active registered agents ...
331
+ data_fetch.json
332
+ data_fetch.md
333
+ raw/
334
+ SPY.json
335
+ SPY_summary.md
336
+ trend_analysis.json
337
+ trend_analysis.md
338
+ ... other published agent outputs from File Content Reference ...
339
+ ```
340
+
341
+ The ellipses explain the layout; they are not ACL wildcard grants.
342
+ The same storage convention applies to quant analysis for every supported
343
+ market. Support executions have their own run IDs and execution contexts.
344
+
345
+ #### Publication And Versioning
346
+
347
+ 1. A run ID is unique within its session, including multiple starts on the
348
+ same day. Dates belong in artifact content; a date alone is not an output
349
+ identity.
350
+ 2. Inputs are resolved and recorded before activation. JSON is parsed and
351
+ validated before publication. Dependencies see only complete published
352
+ JSON files, never partial writes.
353
+ 3. Before publication, an agent may edit only its own listed outputs. After
354
+ publication, the output identity and contents remain fixed. A rerun creates
355
+ a new run ID; it never replaces a prior completed result.
356
+ 4. The runtime records schema version, producer, run ID, and exact path in
357
+ each artifact reference. Each JSON schema defines its own version;
358
+ Markdown and PNG references identify their format and source JSON artifact
359
+ instead of pretending the rendering implements a typed JSON schema.
360
+ 5. The typed JSON is authoritative. Markdown is derived from its declared
361
+ narrative and structured fields. A rendering failure is recorded separately
362
+ from analysis availability and cannot erase an already valid JSON result.
363
+ 6. Missing providers or inputs produce explicit typed gaps when possible.
364
+ An activation that cannot produce a valid output is recorded as failed;
365
+ no success artifact or no-trade decision is fabricated.
366
+ 7. The runtime aggregate is published only after the active contributing
367
+ analysts reach their recorded terminal state. It preserves unavailable
368
+ entries and producer failures; absent results are never silently counted
369
+ as completed analyses.
370
+ 8. Session-state updates and performance changes use the existing runtime
371
+ coordination. The per-run input and output snapshots retain the state
372
+ actually consumed or produced so later updates cannot rewrite replay.
373
+
374
+ #### Baseline And Replay
375
+
376
+ - The first run without a usable completed baseline performs baseline YOLO.
377
+ Subsequent runs select the latest completed eligible YOLO run in this
378
+ session. The selected baseline ID is fixed before activation.
379
+ - Each agent uses only the prior filenames listed in its baseline ACL.
380
+ A newly added ticker without prior coverage is explicitly not compared.
381
+ A failed or incomplete run remains available for review but does not replace
382
+ the last eligible baseline.
383
+ - Prior JSON is consumed only when its schema is supported. Existing
384
+ date-named Markdown and `quant/yolo_baselines/` snapshots remain available
385
+ in historical downloads and replay. They are not silently promoted to
386
+ typed inputs. A session with only legacy artifacts starts a new typed
387
+ baseline while retaining its existing session and paper-position state.
388
+ - The replay record and its artifact inventory identify one run exactly.
389
+ Replay must not search for the latest date-named file or substitute current
390
+ strategy weights, current state, or another run's Finley output.
391
+ - Saved files preserve the recorded result. This remains display replay;
392
+ deterministic LLM re-execution and historical simulation are separate
393
+ product capabilities.
394
+
395
+ #### Downloads And Retention
396
+
397
+ The existing recursive session export includes all run directories, input
398
+ snapshots, typed outputs, renderings, charts, baseline sources, replay records,
399
+ traces, and available evidence ledgers. The selected run record identifies
400
+ which artifacts belong to the viewed run when the package contains multiple
401
+ runs. Download remains available for completed, blocked, and failed runs.
402
+
403
+ The runtime does not delete prior runs on a later YOLO invocation or ordinary
404
+ process restart. Retention lasts as long as the underlying session storage
405
+ exists. This specification does not claim durability after replacement of
406
+ ephemeral deployment storage or introduce an external storage service.
407
+ The evidence ledger remains included in the package; it is not made a primary
408
+ UI panel by this storage change.
409
 
410
  ### Typed Artifact Schemas
411
 
 
418
  its ACL.
419
  - Human-readable markdown may remain as a rendered artifact, but markdown
420
  conventions alone are not the V8.0 machine contract.
421
+ - Artifact paths and publication rules follow the Artifact Storage section.
422
+
423
+ #### `DataFetcher` Typed Contract
424
+
425
+ `DataFetcher` is a root agent. It fetches, normalizes, validates, and organizes
426
+ market data for its effective ticker scope. It does not interpret market
427
+ direction and does not select the next workflow agent.
428
+
429
+ ##### Input: `DataFetcherInput`
430
+
431
+ | Field | Type | Required | Meaning |
432
+ |---|---|---|---|
433
+ | `run_id` | `string` | Yes | Identifier of the current YOLO run. |
434
+ | `session_id` | `string` | Yes | Identifier of the owning session context. |
435
+ | `run_mode` | `BASELINE \| DELTA` | Yes | Whether this is the first session run or a later session-delta run. |
436
+ | `as_of` | `datetime` | Yes | Data-fetch cutoff supplied by the runtime. |
437
+ | `ticker_scope` | `list[string]` | Yes | Non-empty runtime-approved effective ticker scope. |
438
+ | `baseline_refs` | `map[string, ArtifactRef]` | Delta only | Prior market-data artifact reference for each ticker when available. An absent reference is an explicit missing baseline, not an instruction to search unrestricted session files. |
439
+
440
+ `DataFetcher` has no required upstream agent artifact. Session and run fields
441
+ are runtime inputs rather than session-folder read permissions.
442
+
443
+ ##### Output: `DataFetcherOutput`
444
+
445
+ The agent produces one run manifest with one result for every requested ticker.
446
+
447
+ | Field | Type | Required | Meaning |
448
+ |---|---|---|---|
449
+ | `schema_version` | `string` | Yes | Version of this output contract. |
450
+ | `run_id` | `string` | Yes | Run identifier copied from the validated input. |
451
+ | `session_id` | `string` | Yes | Session identifier copied from the validated input. |
452
+ | `producer` | literal `DataFetcher` | Yes | Exact registered producer name. |
453
+ | `completed_at` | `datetime` | Yes | Time at which the fetch manifest was completed. |
454
+ | `overall_status` | `COMPLETE \| PARTIAL \| UNAVAILABLE` | Yes | Aggregate availability across the requested ticker scope. |
455
+ | `ticker_results` | `list[TickerFetchResult]` | Yes | Exactly one result for every ticker in `ticker_scope`. |
456
+
457
+ `TickerFetchResult` contains:
458
+
459
+ | Field | Type | Required | Meaning |
460
+ |---|---|---|---|
461
+ | `ticker` | `string` | Yes | Ticker from the effective scope. The value is never decorated with status markers such as `*`. |
462
+ | `status` | `COMPLETE \| PARTIAL \| UNAVAILABLE` | Yes | Availability of the ticker's requested market data. |
463
+ | `market_data_ref` | `ArtifactRef` | When data exists | Reference to the typed per-ticker `MarketDataArtifact`. |
464
+ | `summary_ref` | `ArtifactRef` | When rendered | Reference to the human-readable markdown rendering. |
465
+ | `available_components` | `list[MarketDataComponent]` | Yes | Components that contain usable records. |
466
+ | `unavailable_components` | `list[MarketDataComponent]` | Yes | Requested components with no usable records. |
467
+ | `errors` | `list[DataIssue]` | Yes | Provider, normalization, and quality problems; empty on clean completion. |
468
+
469
+ `MarketDataComponent` is one of `OHLCV`, `INDICATORS`, `NEWS`, or `EARNINGS`.
470
+ An ETF without an applicable earnings component records earnings as not
471
+ applicable rather than treating it as a provider failure.
472
+
473
+ ##### Per-Ticker Artifact: `MarketDataArtifact`
474
+
475
+ | Field | Type | Required | Meaning |
476
+ |---|---|---|---|
477
+ | `schema_version` | `string` | Yes | Version of the market-data artifact contract. |
478
+ | `run_id` | `string` | Yes | Producing run. |
479
+ | `producer` | literal `DataFetcher` | Yes | Exact registered producer name. |
480
+ | `ticker` | `string` | Yes | Single ticker represented by this artifact. |
481
+ | `retrieved_at` | `datetime` | Yes | Time at which Polyhedra obtained the data. |
482
+ | `market_date` | `date` | When available | Latest valid market date represented by price data. |
483
+ | `status` | `COMPLETE \| PARTIAL \| UNAVAILABLE` | Yes | Overall per-ticker data availability. |
484
+ | `ohlcv` | `list[OHLCVBar]` | Yes | Validated daily price and volume records, ordered by date. |
485
+ | `indicators` | `TechnicalIndicatorSeries` | Yes | SMA-20, EMA-20, RSI-14, and MACD series computed from valid OHLCV records. |
486
+ | `news` | `list[NewsRecord]` | Yes | Available company or market news records. |
487
+ | `earnings` | `list[EarningsRecord]` | Yes | Available earnings records; empty when unavailable or not applicable. |
488
+ | `provenance` | `list[ComponentProvenance]` | Yes | Provider, retrieval time, source observation time, freshness, and availability for each component. |
489
+ | `quality_issues` | `list[DataIssue]` | Yes | Excluded rows, missing fields, stale components, rate limits, and provider errors. |
490
+ | `baseline_ref` | `ArtifactRef` | Delta only | Runtime-approved prior market-data artifact when available. |
491
+
492
+ The nested record types preserve numeric values and timestamps structurally:
493
+
494
+ | Type | Required content |
495
+ |---|---|
496
+ | `ArtifactRef` | Session-relative filename, schema version, producer, and artifact identifier. |
497
+ | `OHLCVBar` | Market date, open, high, low, close, optional adjusted close, and volume. |
498
+ | `TechnicalIndicatorSeries` | Dated SMA-20, EMA-20, RSI-14, and MACD values, including MACD signal and histogram. |
499
+ | `NewsRecord` | Published time, headline, source, URL when available, and provider sentiment fields when available. |
500
+ | `EarningsRecord` | Fiscal period, actual EPS, estimated EPS, surprise, and surprise percentage when available. |
501
+ | `ComponentProvenance` | Component, provider, retrieval time, source observation time when available, `FRESH \| STALE \| UNKNOWN` freshness, and `AVAILABLE \| UNAVAILABLE \| NOT_APPLICABLE` availability. |
502
+ | `DataIssue` | Component, stable issue code, message, and affected record or date references when available. |
503
+
504
+ `COMPLETE`, `PARTIAL`, and `UNAVAILABLE` describe data availability, not agent
505
+ execution. A schema-valid `UNAVAILABLE` result is an explicit data-gap artifact
506
+ that downstream agents consume. An agent execution failure means no valid
507
+ `DataFetcherOutput` was produced and is tracked separately by the runtime.
508
+
509
+ The existing `next_role` field is removed from the V8.0 contract because the
510
+ Routing Table owns activation. The per-ticker artifact is stored at
511
+ `quant/runs/{run_id}/raw/{ticker}.json`; its downloadable rendering is
512
+ `quant/runs/{run_id}/raw/{ticker}_summary.md`. The manifest is
513
+ `quant/runs/{run_id}/data_fetch.json`.
514
+
515
+ #### Common Typed Envelope
516
+
517
+ The remaining quant agents use a common runtime envelope so routing, scope,
518
+ provenance, and data gaps are represented consistently without becoming part
519
+ of every agent-specific reasoning payload.
520
+
521
+ `AgentInput[Dependencies, Context]` contains:
522
+
523
+ | Field | Type | Required | Meaning |
524
+ |---|---|---|---|
525
+ | `run_id` | `string` | Yes | Current run identifier. |
526
+ | `session_id` | `string` | Yes | Owning session identifier. |
527
+ | `run_mode` | `BASELINE \| DELTA` | Yes | Current session execution mode. |
528
+ | `as_of` | `datetime` | Yes | Runtime cutoff for available evidence. |
529
+ | `ticker_scope` | `list[string]` | Yes | Agent's frozen effective ticker scope. |
530
+ | `dependencies` | agent-specific typed object | Yes | Schema-valid outputs from required Routing Table dependencies. |
531
+ | `optional_context` | agent-specific typed object | Yes | ACL-approved optional artifacts; absent fields remain absent rather than being replaced with invented values. |
532
+ | `baseline_refs` | `list[ArtifactRef]` | Delta only | Runtime-selected prior artifacts permitted for this agent. |
533
+
534
+ For each agent, the Baseline File Permissions table enumerates the complete
535
+ set of permitted prior artifact types, including its own earlier output for
536
+ delta comparison. References resolve to the corresponding typed schemas;
537
+ optional-context summaries below do not expand or replace that filename list.
538
+
539
+ `AgentArtifact[Payload]` contains:
540
+
541
+ | Field | Type | Required | Meaning |
542
+ |---|---|---|---|
543
+ | `schema_version` | `string` | Yes | Version of the concrete agent schema. |
544
+ | `artifact_id` | `string` | Yes | Stable identity of this artifact within the session. |
545
+ | `run_id` | `string` | Yes | Producing run. |
546
+ | `session_id` | `string` | Yes | Owning session. |
547
+ | `producer` | registered agent-name literal | Yes | Exact producer from the Routing Table. |
548
+ | `ticker_scope` | `list[string]` | Yes | Scope actually represented by the payload. |
549
+ | `created_at` | `datetime` | Yes | Artifact creation time. |
550
+ | `status` | `COMPLETE \| PARTIAL \| UNAVAILABLE` | Yes | Availability of the agent result. |
551
+ | `input_refs` | `list[ArtifactRef]` | Yes | Exact current-run artifacts used. |
552
+ | `baseline_refs` | `list[ArtifactRef]` | Yes | Exact prior artifacts used; empty in baseline mode or when unavailable. |
553
+ | `data_gaps` | `list[DataIssue]` | Yes | Missing, stale, excluded, or invalid evidence. |
554
+ | `payload` | agent-specific typed object | Yes | Agent-owned result defined below. |
555
+ | `render_ref` | `ArtifactRef` | When rendered | Human-readable markdown rendering for UI and run-package use. |
556
+
557
+ The runtime validates that `ticker_scope` is a subset of the agent's frozen
558
+ effective scope and filters every referenced multi-ticker artifact to that
559
+ scope before prompt construction. A filename permission never grants access to
560
+ out-of-scope ticker records.
561
+
562
+ Common enums used below are:
563
+
564
+ ```text
565
+ ConfidenceLevel = HIGH | MEDIUM | LOW | UNKNOWN
566
+ Direction = BULLISH | BEARISH | NEUTRAL | MIXED | UNKNOWN
567
+ DeltaState = NEW | CHANGED | UNCHANGED | RESOLVED | INVALIDATED | NOT_COMPARED
568
+ AnalysisOutcome = NO_TRADE | WATCH_FOR_CONFIRMATION | PAPER_TRADE_SUGGESTION | ROUTE_TO_HUMAN
569
+ RiskVerdict = ACCEPTABLE | ELEVATED | REJECT
570
+ ```
571
+
572
+ #### `OptionsFlowWatcher` Typed Contract
573
+
574
+ `OptionsFlowWatcherInput` uses the common input envelope with no required agent
575
+ dependency. Its agent-specific input contains the `OPTIONS` ticker scope, a
576
+ provider fetch cutoff, and optional prior `OptionsFlowWatcherOutput` references
577
+ for delta comparison.
578
+
579
+ `OptionsFlowWatcherOutput` uses `OptionsFlowPayload`:
580
+
581
+ | Field | Type | Required | Meaning |
582
+ |---|---|---|---|
583
+ | `ticker_results` | `list[OptionsTickerResult]` | Yes | Exactly one result per in-scope SPY, QQQ, or GLD ticker. |
584
+ | `sampling_policy` | `OptionsSamplingPolicy` | Yes | Expiration and per-side contract limits applied by the provider adapter. |
585
+
586
+ Each `OptionsTickerResult` contains `ticker`, availability status, provider,
587
+ retrieval time, checked expirations, normalized `OptionContract` records,
588
+ `OptionsMarketContext`, zero or more `FlowCandidate` records, zero or more
589
+ `UnusualOptionFlow` records, provider capability flags, `DeltaState`, and data
590
+ issues. `OptionContract` preserves contract symbol, expiration, strike, option
591
+ type, bid, ask, last, volume, open interest, implied volatility, provider, and
592
+ delay or entitlement notes.
593
+
594
+ `OptionsMarketContext`, `FlowCandidate`, and `UnusualOptionFlow` remain separate
595
+ types. A flow candidate records the exact volume, open-interest, IV, or ratio
596
+ rule that selected it and is non-directional by default. `UnusualOptionFlow`
597
+ requires supporting trade-side, sweep/block, opening/closing, premium, or
598
+ validated-classifier evidence. Missing capabilities produce an empty unusual
599
+ flow list, not an inferred claim.
600
+
601
+ #### Analysis Agent Contracts
602
+
603
+ The following table defines each remaining analysis agent's concrete input and
604
+ payload type. All inputs and outputs are wrapped by the common envelopes.
605
+ Required dependency fields correspond exactly to the Routing Table after
606
+ effective-scope pruning.
607
+
608
+ | Agent and schema | Required dependency outputs | Optional typed context | Output payload fields |
609
+ |---|---|---|---|
610
+ | `TrendAnalyst`: `TrendAnalystInput` -> `TrendAnalystOutput` | `DataFetcherOutput` plus referenced `MarketDataArtifact` records | Prior `TrendAnalystOutput` in delta mode | `ticker_analyses: list[TrendAnalysis]`; each record has ticker, price direction, magnitude and duration, support/resistance levels, volume assessment, SMA/EMA state, RSI state, MACD state, confidence, evidence references, `DeltaState`, and data gaps. No recommendation or next role. |
611
+ | `SentimentAnalyst`: `SentimentAnalystInput` -> `SentimentAnalystOutput` | Scope-filtered `DataFetcherOutput` and market-data news/earnings records | Current `TrendAnalystOutput`; prior sentiment, signal, and Finley artifacts in delta mode | `ticker_analyses: list[SentimentAnalysis]`; each record has ticker, source coverage, article count, scored/unscored counts, aggregate sentiment, themes with evidence references, earnings sentiment when applicable, optional trend alignment, incremental-signal-value flag, confidence, `DeltaState`, and data gaps. Thin or mostly unscored news is insufficient evidence, not neutral sentiment. |
612
+ | `MarketEventWatcher`: `MarketEventWatcherInput` -> `MarketEventWatcherOutput` | Scope-filtered `DataFetcherOutput` and `MarketDataArtifact` records | Current `TrendAnalystOutput`; approved baseline event context | `ticker_contexts: list[MarketEventContext]`; each record has ticker, observed market-data changes, relevant news/catalyst records already present in DataFetcher evidence, source references, checked time, `DeltaState`, and data gaps. `external_event_feed_status` explicitly records `NOT_CONFIGURED` unless an approved provider exists. This agent does not invent a separate live event feed. |
613
+ | `MacroContextWatcher`: `MacroContextWatcherInput` -> `MacroContextWatcherOutput` | `MarketEventWatcherOutput` and scope-overlapping `OptionsFlowWatcherOutput` | Approved baseline trend, signal, risk, trade-state, and Finley artifacts | `main_line`, `drivers: list[MacroDriver]`, affected tickers, confidence, uncertainties, contradictions, `DeltaState`, and data gaps. Each driver has a numeric relevance weight, evidence references, and affected tickers. `main_line` may be `UNCLEAR`. No trade decision. |
614
+ | `UnusualEventDetector`: `UnusualEventDetectorInput` -> `UnusualEventDetectorOutput` | `MarketEventWatcherOutput`, `MacroContextWatcherOutput`, and scope-overlapping `OptionsFlowWatcherOutput` | Approved baseline signal, risk, trade-state, and Finley artifacts | `meaningful_events: list[EventCandidate]`, `suppressed_events: list[SuppressedEvent]`, and `monitoring_conditions`. Each candidate has event ID, type, affected tickers, significance, confidence, evidence references, missing evidence, and `DeltaState`. Each suppressed event records its reason: stale, duplicate, unchanged, low significance, contradicted, or unsupported. |
615
+ | `EventRouter`: `EventRouterInput` -> `EventRouterOutput` | `UnusualEventDetectorOutput` | Current market-event and options evidence plus approved baseline risk, trade-state, and Finley artifacts | `assignments: list[EventAssignment]` and `unassigned_event_ids`. Each assignment has event ID, ticker, relevance, evidence references, and rationale. It assigns evidence only to tickers already in effective scope; it cannot activate agents, emit next roles, or expand ticker scope. |
616
+
617
+ #### Specialized Asset Analyst Contracts
618
+
619
+ `BTCAnalyst`, `SPYAnalyst`, `QQQAnalyst`, and `GLDAnalyst` share one payload
620
+ shape but retain separate concrete schemas and exact producer literals:
621
+
622
+ ```text
623
+ BTCAnalystInput -> BTCAnalystOutput
624
+ SPYAnalystInput -> SPYAnalystOutput
625
+ QQQAnalystInput -> QQQAnalystOutput
626
+ GLDAnalystInput -> GLDAnalystOutput
627
+ ```
628
+
629
+ Each required input contains the scope-filtered `TrendAnalystOutput` and
630
+ `EventRouterOutput`. Optional typed context may include `MarketEventWatcherOutput`,
631
+ scope-applicable `OptionsFlowWatcherOutput`, `MacroContextWatcherOutput`,
632
+ `UnusualEventDetectorOutput`, `SentimentAnalystOutput` when available, and the
633
+ agent's approved baseline references.
634
+
635
+ Each output payload contains one `AssetAnalysis` with:
636
+
637
+ | Field | Type | Required | Meaning |
638
+ |---|---|---|---|
639
+ | `ticker` | fixed ticker literal | Yes | Must equal the analyst's registered symbol. |
640
+ | `what_matters_now` | `string` | Yes | Concise current interpretation grounded in evidence. |
641
+ | `signals` | `list[WeightedSignal]` | Yes | Evidence-backed signals with weight, confidence, direction, and references. |
642
+ | `cross_market_evidence` | `list[CrossMarketObservation]` | Yes | Confirmations or contradictions; empty when unsupported. |
643
+ | `setup` | `SetupHypothesis` | When supported | Setup thesis, confirmation conditions, and invalidation conditions. |
644
+ | `outcome` | `AnalysisOutcome` | Yes | Exactly one PRD-approved outcome. |
645
+ | `trade_suggestion` | `PaperTradeSuggestion` | Only for `PAPER_TRADE_SUGGESTION` | Direction, entry condition and level, target, stop, confirmation, invalidation, and human-approval requirement. |
646
+ | `confidence` | `ConfidenceLevel` | Yes | Confidence in the overall outcome. |
647
+ | `delta_state` | `DeltaState` | Yes | Relationship to the approved prior analysis. |
648
+ | `evidence_refs` | `list[EvidenceRef]` | Yes | Evidence actually used. |
649
+ | `data_gaps` | `list[DataIssue]` | Yes | Missing or unusable evidence. |
650
+
651
+ `trade_suggestion` is forbidden for all other outcomes. Its ticker is derived
652
+ from `AssetAnalysis.ticker` and cannot carry a contradictory symbols list.
653
+
654
+ Each specialized analyst creates only its own typed per-ticker artifact and
655
+ markdown rendering. It does not create or append to a shared asset-analysis
656
+ file. The runtime constructs a read-only `AssetAnalysisCollection` from
657
+ schema-valid active analyst outputs for downstream agents. This removes
658
+ parallel shared-file writes and preserves producer ownership.
659
+
660
+ #### Research, Validation, And Decision Contracts
661
+
662
+ | Agent and schema | Required dependency outputs | Optional typed context | Output payload fields |
663
+ |---|---|---|---|
664
+ | `QuantResearcher`: `QuantResearcherInput` -> `QuantResearcherOutput` | Scope-applicable `TrendAnalystOutput`, `SentimentAnalystOutput`, and/or `AssetAnalysisCollection` according to the active Routing Table | `MacroContextWatcherOutput`, `UnusualEventDetectorOutput`, prior signals, backtests, risk, trade state, and Finley output | `signals: list[SignalHypothesis]`, prioritized signal IDs, synthesis, `DeltaState`, and data gaps. Each signal has stable ID, ticker, thesis, direction, entry and exit conditions, confidence, assumptions, falsification conditions, evidence references, and delta state. The list may be empty when evidence supports no signal. |
665
+ | `Backtester`: `BacktesterInput` -> `BacktesterOutput` | `QuantResearcherOutput` | Scope-filtered `MarketDataArtifact` records and prior signal/backtest/risk/trade-state artifacts | `results: list[BacktestResult]`, method, tested window, assumptions, limitations, and data gaps. Each result has signal ID, ticker, observations, occurrences, win rate, average return, cumulative return, maximum drawdown, Sharpe ratio when calculable, and `SUFFICIENT \| WEAK \| NOT_TESTABLE` evidence strength. `method` must distinguish `HISTORICAL_SIMULATION` from `LLM_ASSESSMENT`; only executed calculations may claim simulation metrics. |
666
+ | `RiskAnalyst`: `RiskAnalystInput` -> `RiskAnalystOutput` | `BacktesterOutput` | Current trend, asset-analysis collection, macro context, scope-filtered paper portfolio state, and approved baseline artifacts | `signal_assessments: list[SignalRiskAssessment]`, portfolio heat, concentration assessment, correlation assessment, maximum-loss estimate when calculable, stress scenarios, overall risk summary, and data gaps. Each signal assessment has signal ID, `RiskVerdict`, rationale, suggested paper position limit, and required mitigation. |
667
+ | `QuantStrategist`: `QuantStrategistInput` -> `QuantStrategistOutput` | `RiskAnalystOutput` | Signals, backtests, sentiment, asset analyses, macro context, prior trade state, and runtime-owned committee performance | final `outcome: AnalysisOutcome`, `proposals: list[PaperTradeProposal]`, no-trade/watch rationale, exclusions, committee votes, runtime-owned weights, weighted aggregation, proposal lifecycle updates, evidence references, and data gaps. At most three proposals are allowed; `REJECT` signals cannot become proposals. |
668
+
669
+ `PaperTradeProposal` contains proposal ID, one ticker, direction, entry
670
+ condition and level, target, stop, time horizon, confidence, source signal IDs,
671
+ risk verdict, mitigation when elevated, confirmation and invalidation
672
+ conditions, rationale, and explicit human-approval requirement. Empty proposals
673
+ with `NO_TRADE` or `WATCH_FOR_CONFIRMATION` are valid strategy outcomes.
674
+
675
+ Committee votes contain member ID, vote, confidence, thesis, cited evidence,
676
+ and proposal impact. Trusted weight and aggregation fields are attached by the
677
+ runtime performance tool; LLM output cannot set or modify them.
678
+
679
+ #### Product And Support Agent Contracts
680
+
681
+ | Agent and schema | Required dependency outputs | Optional typed context | Output payload fields |
682
+ |---|---|---|---|
683
+ | `Publisher`: `PublisherInput` -> `PublisherOutput` | `QuantStrategistOutput` | Scope-filtered trend, sentiment, risk, asset-analysis, macro, and approved baseline Finley artifacts | `headline`, `market_summary`, `what_to_watch`, displayed proposal IDs, `no_proposal_reason`, disclaimer, approximate word count, Slack-ready rendering, `DeltaState`, evidence references, and data gaps. `no_proposal_reason` is exactly `DATA_LOSS`, `AGENT_PENDING`, `TRUE_NO_TRADE`, or `WATCH_FOR_CONFIRMATION` when proposals are empty. No next-role or human workflow node is emitted. |
684
+ | `VizAgent`: `VizAgentInput` -> `VizAgentOutput` | None; this is an on-demand execution context | Runtime-selected, ACL-approved market-data, backtest, risk, or portfolio artifacts required by the requested chart | requested chart type, `charts: list[ChartArtifact]`, caption, and errors. Each chart records chart type, optional ticker, image reference, and exact source artifact references. A chart is unavailable when its typed source fields are absent; markdown regex parsing is not the V8 machine path. |
685
+ | `PortfolioMonitor`: `PortfolioMonitorInput` -> `PortfolioMonitorOutput` | None; this is a separately initialized monitoring context | Runtime-supplied open paper positions, alert thresholds, pause state, market-hours state, and quote-provider configuration | checked time, `position_checks: list[PositionCheck]`, `alerts: list[PortfolioAlert]`, quote provenance, and data gaps. Each check records position ID, ticker, direction, entry, current price when available, percentage move, and threshold states. This agent never closes a position. Runtime applies the validated last-monitor timestamp and publishes alerts. |
686
+
687
+ #### Schema Ownership And Validation Rules
688
+
689
+ 1. Every agent owns only the payload it produces. Renderers and runtime
690
+ aggregators may transform a valid payload but cannot add agent reasoning.
691
+ 2. Required dependency outputs are passed directly from the active Routing
692
+ Table plan. Agents do not search the session folder to discover upstream
693
+ producers.
694
+ 3. Optional and baseline artifacts are selected by the runtime through the
695
+ agent ACL and declared input schema.
696
+ 4. A schema-valid `PARTIAL` or `UNAVAILABLE` artifact carries explicit data
697
+ gaps and can satisfy dependency completion. Missing or malformed output is
698
+ an execution failure, not a no-trade conclusion.
699
+ 5. Ticker-bearing records must be inside the producer's effective scope.
700
+ References to records outside that scope are rejected before prompt
701
+ construction.
702
+ 6. Numeric unknowns are `null`; they are never represented as `N/A`, zero, or
703
+ prose inside machine artifacts.
704
+ 7. LLM prose is retained only in declared narrative fields. Enum values,
705
+ numbers, identifiers, evidence references, and decision fields must parse
706
+ and validate before publication or downstream use.
707
+ 8. Markdown and PNG files are product/download renderings. Typed JSON artifacts
708
+ are the inter-agent contract. Exact paths and owners are enumerated in
709
+ the File Content Reference and filename ACL tables.
710
 
711
  ### Runtime And Product Boundaries
712
 
 
730
 
731
  ### UI Visibility
732
 
733
+ The existing YOLO console remains the product entry point. Session selection,
734
+ ticker entry, baseline/delta runs, prior-run replay, options context, Finley
735
+ output, and package downloads remain available. The UI reads the same run
736
+ state used by Slack and the coordinator.
737
 
738
+ #### Run Views
739
+
740
+ | View | Content | Interaction |
741
+ |---|---|---|
742
+ | Run | Run ID, session, frozen tickers, baseline/delta label, execution progress, diagnostics, options context, and Finley's result. | Default view. Start YOLO, run again within the selected session, select a prior run, or download the existing session package. |
743
+ | Routing Table | Active agent rows with exact names, scope enum, effective tickers, required dependencies as a list, execution state, result availability, and waiting/failure detail. | Select an agent to inspect its inputs and outputs. Show the full registered table only through an explicit view toggle; inactive entries carry their exclusion reason. |
744
+ | Permissions | Per-agent read/create/edit/list filename lists, current-run bindings, selected baseline bindings, and publication state. | Select an agent; switch between declared filename templates and resolved paths. Read-only inspection; no ACL editing or agent activation controls. |
745
 
746
+ Session and run selection remain shared across all three views. Selecting a
747
+ different tab does not start a run or change its scope. `VizAgent` and
748
+ `PortfolioMonitor` are absent from the normal active YOLO table; the full
749
+ registry view identifies their separate execution contexts.
750
+
751
+ #### Progress And Result State
752
+
753
+ | Agent execution state | Display behavior |
754
+ |---|---|
755
+ | Waiting | Name the required producers whose outputs are not yet published for the overlapping ticker scope. |
756
+ | Running | Show every concurrently running agent, its actual start time, and elapsed time. |
757
+ | Completed | A valid output was published. Display its separate COMPLETE, PARTIAL, or UNAVAILABLE result status. |
758
+ | Failed | Show the named agent and recorded execution or schema-validation error. Preserve available earlier results. |
759
+ | Blocked | Name the failed or missing required dependency that prevents activation. Do not present this as a market recommendation. |
760
+ | Inactive | Visible only in the full registry view; explain empty effective scope or different execution context. |
761
+
762
+ Execution state comes from runtime activation and publication records. The UI
763
+ must not infer completion from message counts, a Markdown file's existence,
764
+ or the position of an agent in a linear array. A quiet LLM request can still
765
+ be running; a refresh/network error reports connection state without changing
766
+ the recorded agent result.
767
+
768
+ The run view shows completed/active counts and all current agent names. It
769
+ does not render a sequential arrow chain that implies parallel agents ran
770
+ one after another. Unavailable options evidence remains a visible data gap,
771
+ even when OptionsFlowWatcher completed its fetch/report operation.
772
+
773
+ #### Agent Details And Permissions
774
+
775
+ The selected agent detail contains effective tickers, dependency states,
776
+ start/end times, exact current and baseline input references, output identity,
777
+ schema version, result availability, and actionable failure detail when any.
778
+ Long paths wrap without hiding the agent name or permission column.
779
+
780
+ Permissions show what the agent may access, while input/output references
781
+ show what it actually consumed or produced. `[]` is displayed as None.
782
+ Baseline paths and published output paths are labelled read-only even when
783
+ the template permits editing during the owning activation. Runtime-owned
784
+ aggregate, state, replay, and ledger files retain their distinct ownership;
785
+ they are never shown as extra agent nodes.
786
+
787
+ File details are metadata supplied by the existing session/run payloads.
788
+ The download action continues to provide the available intermediate files;
789
+ this UI change does not add arbitrary server-file browsing or a new endpoint.
790
+
791
+ #### Finley And Diagnostics
792
+
793
+ Finley's readable market result remains primary. Routing summaries, JSON,
794
+ and artifact paths do not replace it. Before Publisher runs, the page shows
795
+ progress rather than placing progress text under a completed Finley result.
796
+
797
+ No-proposal output distinguishes missing evidence, analysis still pending or
798
+ failed, an actual NO_TRADE conclusion, and WATCH_FOR_CONFIRMATION. A provider
799
+ gap may coexist with a valid strategy conclusion; the UI displays both and
800
+ does not infer data loss solely from an empty proposal list. LLM/provider
801
+ failures name the affected agent and evidence component using recorded
802
+ diagnostics. A missing final result is never manufactured as NO_TRADE.
803
+
804
+ The existing options context remains available. Evidence ledgers stay in the
805
+ download package, and the distilled committee expansion remains halted under
806
+ the inherited V7.1 decision.
807
+
808
+ #### Replay And Responsive Behavior
809
+
810
+ - Prior-run views use their recorded routing plan, permission bindings,
811
+ statuses, inputs, outputs, and strategy weights. A later live run cannot
812
+ overwrite the selected replay view during polling.
813
+ - Legacy replay lacking routing/ACL snapshots displays that information as
814
+ unavailable for that recorded version. It does not attach today's contract
815
+ to the old run or execute agents to fill the gap.
816
+ - The existing session package is downloadable from every run state. The
817
+ selected run ID is visible so its files can be located inside the package.
818
+ - Desktop uses compact tables. On narrow screens, routing and permission
819
+ tables scroll within their view; agent details and long filenames wrap.
820
+ Controls remain keyboard accessible and status is communicated by text as
821
+ well as color. Refresh preserves selection and scroll position.
822
+ - A new/empty session shows the ticker entry and Run YOLO action. Loading,
823
+ absent replay, failed refresh, and empty options states have distinct labels.
824
+ - UI acceptance covers a mobile viewport of 390 x 844 and a desktop viewport
825
+ of 1440 x 900, including long paths, mixed tickers, parallel running rows,
826
+ failed dependencies, and a replay view while another run is active.
827
 
828
  ---
829
 
 
919
 
920
  ---
921
 
922
+ ## Design Status
923
 
924
+ The Routing Table and typed input/output contracts now cover all registered
925
+ quant agents. Specialized asset ownership and schema-level ticker filtering
926
+ are settled. Run-based storage, filename ACLs, and UI presentation are defined.
927
+ The implementation and verification sequence is in
928
+ [V8.0_IMPLEMENTATION_PLAN.md](V8.0_IMPLEMENTATION_PLAN.md).
929
+ These are design specifications. Checked definition items below mean that the
930
+ PRD section is written; implementation checkboxes in the plan remain open until
931
+ the corresponding behavior is implemented and verified.
932
 
933
  ---
934
 
 
943
  - [x] Define the complete Routing Table at the agent-dependency and scope level.
944
  - [x] Draft filename-based ACL rows and file-content references for all quant agents.
945
  - [x] Record baseline snapshot read permissions for session-delta context.
946
+ - [x] Define the `DataFetcher` typed input and output artifact contract.
947
+ - [x] Finalize shared-file ownership and scope-filtered access with typed schemas.
948
+ - [x] Define the filename ACL for each quant agent against the typed artifact layout.
949
+ - [x] Define typed input and output artifact schemas for each quant agent.
950
+ - [x] Define artifact storage, publication, baseline references, replay, and downloads.
951
+ - [x] Define UI presentation for dependency and ACL state.
952
+ - [x] Write the V8.0 implementation and verification plan.