dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/data/src/trade/plans/executor-live.js

@@ -0,0 +1,220 @@
+// task-1363 — the LIVE fire path for the plan engine: an Executor that fills through the REAL signer process
+// (devnet only, from the capped FAST WALLET). The engine is synchronous and tick-driven; the signer is a child
+// process answered asynchronously. This adapter bridges the two WITHOUT the engine ever waiting:
+//
+//   quote(leg)      first call starts `signer.fill(...)` (build + policy + simulate + USD pricing in the SIGNER)
+//                   and throws RpcOutage (the engine logs price.unusable/rpc-outage and retries on the next
+//                   fresh tick, no attempt consumed). Once the signer has answered, the next quote() returns a
+//                   Quote carrying the signer's verdict: policy/sim/caps refusals arrive as `simOk:false` with
+//                   the signer's own reason, so the engine journals `policy.refused` with that reason.
+//   nextSignature() an INTENT id (`live_N`) the engine journals BEFORE anything is sent (CL-03).
+//   submit(leg)     starts `signer.confirm(hash)` — the signer re-checks caps, reserves USD, has the fast
+//                   wallet sign, verifies + re-simulates the bytes, submits and confirms — and returns
+//                   `send-unknown` at once: the engine marks the leg in flight and settles it by `lookup`.
+//   lookup(intent)  'not-found' while the confirm runs; {confirmed, fill} / 'failed' once the signer answered;
+//                   a transport error at confirm stays 'not-found' (the engine expires it after 90 s, never
+//                   resends — the chain may still have it; the fast wallet is capped so exposure is bounded).
+//
+// What is real on devnet: the lamports the fill moves out of the fast wallet (fees of the wrap-and-unwrap
+// sized to the plan's SOL leg), the signature, the on-chain memo naming the plan leg, the signer's USD
+// per-trade/daily ledger. What is MODELLED: the token leg (Jupiter has no devnet, so no token changes hands);
+// the fill is booked from the planned USD at the fire-time price and labelled `kind:'devnet-fill'` +
+// `modelledTokens:true` in the journal. Nothing in this file signs, holds a key, or reaches mainnet: the signer
+// refuses `fill` off devnet and never loads a fast wallet there.
+import { RpcOutage } from "./executor.js";
+/** How long a signer build is reused before it is rebuilt (the signer's own plan TTL is 90 s). */
+export const LIVE_BUILD_TTL_MS = 60_000;
+/** Remote refusals the signer formats as `reason: message`; anything else from the client is a transport problem. */
+const REMOTE_REFUSAL = /^(network-mismatch|no-fast-wallet|build-failed|bad-request|panicked|no-wallet|signer-mismatch|plan-mismatch):\s*/;
+export class LivePlanExecutor {
+    kind = 'live';
+    signer;
+    clock;
+    solUsd;
+    ttl;
+    onChange;
+    log;
+    builds = new Map();
+    pending = new Map();
+    intents = 0;
+    constructor(o) {
+        this.signer = o.signer;
+        this.clock = o.clock;
+        this.solUsd = o.solUsd;
+        this.ttl = o.buildTtlMs ?? LIVE_BUILD_TTL_MS;
+        this.onChange = o.onChange ?? (() => { });
+        this.log = o.log ?? (() => { });
+    }
+    /** The signer must be alive, on DEVNET, with a fast wallet loaded. Checked by the host before switching to live. */
+    async ready() {
+        if (!this.signer.alive)
+            return { ok: false, why: 'the signer process is not available' };
+        let status;
+        try {
+            status = await this.signer.status();
+        }
+        catch (e) {
+            return { ok: false, why: `signer status: ${msg(e)}` };
+        }
+        if (status.network !== 'devnet')
+            return { ok: false, why: `the signer is on ${status.network}; live plan fills run on devnet only` };
+        if (status.panic || status.ledgerLocked)
+            return { ok: false, why: 'live trading is panicked (dexterm wallet resume)' };
+        let fast;
+        try {
+            fast = await this.signer.fast();
+        }
+        catch (e) {
+            return { ok: false, why: `signer fast: ${msg(e)}` };
+        }
+        if (!fast.loaded || !fast.publicKey)
+            return { ok: false, why: fast.reason ?? 'no fast wallet is loaded in the signer' };
+        return { ok: true, network: 'devnet', fastWallet: fast.publicKey, balanceLamports: fast.balanceLamports };
+    }
+    /** One-line label for banners. */
+    describe(fastWallet) { return `LIVE · DEVNET · fast wallet${fastWallet ? ` ${fastWallet.slice(0, 4)}…${fastWallet.slice(-4)}` : ''}`; }
+    legId(req) { return `${req.plan.id}:${req.legKey}`; }
+    /** The SOL leg in lamports for this leg (buy: USD / SOL-USD; sell: tokens × price / SOL-USD). Null without a SOL price. */
+    lamportsFor(req) {
+        const sol = this.solUsd();
+        if (sol === null || !(sol > 0))
+            return null;
+        const usd = req.side === 'buy' ? (req.usd ?? 0) : req.tokenRaw !== null ? Number(req.tokenRaw) / 10 ** req.plan.decimals * req.priceUsd : 0;
+        if (!(usd > 0))
+            return null;
+        return BigInt(Math.round(usd / sol * 1e9));
+    }
+    quote(req) {
+        const id = this.legId(req);
+        const now = this.clock.now();
+        const b = this.builds.get(id);
+        if (b && b.state === 'building')
+            throw new RpcOutage();
+        if (b && b.state === 'outage') {
+            this.builds.delete(id);
+            throw new RpcOutage();
+        } // retried: a new build starts on the next quote
+        if (b && b.state === 'refused') {
+            this.builds.delete(id);
+            return this.refusedQuote(req, b.error ?? 'build refused', b.at);
+        }
+        if (b && b.state === 'built' && b.view && now - b.at < this.ttl && b.view.expiresAt > now)
+            return this.quoteFromView(req, b.view, b.at);
+        if (b)
+            this.builds.delete(id);
+        // start a build
+        const lamports = this.lamportsFor(req);
+        if (lamports === null) {
+            this.log(`live plans: no SOL/USD price yet to size ${id}; retrying`);
+            throw new RpcOutage();
+        }
+        const build = { state: 'building', view: null, error: null, at: now, usd: req.usd, tokenRaw: req.tokenRaw, priceUsd: req.priceUsd };
+        this.builds.set(id, build);
+        void this.signer.fill({ ref: id, mint: req.plan.mint, symbol: req.plan.symbol, decimals: req.plan.decimals, side: req.side, lamports: lamports.toString() })
+            .then((view) => { build.state = 'built'; build.view = view; build.at = this.clock.now(); this.onChange(); })
+            .catch((e) => {
+            const m = msg(e);
+            if (REMOTE_REFUSAL.test(m)) {
+                build.state = 'refused';
+                build.error = m;
+            }
+            else {
+                build.state = 'outage';
+                build.error = m;
+                this.log(`live plans: signer fill failed (${m}); retrying`);
+            }
+            this.onChange();
+        });
+        throw new RpcOutage();
+    }
+    refusedQuote(req, error, at) {
+        const m = REMOTE_REFUSAL.exec(error);
+        const reason = m ? m[1] : 'signer-refused';
+        return {
+            side: req.side, priceUsd: req.priceUsd, impactPct: 0, route: ['devnet-fill'], feeLamports: 0, tipLamports: 0,
+            simOk: false, simError: error, refusal: { reason, message: error.replace(REMOTE_REFUSAL, '') }, usd: req.usd, tokenRaw: req.tokenRaw, at,
+        };
+    }
+    /** The signer's verdict as a Quote: its policy / simulation / caps refusal (if any) travels with its own reason. */
+    quoteFromView(req, v, at) {
+        const bad = !v.policy.ok ? v.policy : !v.sim.ok ? { ok: false, reason: 'simulation-failed', message: v.sim.error ?? 'simulation failed' } : !v.precheck.ok ? v.precheck : null;
+        return {
+            side: req.side,
+            // a devnet fill has no route, so the signer cannot imply a price; the tick's price stands (on a Jupiter
+            // route the quote-implied price would come from the signer's view instead)
+            priceUsd: req.priceUsd,
+            impactPct: v.priceImpactPct ?? 0, route: [...v.route],
+            feeLamports: Number(v.feeLamports), tipLamports: 0,
+            simOk: bad === null, simError: bad ? `${bad.reason ?? 'refused'}: ${bad.message ?? ''}` : null,
+            refusal: bad ? { reason: bad.reason ?? 'signer-refused', message: bad.message ?? 'refused by the signer' } : null,
+            usd: req.usd, tokenRaw: req.tokenRaw, at,
+        };
+    }
+    nextSignature() { return `live_${++this.intents}`; }
+    submit(req) {
+        const id = this.legId(req);
+        const b = this.builds.get(id);
+        this.builds.delete(id);
+        if (!b || b.state !== 'built' || !b.view)
+            return { kind: 'send-failed', signature: req.signature, error: 'no fresh signer plan for this leg (rebuilt on the next tick)', feeLamports: 0 };
+        const view = b.view;
+        const p = { legId: id, hash: view.hash, state: 'confirming', outcome: null, error: null, fill: null, signature: null };
+        this.pending.set(req.signature, p);
+        void this.signer.confirm(view.hash)
+            .then((out) => {
+            p.outcome = out;
+            if (out.kind === 'filled') {
+                p.state = 'filled';
+                p.signature = out.signature;
+                p.fill = this.modelFill(req, out);
+            }
+            else if (out.kind === 'refused' || out.kind === 'send-failed') {
+                p.state = 'failed';
+                p.error = out.kind === 'refused' ? `${out.reason}: ${out.message}` : out.error;
+                p.signature = out.kind === 'send-failed' ? out.signature : null;
+            }
+            else {
+                p.state = 'unknown';
+                p.error = out.error;
+                p.signature = out.signature;
+            }
+            this.onChange();
+        })
+            .catch((e) => { p.state = 'unknown'; p.error = msg(e); this.log(`live plans: confirm transport error (${p.error}); outcome unknown, never resent`); this.onChange(); });
+        return { kind: 'send-unknown', signature: req.signature, error: 'live confirm in flight (fast wallet, devnet)', feeLamports: req.quote.feeLamports + req.quote.tipLamports };
+    }
+    /**
+     * The fill the engine books. SOL: the real on-chain delta the signer reported (fees of the wrap-and-unwrap).
+     * Tokens: MODELLED from the planned USD at the fire-time price (no token moves on devnet) and labelled so.
+     */
+    modelFill(req, out) {
+        const dec = req.plan.decimals;
+        const usd = req.usd ?? (req.tokenRaw !== null ? Number(req.tokenRaw) / 10 ** dec * req.quote.priceUsd : 0);
+        const tokens = req.tokenRaw ?? BigInt(Math.round(usd / req.quote.priceUsd * 10 ** dec));
+        return {
+            tokenDelta: req.quote.side === 'buy' ? tokens : -tokens,
+            solDelta: BigInt(out.fill.solDelta),
+            usd, priceUsd: req.quote.priceUsd,
+            kind: 'devnet-fill', signature: out.signature, modelledTokens: true, network: out.network,
+        };
+    }
+    lookup(signature) {
+        const p = this.pending.get(signature);
+        if (!p)
+            return 'not-found';
+        if (p.state === 'filled' && p.fill)
+            return { status: 'confirmed', fill: p.fill };
+        if (p.state === 'failed')
+            return { status: 'failed' };
+        return 'not-found'; // confirming, or an unknown outcome: never resent, expires in the engine
+    }
+    chainFill(signature) { return this.pending.get(signature)?.fill ?? null; }
+    /** Diagnostics for the TUI (what is building / in flight / settled). */
+    snapshot() {
+        return {
+            builds: [...this.builds.entries()].map(([leg, b]) => ({ leg, state: b.state, error: b.error })),
+            pending: [...this.pending.entries()].map(([intent, p]) => ({ leg: p.legId, intent, state: p.state, signature: p.signature, error: p.error })),
+        };
+    }
+}
+function msg(e) { return e instanceof Error ? e.message : String(e); }

