augur: actor policy — one channel for buys and sells, target allocation over a cash band

[agentydragon]

The agent's transactions should all come from one place: a policy in the RL sense — a box taking the world state as the agent can see it and emitting actions. Everything below follows from insisting on exactly one such channel.

Contract

Batched. The observation is a struct of arrays: every field carries the rollout axis ((account, R), (lot, R), …), and the policy is a pure jittable function (batch of observations) → (batch of actions), actions shaped (action_slot, R). No per-rollout Python anywhere. A learned policy drops into the same signature later.

Only what's visible. The view carries the agent's own account balances, holdings at their mark, per-lot basis and holding period, and YTD income/tax. Not other agents, not the rest_of_world contra row, and nothing dated after the current month.

Sim calculates, never approximates. A policy may only act on prices the simulator can compute exactly. Equities mark off the realized path, so they can be sold. A bond before maturity cannot — its price is a discount of remaining cashflows on a curve that does not exist yet — so a policy asking to sell one must be rejected loudly until #3740's marking work lands, never served a book-value stand-in.

What it subsumes

• LiquidityPolicy's ordered asset_preference_chain — removed outright, not deprecated. A strict preference chain is not a limit case of weights (it drains a sleeve to zero; weights never do), so keeping both would mean two real behaviors where only one is wanted.
• ScheduledAssetPurchase (added in augur: buy assets mid-horizon, and make cost basis per-rollout #3743, tombstoned there) — a scheduled buy is a policy that ignores state. Two channels for one action drift on ordering against obligations, on the underfunding clamp, on basis, and on the event log. Its execution layer stays and is what the policy emits into: pre-allocated lot slots, per-rollout cost basis, whole-quanta rounding, the external contra credit, settling after obligations.

Target allocation

Integer relative weights over a declared sleeve universe. A fraction is derivable from weights, so storing fractions stores a computed quantity and needs a float sum-to-one validator to defend it. Anything not named is outside the policy's scope and out of the denominator — a target over an asset you cannot trade (PE before liquidity, a rung you will not break) makes the policy permanently overweight something it cannot sell, and it thrashes.

Splitting a withdrawal is water-filling: find a level L with Σ max(0, valueᵢ − L·weightᵢ) = S, each sleeve giving up max(0, valueᵢ − L·weightᵢ). Every sleeve still holding anything ends at the same value-per-weight, which is the definition of on-target — so a withdrawal lands the portfolio on the target ratios rather than nearer them.

Rebalancing happens only through cashflow. There is no standalone rebalance action, because turnover and its tax drag would swamp the effect the allocation study is trying to measure. Zero drift plus zero cashflow must produce zero actions.

Cash band

[floor, ceiling] replaces cash_buffer_trigger_below_usd + cash_buffer_sale_usd (a fixed sale slug is undefined whenever the shortfall exceeds it).

• cash < floor → sell up to the ceiling
• cash > ceiling → buy down to the floor
• inside the band → no action

That is (s,S): cross a bound, go to the far edge. It minimizes crossings, which matters here because every sale is taxable and, more importantly, a thin buffer makes you a forced seller into every dip — the risk the whole exercise exists to price. Recorded counterargument: selling to the ceiling realizes gains earlier than necessary, and deferral is worth real money. Far-edge vs near-edge is empirical, and it is the first rule to vary if results look sensitive to it.

Timing. The sell decision fires once, at the start of the month, sized to known outflows this month + restore to ceiling, and then obligations pay. Obligations are scheduled, so that is a calculation, not a forecast. One sale a month like a real person — and an unpayable obligation then means genuinely nothing left to sell, which is what makes RUIN meaningful for #3740.

Bounds are AmountSpec, so a floor can be CPI-indexed; a flat $50k floor in 2056 is not a floor. The better long-run form is months of spending, which self-indexes and interacts correctly with the tier state — deferred to #3738, because it is circular with that state and the break has to read last month's obligation.

Full-stack

Not sim-internal. Deleting the ordered policy changes api/wire.py's FundingPolicy, product/scenarios.py's translation, input_helpers.ts defaults and payload, the "Cash buffer" group in scenario_editor.tsx, SellOrderControl in forms.tsx, ~8 server_test.py call sites, and SPEC's product paragraph. The UI mapping: "Sell preference" (ordered drag-list) → per-holding integer weights; "Trigger below" / "Sell amount" → floor / ceiling; "Buffer index" survives and applies to both bounds. One atomic PR — no transitional shims.

Acceptance

• Same view ⇒ same actions, independent of rollout index; rollouts never couple.
• No future information: two scenarios identical through month m, diverging by a large shock at m+1, produce identical actions at m.
• The view's account count equals the agent's own accounts; rest_of_world is unreachable from it.
• Weights (3,1) and (30,10) produce identical action streams.
• Zero drift, zero cashflow ⇒ zero actions.
• A withdrawal splits exactly — sleeve amounts sum to the request, no sleeve driven negative or past its value, however awkward the rounding.
• Cash crossing a bound returns to the far edge; inside the band, nothing fires.
• A ladder that self-liquidates gets rebuilt: the bond sleeve reverts to target rather than decaying monotonically (needs augur: classify trajectories — ruin / forced tier drop / intact #3740's par-yield path).
• A pre-maturity bond sale is rejected at compile time until marking exists.

[agentydragon]

Lot-slot exhaustion

It is a real concern, not hypothetical. lot_count is fixed at compile time under the dense-shape discipline, and once the policy decides when to buy, the number of buys is path-dependent — a state-driven "invest the surplus" rule fires a different number of times in each rollout.

Fatal, not graceful — and the reason matters more than the convenience. Failing only the rollouts that ran out of slots would silently drop exactly the paths that traded most. Trading frequency correlates with volatility, so those are disproportionately the turbulent paths, and removing them would bias the terminal distribution toward calm — understating precisely the risk this whole exercise exists to measure. A quiet per-rollout failure is worse than useless here; it is a systematically optimistic answer. Aborting the run is the only unbiased option.

Mechanism mirrors the existing sale_oversell precedent: a () bool in the scan carry, OR-accumulated across months and rollouts (exhausted = exhausted | overflow.any()), threaded out of the scan alongside failed_month, and raised post-scan. Nothing new is needed in the engine's shape discipline, and it costs one boolean.

The error must name the fix, not just the fault: slots configured, slots needed (max over rollouts), and which sleeve overflowed — so the response is a mechanical bump rather than an investigation.

Why a configured budget rather than always allocating the structural maximum. The safe bound is knowable: at most one buy per sleeve per month, so horizon × sleeves can never overflow. It just is not free — lot state is carried as history, (snapshot_months, lot, rollout), so at a 30-year horizon with 3 sleeves and 1000 rollouts the structural maximum is on the order of gigabytes for a buffer that is mostly empty slots. So the budget is a real optimization the caller opts into, not a gratuitous knob, and the failure mode is a loud error that tells them the exact number to set.

Acceptance:

• A scenario whose policy needs more slots than configured aborts the whole run with an error naming configured-vs-needed; it does not fail individual rollouts and does not truncate silently.
• Setting the budget to horizon × sleeves cannot overflow for any path.
• Unused slots cost nothing behaviorally: a run with a large budget and few buys produces identical output to one sized exactly.

---

Generated by Claude Code

[agentydragon]

Spend is an action

Decided 2026-08-05. The current model gives the policy obligations as an input and lets it choose only how to fund them. That leaves the agent's biggest decision — how much to spend — outside the policy entirely, which is the same defect as having two transaction channels: behaviour split across two mechanisms that cannot coordinate. The cake is about spending being a choice, so a policy that cannot emit it is modelling the actor's broker, not the actor.

The line is commitment vs. discretionary, which is not the same as scheduled vs. recurring:

• Commitments — mortgage payment, property tax, the tax bill, a lease already entered. Consequences of past decisions. Sim calculates them; the policy sees them and cannot decline them. Correctly exogenous to this month's choice.
• Discretionary — the entire gap between the SF and Prague numbers. Chosen every month, and therefore a policy output.

So the action language is buy / sell / spend, and it needs all three now even though only buy and sell get implementations in this issue — retrofitting a third action kind into an already-wired dense action tensor means designing the type twice.

The mechanism already exists. Spending flows as a RecurringObligation to a sink agent. What blocks it is that the amount is an AmountSpec, which is structurally closed to exogenous series — it can read a CPI path but not simulated state. Making an obligation's amount policy-emitted is the whole change.

Ordering, and why there is no fixed point. The policy chooses spending from month-start state, then sizes funding to cover commitments plus that choice. Not "attempt to fund, fail, retract" — that would be a within-month fixed point. A tier drop is triggered by what was visible at the start of the month and takes effect the month after, which is also how it works in life.

This does not disturb cash_band.py: cash_order takes scheduled_outflow_cents, and the caller passes commitments + chosen spending rather than commitments alone. The seam was already in the right place.

Acceptance:

• The action tensor can express a spend action, and a policy emitting one moves cash to the sink agent as an ordinary transfer with its own event row.
• Spending is chosen from month-start state only: a shock arriving later in the month cannot change this month's spend.
• Commitments remain undeclinable — a policy cannot emit a "spend" that reduces a contracted obligation.
• With a constant spend action the run is identical to today's configured-obligation equivalent.

Deferred: tiers are bundles, not dials

A tier changes the rent commitment, the Location, and tax residency — which jurisdictions apply from that month on. Handwaved for now (see sim/TODO.md, tracked with #3738): tier state changes the spending level only, and every tier keeps the agent's starting jurisdictions. Any result about a cheaper-location tier is optimistic until that lands, because it spends Czech amounts while paying California tax. One-off transition costs (moving, breaking a lease) are unmodelled for the same reason, and they are what make hysteresis a real constraint rather than only an anti-chatter device.

---

Generated by Claude Code

[agentydragon]

Slot cost is smaller than I claimed, for a fixable reason

Designing the runtime slot pool turned up something that changes the budget calculus above.

I argued the structural maximum (horizon * sleeves slots) was unaffordable because lot state is carried as history, (snapshot_months, lot, rollout) — gigabytes at a 30-year horizon. That is true of lot_remaining, which genuinely changes every month. It is not true of the two per-rollout lot attributes:

• lot_cost_basis_state, added in augur: buy assets mid-horizon, and make cost basis per-rollout #3743
• lot_purchase_month, which has to become per-rollout for runtime slots (a reserve slot's fill month is decided during the scan)

Both are written once and never change, because slots are never reused. Every snapshot after the purchase month is a copy of the one before it. Carrying them as (lot, rollout) final state rather than (snapshot, lot, rollout) history costs a factor of snapshot_months less — 361× at a 30-year horizon — for the same information.

That materially widens what the budget can afford, so the "generous reserve" option is cheaper than the issue body implies. It does not remove the need for the abort: lot_remaining still scales with slot count, and the bias argument for aborting rather than degrading is unchanged.

One wrinkle if this is done: the decoded asset_lots frame is per-month, so a final-state basis would report the eventual basis for months before the purchase, where the lot holds zero units. Today those months report a basis of zero. Neither is meaningful next to a zero quantity, but it is a visible frame change and should be a deliberate one rather than a side effect.

Not doing it as part of the runtime-slot work — it is a separable change to something already merged and green, and bundling it would mean a memory refactor rides along with a behavioural one.

Runtime slots: settled design

• Homogeneous reserve per (policy, sleeve). All slots in a reserve share agent, account and asset, so they are interchangeable and per-rollout divergence in which slot gets used is harmless.
• Per-rollout cursor. A buy consumes the next free slot; the cursor is (policy, sleeve, rollout) carry state.
• Compile-time FIFO still holds. Cursor allocation is monotonic within a rollout, so slot order equals chronological order and the existing static lexsort stays correct. That is the same property that let augur: buy assets mid-horizon, and make cost basis per-rollout #3743 skip runtime ordering.
• Purchase month becomes per-rollout state, which is what augur: buy assets mid-horizon, and make cost basis per-rollout #3743 explicitly deferred. Holding-period classification reads it, so _record_capital_gains' long/short mask goes from (lot,) to (lot, rollout).
• Month-keyed slots were the alternative that would have kept purchase month static, but they only work at the full structural maximum — with a smaller reserve there is no sound mapping from month to slot, and merging two purchases into one slot would blend their bases and break exact FIFO.

---

Generated by Claude Code