MAP Documentation

How to read your MEAL statements, set MANA budgets, configure throttle policy, run reconciliation.

Companion to Concepts → Metering. This page covers the operations side.

Read a statement

map invoke MEAL statement --input '{
  "tenant_id": "org_acme",
  "period": { "from": "2026-05-01T00:00:00Z", "to": "2026-05-31T23:59:59Z" },
  "include_breakdown": true,
  "group_by": ["protocol", "operation"]
}'

Returns the metered events grouped by protocol and operation, with totals per dimension.

{
  "tenant_id": "org_acme",
  "period": { "from": "...", "to": "..." },
  "totals": {
    "tokens":  18_432_100,
    "seconds": 84_320.7,
    "watts_kWh": 312.4,
    "amount_usd": 4_812.55
  },
  "by_protocol": [
    { "protocol": "MARC",  "tokens": 14_200_000, "seconds": 28_400.2, "watts_kWh": 240.1, "amount_usd": 3_180.45 },
    { "protocol": "MIND",  "tokens":  3_120_500, "seconds": 18_320.4, "watts_kWh":  18.2, "amount_usd":   820.10 },
    { "protocol": "MAX",   "tokens":           0, "seconds": 38_200.1, "watts_kWh":   2.1, "amount_usd":   811.00 },
    { "protocol": "...",   "...": "..." }
  ],
  "settlement_status": "current",
  "next_invoice_at": "2026-06-01T00:00:00Z"
}

Set a budget

map invoke MANA allocate --input '{
  "envelope": {
    "department": "research",
    "max_per_month_usd": 5000,
    "max_per_day_usd": 250
  },
  "capabilities_granted": [
    "map.marc.reasoning_task",
    "map.mari.inquire",
    "map.maven.cite",
    "map.mind.recall_memory"
  ],
  "authority": "max://record/0xcharter..."
}'

MANA then enforces the envelope at Stage 5 of the pipeline. Calls that would exceed the per-day or per-month cap are refused with PolicyDenied { reason: "runway exhausted" }.

Throttle policy

When runway compresses, MANA::throttle reduces non-essential rate-limit buckets:

map invoke MANA throttle --input '{
  "envelope_id": "...",
  "rules": [
    { "match": "map.mind.recall_memory", "factor": 0.5 },
    { "match": "map.marc.*",             "factor": 0.25 },
    { "match": "map.max.audit_query",    "factor": 1.0 }
  ]
}'

Read operations on MAX are deliberately untouched — the institution can always read its own history.

Emergency hold

map invoke MANA hold --input '{
  "reason": "Anomalous spend detected — see motet trace abc",
  "scope": "tenant",
  "until": "manual_release"
}'

Multi-sig revocable via MACE quorum. All non-essential operations refuse until released.

Reconciliation

MEAL::reconcile runs nightly. To run on-demand:

map invoke MEAL reconcile --input '{
  "period": { "from": "2026-05-01T00:00:00Z", "to": "2026-05-31T23:59:59Z" }
}'

Asserts that

sum(tenant_debits) = sum(merchant_credits) + sum(audit_records)

Any drift produces an Unbalanced event recorded to MAX and routes to ops. Drift is almost always benign (timezone window edge cases) but worth surfacing.

Settlement

For cross-org settlement (the fourth metered dimension at the rate-card level), MADE clears via the configured rail. Configure rails per tenant:

map invoke MADE asset_definition_publish --input '{
  "asset_id": "settlement-usdc-x402",
  "kind": "currency",
  "rail": "x402",
  "denomination": "USDC",
  "settlement_finality_seconds": 3
}'

Settlement runs in the background; the audit chain records both the metered event (in MEAL) and the settled payment (in MADE). MEAL::reconcile cross-checks.

Rate-card overrides

Per-tenant overrides on the published rate card (for Sovereign tier or special arrangements):

map invoke MEAL admin_set_rate --input '{
  "tenant_id": "org_acme",
  "overrides": {
    "tokens_per_million_usd": 2.50,    # default $3.00
    "seconds_per_million_usd": 15.00,  # default $18.00
    "watts_per_kwh_usd":      0.36     # default $0.42
  },
  "effective_from": "2026-06-01T00:00:00Z",
  "authority": "max://record/0xcontract..."
}'

Requires map.meal.admin capability. Overrides are recorded to MAX; the next invoice picks them up.

Per-operation metering details

Protocol::operation	Tokens	Seconds	Watts
`MAX::audit_log_entry`	0	yes	0
`MAX::audit_query`	0	yes	0
`MIND::store_memory`	0	yes	`<0.001 kWh`
`MIND::recall_memory`	0	yes	`<0.001 kWh`
`MIND::fusion_request`	yes (agent path)	yes	yes
`MARC::reasoning_task`	yes	yes	yes (multiplier 1.2×)
`MAVEN::attest`	yes (multiplier 0.8×)	yes	yes
`MACE::deliberate`	yes (multiplier 1.5× per delegate)	yes	yes
`MAGI::trace`	yes	yes (multiplier 2×)	yes (multiplier 4×)
`MOON::execute_workflow`	per-step	yes	per-step
`MIM::message_send`	0	yes	0

Heavyweight agents (MARC, MACE, MAGI) typically dominate consumption. Most protocols meter on seconds only.

Metering ops