package/dist/packages/data/src/trade/plans/executor-paper.js

@@ -0,0 +1,44 @@
+// task-1355 — PAPER fire path for the plan engine (the default; no key, no wallet, no network, no mainnet).
+//
+// Implements the engine's Executor by booking fills deterministically at the fire-time tick price, exactly
+// as paper trading does elsewhere (packages/data/src/paper.ts computeFill). The engine's signer-side policy
+// (caps, allow-list, impact ceiling, panic, trigger re-confirm) still runs on every fire — this executor
+// only stands in for "sign with the fast wallet + land", so a paper mandate exercises the full money-safe
+// path with zero funds at risk. The real devnet/mainnet fire path (async Jupiter warm-quote +
+// LiveExecutor.confirmAndSubmit) is a separate adapter and is intentionally not this one.
+export class PaperPlanExecutor {
+    kind = 'paper';
+    clock;
+    solUsd;
+    fees;
+    impactPct;
+    chain = new Map();
+    sigN = 0;
+    constructor({ clock, solUsd = 150, baseFeeLamports = 5_000, priorityFeeLamports = 500_000, tipLamports = 100_000, impactPct = 0.4 }) {
+        this.clock = clock;
+        this.solUsd = solUsd;
+        this.fees = { baseFeeLamports, priorityFeeLamports, tipLamports };
+        this.impactPct = impactPct;
+    }
+    quote({ plan, side, usd, tokenRaw, priceUsd }) {
+        return {
+            side, priceUsd, impactPct: this.impactPct, route: ['Paper'],
+            feeLamports: this.fees.baseFeeLamports + this.fees.priorityFeeLamports, tipLamports: this.fees.tipLamports,
+            simOk: true, simError: null, usd: usd ?? null, tokenRaw: tokenRaw ?? null, at: this.clock.now(),
+        };
+    }
+    nextSignature() { return `PAPER${String(++this.sigN).padStart(6, '0')}`; }
+    computeFill(decimals, quote, usd, tokenRaw) {
+        const tokens = tokenRaw ?? BigInt(Math.round((usd / quote.priceUsd) * 10 ** decimals));
+        const usdValue = usd ?? Number(tokens) / 10 ** decimals * quote.priceUsd;
+        const lamports = BigInt(Math.round(usdValue / this.solUsd * 1e9));
+        return { tokenDelta: quote.side === 'buy' ? tokens : -tokens, solDelta: quote.side === 'buy' ? -lamports : lamports, usd: usdValue, priceUsd: quote.priceUsd };
+    }
+    submit({ plan, quote, signature, usd, tokenRaw }) {
+        const fill = this.computeFill(plan.decimals, quote, usd, tokenRaw);
+        this.chain.set(signature, { status: 'confirmed', fill });
+        return { kind: 'filled', signature, feeLamports: quote.feeLamports + quote.tipLamports, fill, roundTripMs: 0 };
+    }
+    lookup(signature) { return this.chain.get(signature) ?? 'not-found'; }
+    chainFill(signature) { return this.chain.get(signature)?.fill ?? null; }
+}

