feat: policy simulation sandbox for dry-running rules

[Timmatt112]

Closes #50

Summary

Adds a policy simulation sandbox modal that lets administrators dry-run proposed spending rules against custom (historical or simulated) agent transactions before enforcing them on-chain — preventing misconfigured rules from locking up agent funds.

What was built

src/features/policies/policySimulation.ts (new)

Pure, React/DOM-free evaluation engine:

• Reuses the established Zod schemas from rulesSchema.ts (PolicyRule, RuleField, RuleOperator, RuleAction).
• simulateTransaction(tx, rules) evaluates every clause in order, firewall-style first-match semantics, and escalates the verdict across matched actions (allow < flag/require_approval < block).
• Returns SimulationVerdict (allowed | flagged | rejected), a human-readable summary, an ordered EvaluatedClause[] trail (each clause shows the actual value checked, the operator, the rule value, and whether it matched), and matchedClauseIndices.
• Whitelist rules parse the comma-separated value format used by the existing rule builder UI; comparisons are case-insensitive.

src/features/policies/PolicySimulationModal.tsx (new)

• Simulation input form: amount, asset (XLM/USDC/BTC/ETH/EURC), recipient address, agent tags — validated with Zod via react-hook-form + zodResolver, matching the validation patterns already used in SpendingPolicyBuilder.tsx.
• Recipient must be a valid Stellar public key (reuses isValidStellarPublicKey from the freighter store).
• Immediate visual feedback: verdict banner with Allowed / Flagged / Rejected badge (success/warning/danger variants) driven by the engine result.
• Step-by-step evaluation breakdown: ordered list of every clause checked, showing If <field> <operator> <value> then <action>, the engine's actual comparison detail, and a Matched/No-match badge per clause.
• Reuses the existing accessible Dialog primitive: portal rendering, focus trap, Escape-to-close, overlay dismissal, focus restoration on close.
• Screen-reader friendly: aria-live="polite" status region announces the verdict after each run, sr-only verdict text, labelled inputs, aria-haspopup="dialog" on the launcher.
• Ships PolicySimulationSandbox (button + modal pair) and a default sample ruleset; accepts a custom rules prop so it can be pointed at live builder state.

Wiring

• Exported from src/features/policies/index.ts (PolicySimulationModal, PolicySimulationSandbox, defaultSimulationRules, engine types/helpers).

Acceptance criteria

• Simulation input form with custom amounts, recipient addresses, agent tags
• Simulation evaluation logic returning matching policy clauses and verdict
• Step-by-step evaluation breakdown inside a clean modal component
• Integrates with the established Zod policy validation schemas (rulesSchema.ts)
• Keyboard accessible + screen-reader friendly (focus trap, Esc, aria-live)
• npx eslint clean on all touched files; npm run typecheck introduces no new errors (the only remaining errors pre-exist on main in src/app/(dashboard)/transactions/page.tsx and are untouched by this PR)

Edge cases covered by the engine

• Zero / negative amounts (Zod min(0) on the form; engine treats amount as a plain number for greater_than/less_than)
• Exact limit boundaries (> / < are strict, so a transaction exactly at the limit does not trigger greater_than — matches the builder's wording)
• Unauthorized destination accounts (whitelist in_whitelist + contains on Destination Target)
• Unknown/malformed rule values (numeric comparisons against non-numeric values safely return "no match" instead of throwing)
• Empty rule set (renders an explicit "allowed by default" notice rather than an empty panel)

Test plan

• npx eslint on touched files — clean.
• npm run typecheck — no new errors vs main.
• Manual: open sandbox, run amount 1200 USDC against the default ruleset → require_approval clause fires → Flagged; amount 11000 → Rejected; whitelisted recipient under the ceiling → Allowed; malformed recipient → inline Zod error; Esc closes the modal and focus returns to the launcher.

[vercel]

@Timmatt112 is attempting to deploy a commit to the Cjay's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Timmatt112 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits