Loading NeuFin…
Loading NeuFin…
A machine-readable structure for representing a single proposed financial decision — the investor context, mandate, suitability, evidence, and disposition behind it — so it can be reviewed, audited, and replayed independent of the system that produced it.
This is a NeuFin specification, not an industry, official, or regulatory standard. It's published so developers, AI agent frameworks, and other systems can adopt a shared structure for representing investor-aware decisions.
Agentic and AI-assisted wealth workflows produce a lot of proposed decisions — rebalance suggestions, outreach flags, drafted recommendations. Without a shared structure, the context behind each decision (who proposed it, under what mandate, based on what investor and portfolio state, checked against what suitability and policy constraints) tends to live in system-specific formats that are hard to audit or move between tools. The Decision Assurance Envelope defines that structure once, so it can travel with the decision.
decision_idUnique identifier for this specific proposed decision.
trace_idLinks this decision to a broader workflow or conversation trace.
organization_idThe organization (firm, platform, tenant) this decision was evaluated within.
investor_idThe specific investor this decision concerns.
actor_id / agent_idThe human actor or AI agent associated with this decision.
actor_or_agentStructured identity of whoever proposed the decision.
mandateWhat the actor or agent is actually authorized to do for this investor.
investor_contextRisk tolerance, time horizon, investment policy, behavioral history.
portfolio_contextCurrent, relevant state of the investor's holdings.
proposed_actionThe specific action being proposed for review.
suitabilityResult of comparing the proposed action to the investor's mandate and risk profile.
policyResult of comparing the proposed action to firm-level policy constraints.
evidenceThe traceable basis for the decision — sources and reasoning summary.
confidenceSystem-assigned confidence score for the decision, 0 to 1.
human_approvalRecord of human review, when required.
dispositionPROCEED, REVIEW, ESCALATE, or DENY.
The full JSON Schema is published at /specs/decision-assurance-envelope/v1.schema.json.
PROCEED
Investor context, suitability, and policy checks passed cleanly.
REVIEW
Something warrants advisor attention before the action moves forward.
ESCALATE
The mismatch or stakes require senior or specialist review.
DENY
The action should not proceed as proposed.
These four values are the business dispositions defined by this specification. Technical systems may separately represent a NOT_EVALUATED state where a check could not be completed, outside this vocabulary.
{
"decision_id": "dec_9f2a1c",
"trace_id": "trace_88b210",
"organization_id": "org_acme_wealth",
"investor_id": "inv_44210",
"actor_or_agent": {
"type": "ai_agent",
"id": "agent_rebalance_v2",
"name": "Rebalance Copilot"
},
"mandate": {
"scope": "propose_only",
"authorized_actions": ["propose_rebalance"],
"constraints": ["no_direct_execution"]
},
"investor_context": {
"risk_tolerance": "moderate",
"time_horizon": "10+ years",
"investment_policy_summary": "Balanced growth, max 15% single-position concentration"
},
"portfolio_context": {
"as_of": "2026-09-19T00:00:00Z",
"concentration_summary": "22% in single technology position"
},
"proposed_action": {
"type": "rebalance",
"description": "Trim technology position from 22% to 15% of portfolio"
},
"suitability": {
"match": false,
"notes": "Current concentration exceeds investment policy limit"
},
"evidence": {
"sources": ["portfolio_feed", "investment_policy_statement"],
"reasoning_summary": "Concentration limit exceeded per IPS section 4.2"
},
"confidence": 0.91,
"disposition": "REVIEW"
}NeuFin's own decision-assurance layer produces and consumes Decision Assurance Envelopes internally, and exposes related behavioral and suitability tools through its MCP server. Third-party systems can adopt the same JSON structure to represent their own proposed decisions in a way that's reviewable and auditable using the same vocabulary.
Version: v1.0.0. Usage: this specification is published by NeuFin for reference and integration purposes. See NeuFin's Terms and Conditions for usage terms. This is not an industry, official, or regulatory standard.
Public asset: the full schema, worked examples, field reference, and validator examples are published on GitHub — github.com/stealthg0dd/neufin-public.