package/dist/packages/data/src/trade/plans/executor.js

@@ -0,0 +1,11 @@
+// task-1355 — the EXECUTOR boundary the plan engine fires through.
+//
+// The engine never signs or sends. It calls an Executor that stands in for "quote -> build -> simulate ->
+// sign (fast wallet) -> send -> confirm". In tests this is a scripted FixtureExecutor (no key, no wallet,
+// no network; research/task-1292/sim/executor.mjs); in the app it is a live adapter bridging to the real
+// signer-side LiveExecutor / PaperExecutor (plans/executor-live.ts). Caps/allow-list/panic are re-checked
+// by the signer on every submit — the engine is only the trigger brain, never the key holder.
+/** A transient RPC/transport failure: nothing fired, nothing sent; retried on the next fresh tick. */
+export class RpcOutage extends Error {
+    constructor() { super('rpc outage'); this.name = 'RpcOutage'; }
+}

package/dist/packages/data/src/trade/plans/index.js

@@ -0,0 +1,12 @@
+// task-1355 — order-plan + mandate engine (SPEC §6.13). Front-end agnostic; lives in the signer trust
+// domain alongside caps/killswitch/executor. Voice and agents can only PROPOSE; arming needs a
+// signer-issued keypress/Phantom gesture proof; caps are frozen and the signer re-checks every fill.
+export { PLAN_SCHEMA_VERSION, MATERIAL_FIELDS, PlanError, proposePlan, canonicalPlan, planHash, amendPlan, displayText, readBack, fmtUsd, priceForMc } from "./plan.js";
+export { HARD, TIERS, MandateError, draftMandate, armMandate, revokeMandate, capsHash, mandateAlive } from "./mandate.js";
+export { HOLD_MS, CHALLENGE_TTL_MS, ECHO_GUARD_MS, RISK_ACCEPT_TTL_MS, ConfirmError, Settings, ConfirmGate, gestureTier } from "./confirm.js";
+export { Journal, redact, eventHash } from "./journal.js";
+export { RpcOutage } from "./executor.js";
+export { PaperPlanExecutor } from "./executor-paper.js";
+export { LivePlanExecutor, LIVE_BUILD_TTL_MS } from "./executor-live.js";
+export { PlanEngine, PolicyRefusal, TERMINAL } from "./engine.js";
+export { PlanService, parseAmount, parseTrigger, parseExit, planStatusLabel, defaultPlansJournalPath } from "./service.js";

