Documentation Index
Fetch the complete documentation index at: https://docs.meshqu.com/llms.txt
Use this file to discover all available pages before exploring further.
This page introduces the key abstractions you will work with when integrating MeshQu.
Decision boundary
The decision boundary is the moment a system outcome becomes irreversible — execution, settlement, release, or approval. MeshQu is designed to sit at the decision boundary: your application calls it before (or after) that moment and receives a governed verdict.
Decision context
A decision context is the payload you send to MeshQu describing what is about to happen. It contains:
| Field | Description |
|---|
decision_type | A string identifying the kind of operation (e.g. trade_execution, withdrawal). |
fields | Domain-agnostic values the policies evaluate (account, amount, instrument, etc.). |
metadata | Optional key-value pairs for traceability (source system, request ID, etc.). |
evidence | Optional supporting data that policies may reference during evaluation (e.g. credit_report_id, sanctions_list_version). Evidence supports the audit trail but does not drive policy logic. |
source_artifact | Optional cryptographic binding to a source document (hash + metadata). |
Policy
A policy is a named, versioned governance configuration that MeshQu evaluates against incoming decision contexts. Policies have:
- A unique
code (human-readable identifier).
- An
advisory_mode flag: when enabled, DENY decisions are downgraded to ALERT for observation.
- One or more versions. Only the active version is used during evaluation.
You manage policies via the API or the MeshQu Console.
Policy groups
Policies can be organised into policy groups for batch management. A decision context may be evaluated against all policies in a group.
Decision
Every evaluation returns a decision:
| Decision | Meaning |
|---|
ALLOW | All evaluated policies passed. Proceed normally. |
REVIEW | One or more policies flagged the context for manual review. |
DENY | One or more policies rejected the context. |
ALERT | An advisory-mode policy would have denied; logged for observation. |
Decision receipt
Every evaluation returns a cryptographic receipt that binds the verdict to the exact policy snapshot used:
{
"decision": "ALLOW",
"policy_snapshot_id": "11111111-1111-1111-1111-111111111111",
"evaluated_rules_hash": "2c26b46b68ffc68ff99b453c1d...sha256",
"integrity_hash": "6f1ed002ab5595859014ebf09...sha256",
"signature": "base64url-encoded-ed25519-signature",
"signature_kid": "msk_v1",
"signature_algorithm": "ed25519",
"timestamp": "2025-01-15T10:30:00.000Z"
}
integrity_hash (SHA-256) covers the context, decision, and snapshot in canonical JSON, making the result independently verifiable. When a signing key is configured, MeshQu signs the integrity hash with Ed25519. Auditors can verify receipts using the public key alone — no shared secret is needed. The signature_kid identifies which key signed the receipt, supporting key rotation.
Actor
An actor identifies who or what triggered a decision — a human reviewer, an automated system, or a service account. Actors are optional but strongly recommended for workflows where audit trails must name a responsible party.
| Field | Type | Description |
|---|
id | string | Stable identifier for the actor (e.g. user ID, service name). Included in the integrity hash. |
type | string | human or system. |
role | string | Functional role (e.g. analyst, compliance_officer, screening_service). |
authority | string | Optional. The authority or organisation the actor acts under. |
display_name | string | Optional. Human-readable name for audit display. |
actor.id is the only actor field included in the integrity hash and therefore cryptographically bound to the receipt. Other fields (type, role, authority, display_name) are stored for audit display but are not part of the cryptographic proof.
Conditional rules
Rules can include an optional when clause for conditional applicability. A rule with when is only evaluated when the clause matches the decision context — otherwise it returns NA (not applicable) and does not affect the outcome. NA rules still appear on the decision receipt with a human-readable reason, proving the system considered the rule and explaining why it didn’t apply.
Supported operators:
| Form | Example | Matches when |
|---|
equals | { "field": "currency", "equals": "USD" } | Field value is exactly "USD". |
in | { "field": "currency", "in": ["USD", "EUR"] } | Field value is one of the listed values. |
exists | { "field": "credit_score", "exists": true } | Field is present (or absent if false). |
all | { "all": [clause, clause] } | All nested clauses match (AND). |
any | { "any": [clause, clause] } | At least one nested clause matches (OR). |
{ "all": [{ "field": "region", "in": ["EU", "UK"] }, { "field": "amount", "exists": true }] }.
See the API Reference for the full when syntax in policy creation.
Violation
When a policy does not pass, it produces one or more violations. Each violation includes:
rule_code — which rule raised it.reason_code — a structured code for programmatic aggregation (e.g., FIELD_MISSING, VALUE_ABOVE_MAX).reason — a human-readable explanation.severity — how serious the violation is.
Decision (recorded)
A decision is a persisted evaluation result. You create one by calling /v1/decisions/record with an idempotency_key. Recorded decisions support:
- Retrieval by ID or listing with filters.
- Replay for audit verification.
- Linking to alerts.
- Grouping into decision chains.
Decision outcome
A decision outcome captures what happened after a verdict. For example, a REVIEW decision might be accepted or overridden by a human reviewer.
| Status | Meaning |
|---|
accepted | Verdict was accepted as-is. |
overridden | Verdict was overridden (includes final_action). |
escalated | Referred to a higher authority. |
expired | No action taken within the required window. |
abandoned | Process was abandoned. |
Decision chain
A decision chain is an ordered group of decision receipts that together prove a governed outcome across multiple steps. Chains enable workflow traceability — instead of a bag of individual receipts, a regulator or auditor sees an ordered, parent-linked structure from trigger to outcome.
Each step in a chain is a full cryptographic receipt (integrity hash + Ed25519 signature + optional Rekor anchor). The chain provides queryable grouping and ordering — it does not weaken the proof.
Key properties:
- Steps are ordered by
chain_step (1-based, unique per chain).
- Each step may reference a
parent_decision_id for causal lineage.
- Chain membership is declared at record time and is immutable.
- Steps can come from automated evaluation or manual form review.
- The verification endpoint checks each receipt’s integrity and reports structural warnings (gaps, parent linkage).
Example: AML workflow
| Step | Decision type | Verdict | Source |
|---|
| 1 | Transaction screening | REVIEW | Automated |
| 2 | Analyst review | ALLOW | Manual form |
| 3 | Final disposition | ALLOW | Automated |
GET /v1/decisions?chain_id=... returns all three steps in order. The verification endpoint confirms each receipt is individually sound.
See the Decision Chains guide for integration patterns and the API Reference for endpoint details.
Alert
An alert is raised when notable conditions are detected (e.g. a critical policy failure). Alerts have a severity (low, medium, high, critical) and can be acknowledged. You can subscribe to alert webhooks for real-time notification.
Tenant
All data is isolated per tenant. Every API request includes a X-MeshQu-Tenant-Id header, and the API key must belong to that tenant.
Operational guarantees
- Deterministic policy evaluation
- Immutable policy snapshots
- Idempotent decision recording
- Tenant-isolated data
- Replayable audit trail
These are contractual properties of the platform.
What MeshQu is not
- Not a rules engine you embed. MeshQu is a standalone service. Your application calls it over HTTP.
- Not an execution layer. MeshQu returns a verdict. It never blocks, allows, or modifies operations on its own.
- Not a permissions system. MeshQu does not manage authentication or resource access. Use it alongside your existing IAM.
- Not a real-time data feed. MeshQu evaluates the context you send. It does not subscribe to market data or external sources.
- Not a scoring or risk engine. MeshQu evaluates decisions against policy. It does not generate risk scores or predictions.
- Not an explainability tool. MeshQu proves policy compliance. Model explainability is a separate concern.
Explicit non-goals
MeshQu intentionally does not:
- Generate risk scores or predictions.
- Subscribe to external data feeds.
- Manage user authentication or authorization.
- Explain upstream model behaviour.
These are out of scope by design, not missing features.
How auditors use MeshQu
- Request a decision by ID.
- Replay the decision against the original policy snapshot.
- Verify integrity hashes to confirm the verdict has not been altered.
- If the receipt is signed, verify the Ed25519 signature using the public key.
- Confirm the policy snapshot and timestamp match expectations.
No access to application code or models is required.
Decision lifecycle
- Build context — your application assembles a decision context (type, fields, metadata, evidence).
- Evaluate — MeshQu evaluates the context against active policies at the decision boundary.
- Receive verdict — MeshQu returns
ALLOW, REVIEW, DENY, or ALERT with a cryptographic receipt.
- Act — your application enforces the verdict (proceed, queue, or block).
- Record (optional) — persist the evaluation for audit by calling
/v1/decisions/record.
Evaluate vs Record
| Evaluate (/v1/decisions/evaluate) | Record (/v1/decisions/record) |
|---|
| Persisted | No — stateless, nothing stored | Yes — context, verdict, and metadata stored |
| Idempotency key | Not required | Required |
| Typical use | Real-time gating, dry-run testing | Audit trail, compliance evidence |
Example: blocking a trade and proving it later
- Order service reaches the decision boundary.
- Application calls
evaluate with the trade context.
- MeshQu returns
DENY with a policy snapshot hash.
- Application blocks execution and surfaces violations.
- Decision is recorded with an idempotency key.
- Six months later, an auditor replays the decision and verifies integrity hashes match.
No application code or model access is required.
How these fit together
Next: API Reference — full endpoint listing.
