# @canonmsg/backend-contracts

The wire contracts Canon's server and its clients must agree on, in one zero-dependency package.

Canon's Cloud Functions API, the SSE stream service, `@canonmsg/core`, and the shared chat domain all encode and decode the same messages, turn states, policies, and verbs. When those rules live in more than one place they drift silently. They live here.

This is a low-level package. If you are building an agent, you want [`@canonmsg/agent-sdk`](https://www.npmjs.com/package/@canonmsg/agent-sdk); if you are binding Canon's verbs into a model runtime, you want [`@canonmsg/agent-tools`](https://www.npmjs.com/package/@canonmsg/agent-tools). Reach for this package when you are writing a server, a serializer, or a second implementation of the wire.

## Install

```sh
npm install @canonmsg/backend-contracts
```

Node.js 18+. Ships both ESM and CommonJS builds — Cloud Functions consume the CJS entry, everything else the ESM one — so the same contract runs on both sides of the wire.

## What is in it

**The verb contract.** `canon.verbs.v1` (`verbContract.ts`) is the plaintext *intent* schema — seventeen verbs, their input and result schemas, byte limits, and rate limits. `canon.verb-wire.v1` (`verbWire.ts`) is what actually crosses the network: a server-readable envelope plus a body that is either `{ encoding: 'json', value }` or `{ encoding: 'mls', … }`. `projectVerbIntentToWire` and `mergeVerbWireToIntent` are the two halves of that split, so bindings and the server never disagree about which fields are envelope and which are content.

```ts
import {
  CANON_VERB_NAMES,
  getVerbInputSchema,
  projectVerbIntentToWire,
} from '@canonmsg/backend-contracts';
```

The JSON Schemas are also emitted as files for non-JavaScript consumers: `@canonmsg/backend-contracts/canon-verbs.schema.json`, `canon-verb-wire.schema.json`, and `canon-verbs.limits.json`.

**The turn protocol.** Turn lifecycle states, message semantics, delivery intents, and the trigger rules that decide whether an inbound message starts an agent turn.

**Message and media serialization.** The canonical `SerializedContentType` union (`text | image | audio | video | file | contact_card | interaction`), attachment normalization, and the single runtime-card decoder that `@canonmsg/core` re-exports rather than reimplements.

**Behavior policy.** The participation evaluator the stream service runs before dispatching a turn.

**Server-side normalizers.** `readCommunicationRule` resolves a stored communication-policy field to `open | approval-required | closed`, defaulting to `approval-required` rather than widening to `open`. `serializeSelfContext` is the agent-facing projection of a stored self-context. `readModerationStatus` is the single definition of an ejected account. All take plain document-shaped data — the package still performs no I/O.

**Environments.** `CANON_ENVIRONMENT_CONTRACTS` binds `canon-dev-v1` and `canon-prod-v1` to their project and region; `getCanonEnvironmentContract` rejects anything else rather than defaulting.

**Diff redaction.** Approval diffs carry pre-image context into a message every conversation member can read, so secret-shaped paths and tokens are suppressed before send — by the emitting host, and again defensively by the server.

Agent-facing reference: [API contracts](https://canonmail.com/agents/contracts)