package/dist/packages/data/src/trade/plans/journal.js

@@ -0,0 +1,77 @@
+// task-1355 — the append-only, hash-chained JOURNAL (audit log + crash-recovery source of truth; §6.13.3/§6.13.12).
+//
+// Every state change is an event: {seq, ts, type, planId?, mandateId?, data, prev, hash}. `hash` covers
+// the whole event including `prev`, so a removed, reordered or edited line breaks the chain and
+// `verify()` reports exactly where. Signatures are journaled BEFORE a send (CL-03), so a crash between
+// "sent" and "confirmed" is recoverable by looking the signature up, never by re-sending. Secrets never
+// enter the journal: there is no field for keys, and `redact()` scrubs anything key-shaped defensively.
+// Ported from the task-1292 reference simulation (research/task-1292/sim/journal.mjs), typed.
+import { createHash } from 'node:crypto';
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+const KEY_SHAPED = /(?:[1-9A-HJ-NP-Za-km-z]{85,90})|(?:\[(?:\s*\d{1,3}\s*,){63}\s*\d{1,3}\s*\])/g;
+export function redact(s) { return String(s).replace(KEY_SHAPED, '[REDACTED]'); }
+export function eventHash(e) {
+    const body = JSON.stringify({ seq: e.seq, ts: e.ts, type: e.type, planId: e.planId ?? null, mandateId: e.mandateId ?? null, data: e.data ?? null, prev: e.prev });
+    return createHash('sha256').update(body).digest('hex');
+}
+export class Journal {
+    path;
+    clock;
+    events = [];
+    head = 'genesis';
+    dirReady = false;
+    /** `path` optional: when given, every event is also appended to a JSONL file (crash recovery / audit export). */
+    constructor({ path = null, clock }) {
+        this.path = path;
+        this.clock = clock;
+        if (path && existsSync(path))
+            this.load(path);
+    }
+    append(type, fields = {}) {
+        const base = {
+            seq: this.events.length + 1,
+            ts: this.clock.now(),
+            type,
+            planId: fields.planId ?? null,
+            mandateId: fields.mandateId ?? null,
+            data: fields.data ?? null,
+            prev: this.head,
+        };
+        const e = { ...base, hash: eventHash(base) };
+        this.events.push(e);
+        this.head = e.hash;
+        if (this.path) {
+            // task-1376: a fresh HOME has no ~/.dexterm yet; create it (owner-only) on the first write instead of ENOENT.
+            if (!this.dirReady) {
+                mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+                this.dirReady = true;
+            }
+            appendFileSync(this.path, redact(JSON.stringify(e)) + '\n');
+        }
+        return e;
+    }
+    load(path) {
+        const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+        this.events = lines.map((l) => JSON.parse(l));
+        this.head = this.events.length ? this.events[this.events.length - 1].hash : 'genesis';
+    }
+    /** Verify the chain. Returns {ok:true} or {ok:false, atSeq, why}. */
+    verify() {
+        let prev = 'genesis';
+        for (let i = 0; i < this.events.length; i++) {
+            const e = this.events[i];
+            if (e.seq !== i + 1)
+                return { ok: false, atSeq: e.seq, why: 'seq gap' };
+            if (e.prev !== prev)
+                return { ok: false, atSeq: e.seq, why: 'prev mismatch' };
+            const { hash, ...rest } = e;
+            if (eventHash(rest) !== hash)
+                return { ok: false, atSeq: e.seq, why: 'hash mismatch' };
+            prev = e.hash;
+        }
+        return { ok: true, count: this.events.length };
+    }
+    byPlan(planId) { return this.events.filter((e) => e.planId === planId); }
+    types() { return this.events.map((e) => e.type); }
+}

