fix(executor): size each DCA buy from the rule's own amount (#840)

[eaitbrahim]

Closes #840

Milestone: DCA plan — proposal CLI and read-only card

What changed

keel/execution/executor.py _build_intent now sizes a DCA ENTER from the rule's amount, setup.context["size_usd"] (what Dca.detect computes: budget_usd × (1 + dip bonus)), instead of the config's single dca.budget_usd.

• A new helper, _dca_budget(context, fallback), returns (amount, "rule" | "config"). It falls back to config.dca.budget_usd only when size_usd is absent or is not a positive, finite number. A bool is refused too. Decimal('Infinity') > 0 is true, which is why the finite check is there: commands/rules.py documents how an infinite budget_usd gets through.
• The source is logged as executor.dca_sized, at INFO for rule and WARNING for config, with product, rule, rule_id and amount.
• Paper: agent._paper_enter sizes through the same executor._build_intent and fills intent.qty, so paper is fixed by the same change. A test pins it. The account sim (sim/portfolio_sim.py) already preferred size_usd, so live, paper and the sim now agree.
• No rail, cap, guard or veto changed, and max_exposure_usd is untouched. intent.notional is still spend(qty, entry) from the new qty, so rail 14 and every other guard see the real order, which is now smaller.
• Docs: the executor's "CAREFUL" comment is rewritten. It records that the old "config is the operator-facing dial" rationale was reversed by the operator on 2026-09-27. Also updated:
  • the executor module docstring and the _order_spec docstring;
  • a new DcaConfig docstring (in packages/keel-core);
  • the dca: comment in config.yaml, keel/templates/config.yaml and keel/templates/config.live.yaml;
  • equity.sizing_equity's docstring;
  • docs/operator-runbook.md and docs/RELEASING.md.

Before and after

rule	asset	amount	cadence	buys/month (30.44 d)	before ($50 each)	after (rule's amount)
6	BTC	$40	7d	4.35	$217.4	$173.9
8	ETH	$25	7d	4.35	$217.4	$108.7
9	PAXG	$25	14d	2.17	$108.7	$54.4
10–13	ADA/XLM/DOGE/FET	$15 each	14d	2.17 each	$434.9 (4 × 108.7)	$130.5 (4 × 32.6)
					≈ $978	≈ $467

Before, the book tried to spend about $978 a month against rail 14's $500 cap, so rail 14 vetoed the tail of each month. After, it spends the rules' ~$467, which fits under the cap. Rail 14 is unchanged and still vetoes any buy that would cross it.

This changes live behaviour only after a release and deploy. The live deployment runs installed wheels, not this repo.

Tests (each one seen failing before the implementation)

test	what it pins	red before the fix
(a) test_live_dca_sizes_from_the_rules_size_usd_not_the_config_budget	through the real execute() path, size_usd=25 at 50,000 places qty 0.0005 with quote_size 25, and logs source=rule	0.001 != 0.0005
(b) test_live_dca_falls_back_to_the_config_budget_without_a_usable_size_usd ×8	absent, None, 0, −25, Infinity, NaN, "25" and True all size from the config's 50 and log source=config	no executor.dca_sized record (fallback sizing already held; recording the source is new)
(c) test_a_dca_rules_detect_feeds_the_live_order_size_end_to_end	Dca(budget_usd=15).detect(...) → execute() → qty 0.0005 at 30,000	0.001666… != 0.0005
(c′) test_a_dip_scaled_dca_buy_spends_size_usd_not_the_rules_base_budget	with a dip, size_usd 18.75 ≠ budget_usd 15, and the order spends 18.75	added after the fix; red against the old code via mutant M1 below
(d) test_paper_dca_fill_is_sized_from_the_rules_amount_not_the_config_budget	_paper_enter with a real Dca(budget_usd=15) fills 0.5 at 30	1.666… != 0.5
(e) test_rail_14_sees_the_rules_true_notional_and_admits_a_25_dollar_buy_that_fits	$460 spent + $25 = $485 against a $485 cap is placed	intent notional 50.000 != 25
(e) test_rail_14_still_vetoes_a_25_dollar_dca_buy_that_would_cross_the_cap	$460 + $25 = $485 against a $480 cap is vetoed, and the veto names 460 + 25 = 485	the veto named 50.000

Mutants (each proven applied by a changed sha256, restored from a saved copy, never git checkout)

mutant	result	killed by
M1: revert to config.dca.budget_usd	KILLED (6 fail)	(a), (c), (c′), (d), both (e)
M2: drop the fallback (use size_usd unconditionally)	KILLED (10 fail)	all 8 (b) cases plus 2 existing DCA tests
M3: read budget_usd instead of size_usd	KILLED (4 fail)	(a), (c′), both (e)
M4: accept size_usd <= 0 (< 0)	KILLED (1 fail)	(b)[zero]
M5: drop the finite check	KILLED (2 fail)	(b)[infinity], (b)[nan]
M6: drop the bool guard	KILLED (1 fail)	(b)[bool]

Checks

• uv run pytest -q: 6854 passed, 3 skipped, exit 0
• uv run ruff check keel tests: exit 0
• uv run ruff format --check keel tests: exit 0
• uv run mypy (bare): no issues in 473 source files, exit 0

Not done here

• deploy/live-rules.json still records a single BTC DCA rule at budget_usd: "50". The brief lists seven live DCA rules, with BTC at $40. Now that the rule's amount is what spends, that manifest is worth syncing from the deployment in a separate change.
• The sim's own fallback (size_usd or config.dca.budget_usd) still accepts a negative size_usd. It is not touched here, and Dca refuses a non-positive budget_usd at construction.
• The root config.*.yaml profiles (config.live-sandbox.yaml, the paper profiles) keep their uncommented dca: blocks.

🤖 Generated with Claude Code