@aclymatepackages/mcp-envelope-codes

Central registry for FM §4 response-envelope codes used by every Aclymate MCP tool. Exports two frozen objects:

• WARNING_CODES — non-fatal signals attached to a successful response's warnings[] array (e.g. factor_not_found, drill_key_defaulted, climate_brain_fallback).
• ERROR_CODES — fatal codes attached to envelope.error.code when a tool returns an error envelope (e.g. invalid_input, climate_brain_unavailable).

Why this exists

Warning and error codes are part of the FM §4 envelope contract. Free-floating string literals in each tool file drift over time — the same conceptual signal ends up spelled two different ways across tools, breaking partner-UI card rendering and cross-engine parity checks. This package owns the canonical spelling.

Usage

const { WARNING_CODES, ERROR_CODES } = require("@aclymatepackages/mcp-envelope-codes");

// Attach a warning to a successful (result: null) envelope.
buildSuccessEnvelope({
  result: null,
  warnings: [
    {
      code: WARNING_CODES.FACTOR_NOT_FOUND,
      message: "No factor with id 'X' exists. Use search_factors to find related factors."
    }
  ]
});

// Return a structural-failure error envelope.
buildErrorEnvelope({
  code: ERROR_CODES.CLIMATE_BRAIN_UNAVAILABLE,
  http_status: 503,
  message: "Aclymate's Climate Brain is temporarily unavailable. Retry in a moment."
});

buildSuccessEnvelope / buildErrorEnvelope are caller-supplied — this package owns only the codes, not the envelope builders.

Code catalogue

WARNING_CODES — soft signals on successful envelopes

Catalog-lookup misses (fail-null discipline — never a 400)

| Code | Emitted when | |---|---| | factor_not_found | lookup_factor_by_id — the supplied factor_id doesn't exist. | | unknown_factor_type | Any browse tool — the factor_type string isn't in the manifest. | | unknown_key_name | find_factor / list_factor_key_values — the key_name isn't valid on that factor_type. | | no_keys_supplied | find_factor — caller sent {} or omitted keys (assertion mode; empty keys ≠ discovery). | | no_match_for_keys | find_factor — keys are valid but no factor matches. | | no_search_matches | search_factors — zero hits for the query. | | no_drill_key_available | list_factor_key_values — factor_type has no designated drill key and none was supplied. |

Search / drill defaults (partially-successful)

| Code | Emitted when | |---|---| | result_truncated | search_factors — returned 25 of N matches; caller should narrow the query. | | drill_key_defaulted | list_factor_key_values — key_name omitted; used the factor_type's designated drill key. | | disambiguation_hint | get_emission_factor — canonical hit succeeded, but the alias index also matched other factors worth naming. |

Canonical-row degradation (should be rare in a healthy catalog)

| Code | Emitted when | |---|---| | missing_value | Canonical row matched but the value block is empty (value === null and no values map). | | missing_source | Canonical row matched but has no source metadata. | | manifest_unavailable | Manifest is empty at boot — no factor types available. |

Climate Brain provenance (distinct warnings for four distinct product surfaces)

| Code | Emitted by | Says to the caller | |---|---|---| | climate_brain_fallback | get_emission_factor (miss path) | "No canonical factor for this activity — this response is AI-assisted, not from the catalog." | | climate_brain_authored | explain_scope | "Aclymate-voiced Climate Brain output describing a well-known standard, not a canonical reference document." | | climate_brain_estimate | estimate_emissions | "Generated against SMB pattern data, not derived from the customer's actual data." | | climate_brain_benchmark | compare_business_footprint | "Benchmark generated against SMB patterns, not against the customer's real emissions." | | factors_lookup_unavailable | get_emission_factor (backend-outage path) | "factorsLookup backend threw — this response is a Climate Brain fallback, not a canonical miss." Distinguishes true "no match" from "backend down." |

Calc tool defaults (from B-Tier1-calcs, already in production)

| Code | Emitted when | |---|---| | default_used | Calc tool used a default value for a required input (e.g. NYC↔LA flight distance). | | class_defaulted | Flight/train tool used the DEFRA average across cabin/class variants. | | nec_overrides_train_type | Train tool applied the Northeast Corridor factor and ignored the supplied trainType. | | unknown_region | Electricity tool couldn't match the supplied eGrid region and fell back to a global average. |

ERROR_CODES — structural failures on error envelopes

| Code | Emitted when | HTTP | |---|---|---| | invalid_input | Zod validation failed (missing required field, wrong type, unparseable JSON). | 400 | | calc_unexpected_output | Calc engine returned a value that couldn't be interpreted (NaN, negative, non-finite). | 500 | | missing_bearer_token | Auth middleware couldn't find a Bearer token on the request. | 401 | | tier_mismatch | Caller's tier doesn't grant access to the requested tool. | 403 | | unknown_tool | Requested tool name isn't in the registry. | 404 | | internal_api_unavailable | renew-west internalApi returned 5xx or unreachable. | 503 | | climate_brain_unavailable | callClimateBrain threw or returned an empty response. | 503 |

Contract

Values are lowercase snake_case strings. Both objects are Object.freezed — any attempt to add or mutate keys at runtime is a bug in the caller.

Adding a new code requires bumping this package's version and re-publishing before consuming tools can rely on it.

Codes ownership: FM §4 of the MCP hill's Feature Map (see internal/functions/knowledge/feature-maps/hill-8Dl6hIaZLYEI3aAL42Tk-feature-map.md).