package/dist/packages/data/src/trade/plans/mandate.js

@@ -0,0 +1,129 @@
+// task-1355 — MANDATE schema, arming, and the signer-side admission check (SPEC §6.13.2).
+//
+// A mandate is a standing authorization. It is DRAFTED by anyone (voice, Claude, a preset, the user) and
+// ARMED only by a gesture proof of kind 'keypress' or 'phantom' that the signer side itself issued and
+// consumed. There is no `raiseCap()`; a mandate's caps are immutable after arming — a change is a new
+// draft that needs a new arming gesture. Hard ceilings clamp every cap regardless of what was asked.
+// Ported from the task-1292 reference simulation (research/task-1292/sim/mandate.mjs), typed and frozen.
+import { createHash } from 'node:crypto';
+export const HARD = Object.freeze({
+    totalUsd: 2000, perTradeUsd: 500, perCoinUsd: 1000, dailyLossUsd: 2000,
+    maxArmedPlans: 200, maxInFlight: 25, maxOpenPositions: 100,
+    maxSlippageBps: 1000, maxPriceImpactPct: 3,
+    tipBudgetLamports: 500_000_000, maxTipLamportsPerTx: 10_000_000, maxPriorityFeeLamportsPerTx: 10_000_000,
+    ttlMs: 24 * 3600_000, maxSendsPerSec: 20,
+});
+/** Confirmation tiers and the multiplier they apply to a mandate's per-trade cap for plans confirmed that way. */
+export const TIERS = Object.freeze({
+    'keypress': { rank: 0, perTradeMultiplier: 1.0, canArmMandate: true, canArmBatch: true },
+    'ptt-held': { rank: 1, perTradeMultiplier: 0.5, canArmMandate: false, canArmBatch: false },
+    'hands-free': { rank: 2, perTradeMultiplier: 0.25, canArmMandate: false, canArmBatch: false },
+});
+export class MandateError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'MandateError';
+        this.reason = reason;
+    }
+}
+function clamp(v, dflt, hardMax) {
+    const n = typeof v === 'number' ? v : Number(v);
+    if (!(n > 0) || !Number.isFinite(n))
+        return dflt;
+    return Math.min(n, hardMax);
+}
+/** Validate an untrusted mandate draft. Every cap is clamped to the hard ceiling; nothing is coerced upward. */
+export function draftMandate(input, ctx) {
+    const x = input ?? {};
+    const now = ctx.clock.now();
+    const actions = Array.isArray(x.actions) ? x.actions.filter((a) => a === 'buy' || a === 'sell') : ['buy', 'sell'];
+    if (actions.length === 0)
+        throw new MandateError('bad-request', 'at least one of buy/sell');
+    const m = {
+        v: 1,
+        id: ctx.id ?? `mandate_${now.toString(36)}_${Math.random().toString(36).slice(2, 8)}`,
+        wallet: 'fast', // the capped fast wallet; the main wallet is never named here
+        budget: {
+            totalUsd: clamp(x.totalUsd, 100, HARD.totalUsd),
+            perTradeUsd: clamp(x.perTradeUsd, 20, HARD.perTradeUsd),
+            perCoinUsd: clamp(x.perCoinUsd, 40, HARD.perCoinUsd),
+            dailyLossUsd: clamp(x.dailyLossUsd, 50, HARD.dailyLossUsd),
+        },
+        limits: {
+            maxArmedPlans: clamp(x.maxArmedPlans, 20, HARD.maxArmedPlans),
+            maxInFlight: clamp(x.maxInFlight, 5, HARD.maxInFlight),
+            maxOpenPositions: clamp(x.maxOpenPositions, 20, HARD.maxOpenPositions),
+            maxSlippageBps: clamp(x.maxSlippageBps, 500, HARD.maxSlippageBps),
+            maxPriceImpactPct: clamp(x.maxPriceImpactPct, 3, HARD.maxPriceImpactPct),
+            maxSendsPerSec: clamp(x.maxSendsPerSec, 5, HARD.maxSendsPerSec),
+        },
+        fees: {
+            tipBudgetLamports: clamp(x.tipBudgetLamports, 50_000_000, HARD.tipBudgetLamports),
+            maxTipLamportsPerTx: clamp(x.maxTipLamportsPerTx, 1_000_000, HARD.maxTipLamportsPerTx),
+            maxPriorityFeeLamportsPerTx: clamp(x.maxPriorityFeeLamportsPerTx, 2_000_000, HARD.maxPriorityFeeLamportsPerTx),
+        },
+        allowed: {
+            actions,
+            safetyFilter: typeof x.safetyFilter === 'string' ? x.safetyFilter.slice(0, 32) : 'safety-v1',
+            mints: Array.isArray(x.mints) ? x.mints.filter((s) => typeof s === 'string').slice(0, 500) : null, // optional explicit allow-list
+        },
+        maxTier: (typeof x.maxTier === 'string' && x.maxTier in TIERS) ? x.maxTier : 'keypress',
+        createdAt: now,
+        expiresAt: now + clamp(x.ttlMs, 4 * 3600_000, HARD.ttlMs),
+        status: 'draft', armedAt: null, armedBy: null, revokedAt: null, revokedReason: null,
+    };
+    // perTrade can never exceed total; perCoin never exceeds total.
+    m.budget.perTradeUsd = Math.min(m.budget.perTradeUsd, m.budget.totalUsd);
+    m.budget.perCoinUsd = Math.min(m.budget.perCoinUsd, m.budget.totalUsd);
+    // Caps are immutable after drafting: a different cap is a different draft that needs its own gesture.
+    Object.freeze(m.budget);
+    Object.freeze(m.limits);
+    Object.freeze(m.fees);
+    Object.freeze(m.allowed);
+    return m;
+}
+/**
+ * Arm a mandate. Only a signer-issued, unconsumed 'keypress' or 'phantom' proof bound to THIS mandate's
+ * caps hash is accepted. Spoken proofs of any tier are refused: voice can never arm a mandate.
+ */
+export function armMandate(m, proof, ctx) {
+    if (m.status !== 'draft')
+        throw new MandateError('not-draft', `mandate is ${m.status}`);
+    if (!proof || proof.kind !== 'gesture' || !proof.signerIssued)
+        throw new MandateError('no-gesture', 'arming needs a signer-issued gesture proof');
+    if (proof.gesture !== 'keypress' && proof.gesture !== 'phantom')
+        throw new MandateError('voice-cannot-arm', `a ${proof.gesture} proof cannot arm a mandate`);
+    if (proof.subject !== `mandate:${m.id}:${capsHash(m)}`)
+        throw new MandateError('proof-mismatch', 'the proof is for a different mandate or different caps');
+    if (proof.consumed)
+        throw new MandateError('proof-consumed', 'this proof was already used');
+    proof.consumed = true;
+    const now = ctx.clock.now();
+    if (now > m.expiresAt)
+        throw new MandateError('expired', 'mandate draft expired');
+    m.status = 'armed';
+    m.armedAt = now;
+    m.armedBy = { gesture: proof.gesture, proofId: proof.id };
+    return m;
+}
+export function revokeMandate(m, reason, ctx) {
+    if (m.status === 'revoked')
+        return m;
+    m.status = 'revoked';
+    m.revokedAt = ctx.clock.now();
+    m.revokedReason = String(reason).slice(0, 120);
+    return m;
+}
+/** Hash of the caps a gesture arms — the proof binds to these numbers, not to the mandate id alone. */
+export function capsHash(m) {
+    return createHash('sha256').update(JSON.stringify({ b: m.budget, l: m.limits, f: m.fees, a: m.allowed, t: m.maxTier, e: m.expiresAt, w: m.wallet })).digest('hex').slice(0, 16);
+}
+/** Alive = armed and not expired. Expiry is checked on every call, never cached. */
+export function mandateAlive(m, now) {
+    if (m.status !== 'armed')
+        return { ok: false, reason: m.status === 'draft' ? 'mandate-not-armed' : `mandate-${m.status}` };
+    if (now > m.expiresAt)
+        return { ok: false, reason: 'mandate-expired' };
+    return { ok: true };
+}