Background

Evaluating TradingAgents advice against existing holdings requires audit records isolated from real positions and paper trading. Decision-time quotes must remain available for later review.

Changes

• Add ShadowPosition and ShadowTrade persistence models with position/decision references, target weights, execution rules, fill costs and execution status.
• Pass the collected quote into the result mapper and retain a selected market snapshot plus a normalized positive price_at_analysis.

Scope

One outcome: persist the schema and decision-time audit inputs for a future shadow portfolio. This does not create shadow positions, consume decisions or execute trades. The current PR diff contains 3 production files and 75 added/deleted production lines, plus 2 test files; no size exception is requested. A future decision bridge is a separate proposal, not delivered here.

Validation

Tested commit: 0d289de

Commands and results:

Independently executed on this exact detached commit on 2026-10-24, Linux, Python 3.12, pytest 9.1.1, SQLAlchemy 2.1.6:

PYTHONPATH=packages/marketdata/src:packages/pan-agent-runtime/src python -m pytest tests/test_shadow_portfolio_models.py tests/test_tradingagents_5_tier_rating.py tests/test_tradingagents_agent.py -q
70 passed in 1.12s
git diff f8c2b5e...HEAD --check
exit 0; no output

An initial run without the local package path returned 69 passed / 1 failed (ModuleNotFoundError: marketdata); the corrected run above passed. The old description's Windows run also reported 70 passed, but its original log was not independently available. No live model request or production database was used.

Acceptance evidence

Steps:

1. Check out the tested commit and expose the two local package source directories as in the command above.
2. Run the schema, mapper and agent tests.
3. Inspect the SQLite fixture's persisted shadow trade and the mapper's supplied quote snapshot.

Expected:
The shadow trade retains its real-position reference, target weight and cost JSON; the result retains decision-time quote fields. Existing rating/agent tests continue to pass.

Observed:
All 70 tests passed. The schema fixture asserts the real_position_id relationship, commission=12.5 and target_weight_pct=25. The snapshot test asserts price_at_analysis=12.34 and the supplied current/open prices and timestamp. This verifies these fixture assertions, not a production migration or an execution engine.

Evidence:
The sanitized executed output is included above and remains accessible in this PR body. Reproducible assertions: schema test and mapper tests. Source links describe assertions; they are not CI logs. No pull-request-triggered workflow runs were returned for this SHA during this audit. UI screenshots do not apply because this PR changes no UI.

Boundaries and risks

• This is a schema/audit foundation, not a working shadow trading workflow.
• Table creation follows the repository's existing startup mechanism; production upgrade, rollback and database-specific migration behavior have not been exercised.
• The tests do not prove historical quote accuracy, foreign-key deletion behavior on every backend, or fill correctness.
• No real account, order submission, paid model call or existing paper trading modification was performed.

Follow-up

Agree on any decision-bridge scope separately before implementation. Before production use, verify database upgrade/rollback and deletion semantics, then validate execution timing and cost accounting with their own evidence. Maintainer review of whether this prerequisite has sufficient standalone value is still required.