# Station connector protocol and SDK

The project-local Rust SDK is transport-only. Its authoritative source is copied
to `.chasing-mastery/toolchain/cm-station-connector-sdk/src/lib.rs`.

## Lifecycle

1. Read `host.initialize`, echo its exact `expectedIdentity` in one
   `connector.hello`, and retain its exact `observationProtocols` using protocol
   version 1. Station has already resolved the reviewed schema bytes into these
   identities; the sidecar never hashes a schema at runtime.
2. Read `host.start`.
3. Emit `connector.status` as `starting`, then `ready`.
4. Emit a revisioned `connector.sources` inventory and `connector.health`.
5. Emit declared `connector.observation` frames carrying one exact supplied
   type/version/schema-digest identity. Wait for the matching
   `host.observation.receipt` before considering delivery committed.
6. At any time after start, answer `host.ping` with the exact nonce in
   `connector.pong`.
7. On `host.stop`, emit `stopping`, then `stopped`, and exit successfully.

Every frame is one strict JSON object followed by `\n`, bounded by the runtime's
`maximumMessageBytes`. Unknown fields, changed session IDs, undeclared sources
or exact observation protocols, invalid lifecycle order, unsolicited pongs,
late events, and oversized frames fail closed.

A source inventory revision is immutable. Persist enough local state to replay
the exact document, including `observedAt`, after a connector process restart.
When the discovered source set or metadata changes, emit a strictly higher
revision. Reusing a revision with changed content or moving backwards is a
protocol error.

## Authority

`grantedResources` is the complete local authority visible to the connector.
The current authoring Lab requires it to be empty. Configuration is inert JSON;
it is not permission. The SDK provides no HTTP client, filesystem handle,
credential store, account session, database, OBS connection, or activity host.

## Receipts

- `spooled`: Station durably accepted a new source event.
- `duplicate`: the exact stable source event was already accepted.
- `tested`: a testing host validated the event without production persistence.
- `rejected`: the sink or Practice Mode contract rejected the event; inspect the
  bounded diagnostic and fix the contract.

Never infer acceptance merely because the observation was written to stdout.
