[alex-clickhouse]

What

• The hosted channel contract mirror knows generic sources. Every provider other than
  github, github_repos and email is generic: its records carry a schema and data, a
  JSON object that the provider defines, and a subscription to it carries settings, the
  record schemas that Nerve reads, and rules on the data. Nerve keeps every member of the
  data, also the members that it does not know. Conversation kind item names a tracked item.
• A shared module checks and writes the JSON data of generic sources: the bounds (8 levels,
  32 KiB of data and 8 KiB of settings in canonical form), the canonical form (RFC 8785) and
  JSON Pointers.
• DataRule in the inbox guardrail applies the rules of a generic source to the record data
  with the same semantics as the channel gateway: a deny rule drops a record when a value at its
  path matches, an allow rule drops a record without a matching value.
• HostedSource drains the hosted buffer of any generic provider; the record's metadata holds
  its schema and its data. The hosted GitHub source keeps its own records.
• sync.linear: enabled, mode (hosted only; poll refuses to load), events, inbox,
  include_bots, drop_own_actions, rules, schedule, condense, batch_size. While it is
  on, Nerve subscribes to provider linear with the settings that differ from the defaults, the
  schema linear.issue_event/1, and the rules, and the source:linear runner drains the
  records with the rules as guardrail. nerve doctor reports the source.
• The poll tools show the schema and the whole data of a generic record to the agent as JSON,
  so the agent reads the MCP catalog server that a Linear record names.
• The runner's drop log names only the record ID and the rule that dropped it, never a value
  or a summary of the dropped record, for every source.
• Sources page: the record schema picks the view: a Linear card (identifier, title, event,
  state, actor, link) for linear.issue_event/1, and a JSON view of the record data for any
  other schema.
• Docs: sources (Linear, rules of generic hosted sources), config keys and restart table, cron,
  the example config, and the TOOLS.md templates.

Why

The channel gateway can poll Linear for an agent with the agent's Linear connector (its
credential, project scope and GitHub filter) and deliver the records while Nerve is stopped. The
contract for such a source is generic: a strict envelope and provider-owned JSON data with a
versioned schema, so that a new provider or record type needs no contract change in Nerve.

How

• Decoding keeps data and settings as parsed JSON, tells an absent member from null, and
  refuses what the gateway refuses: repeated member names, NaN, lone surrogates, numbers
  outside binary64, too deep or too large objects. A member with its zero value counts as absent,
  except settings and data.
• A subscription is generic only when it names a schema; Nerve sends schemas on every generic
  subscription that it builds. The frames of GitHub, the repository watch and email do not
  change.
• Rules that the gateway would refuse refuse to load. A subscription is never sent without its
  rules: if the subscriptions frame is too large, it goes first without the GitHub filter
  patterns, then without the subscriptions that carry rules. The gateway then stores nothing
  for them, the stream logs an error, and nerve doctor reports it.
• Switching Linear on needs a restart (the consumer of the gateway's records is built at
  startup); switching it off follows a reload.

Rollout: the gateway must know generic sources before an agent switches Linear on; an older
gateway closes the stream on settings, schemas or rules. With the default config Nerve
sends the same frames as before.

The Linear card is based on a Linear renderer by Frank Rosner.

Tests

• Byte-exact copies of the channel contract's synthetic vectors: canonical form, bounds, record
  and subscription verdicts, rule evaluation, the generic subscriptions frame, and the canonical
  data in the digest projection.
• A byte-exact copy of the gateway's schema file of linear.issue_event/1 validates every Linear
  fixture, backend and frontend; the fixtures follow the gateway's ID rules, and a changed event
  replaces the stored copy.
• Linear settings, subscription, buffer, drain, guardrail, the frame limit at its boundary, end
  to end over real streams with the fake gateway, the agent's view, and nerve doctor.
• Full backend suite: 9206 passed, 39 skipped. Frontend: build, 1923 tests passed.

🤖 Generated with Claude Code

[nerveai]

Nerve PR review · ✅ Ready to merge

This PR adds the generic side of the hosted channel contract: records carry provider-defined JSON data with a schema, and subscriptions carry settings/schemas/rules. Linear is the first generic source (sync.linear, hosted only). The approach fits the architecture. Linear reuses the hosted buffer, the push-fed runner, the guardrail, consumer cursors and messages gates, and HostedGitHubSource now builds on a shared HostedSource. GitHub, repository-watch and email frames are unchanged. Parity with the gateway rests on byte-exact copies of its vectors. A subscription with rules is left out of the frame rather than sent without its rules, and both the log and nerve doctor report it. New gateway providers then need no change to Nerve's contract.

Completeness: tests cover the contract vectors, Linear end to end over the fake gateway, the frame-limit boundary and doctor. Also covered: docs, example config, the restart-table row and the TOOLS.md templates. No migration is needed.

Worth considering:

• Sources: start consumer cursors before a source's first run #677 should land with this PR or before it. Otherwise existing inbox consumers miss the first Linear records: consumer_has_unread skips a source with no cursor (nerve/db/sources.py:456-471), and the first poll starts at the newest row (:343-354).
• Draft Linear source: issue notifications for agents, writes through Linear's MCP #596 also defines sync.linear, as a polled source, and conflicts with this PR in 12 files. It would help to say whether this PR supersedes Linear source: issue notifications for agents, writes through Linear's MCP #596, or whether a later mode: poll must emit linear.issue_event/1 records.

_{Checked: full suite in an offline sandbox at 190f146 (3 chunks): 9193 passed, 39 skipped; test_slack_integration.py excluded (hangs offline on main too); web sandbox: build + 1923 tests passed; read contract model/wire, source_json, filters, hosted sources, stream fallback, config, doctor, renderers · automated review by nerveai — mention @nerveai to ask a follow-up.}