v0.1 architecture: seams and surfaces

[thorwhalen]

correspond is a thin channel facade for agents: one data model (conversation references, channel identities, authenticity grades, messages, events, graded capabilities) and one set of verbs (read, listen, send, edit, react, upload, verify) over per-channel adapters. It knows no people: identity stops at what the platform attests, and linking a handle to a person is acquaint's job. liaise will consume it for its channel bindings and outbound messages.

Seam table (decided before the first commit)

#	Seam	v0.1 default (no new dependency)	Replacement you can point at
1	which adapters exist: registry= on the facade functions	xdol.Registry, built lazily from the built-in channel table; an entry registers only when its optional modules import	correspond.testing.FakeChannel (tests, and liaise's offline suite); Discord over discorddol
2	how an adapter reaches its platform: run= (gh, macOS notifiers), http= (ntfy, Telegram), imap= / smtp= (email)	subprocess.run, urllib.request, imaplib / smtplib	the scripted fakes in the tests; githubkit with a GitHub App, imap-tools, aiogram as extras
3	where state lives: cursors= (listen), store= / blobs= (web inbox, Telegram log)	dol files under ~/.local/share/correspond/<kind>/ (CORRESPOND_DATA_DIR overrides the root)	a dict (tests); s3dol for a server's web inbox
4	the last routing rule: classifier= on route	none: bindings, then thread continuity, then metadata decide; otherwise the message is unrouted	liaise's "is this message about subject X?" classifier

Surfaces for v0.1: CLI (cw over correspond.tools) + shipped `correspond` skill + MCP over stdio (py2mcp string refs, [mcp] extra; write tools only with --allow-send). Claude Code channel server and remote MCP/HTTP asked, not built.
NOT seams: per-channel ref grammar, authenticity-grade and error-kind vocabularies, the seven operation names, the built-in channel table format, config file format and env var names, data-root layout, web inbox payload and identity-token format, rate and size defaults (config values), CLI rendering, dry-run plan format

One-command test (the definition of v0.1, fully offline)

python -m correspond.testing send fake:example/demo "hello" --dry-run \
  && python -m correspond.testing read fake:example/demo \
  && python -m correspond.testing ref fake:example/demo \
  && ! python -m correspond.testing react fake:example/demo m1 eyes   # NotSupported: react

correspond.testing runs the ordinary CLI with an in-memory fake channel registered. No plugin loader.

Decisions worth keeping

• Authenticity grades are a vocabulary, not a ranking. forged, claimed, platform, domain, bound, crypto. A policy that accepts platform, bound and crypto for one permission but not domain cannot be expressed as a threshold, so comparing grades with < raises.
• --dry-run contacts nothing and changes nothing. It validates the reference and the draft against the channel's capabilities and limits and shows the plan, with secrets (an ntfy topic) masked.
• Writes return a SendResult for everything a retry or a corrected draft could change (error_kind, retryable, retry_after). Unknown channels, malformed references and unsupported operations raise, and NotSupported names the operation.
• Cursors are committed only after the consumer has taken the event (the generator commits when it is resumed), so delivery is at-least-once; delivery_id is the dedupe key.
• Telegram listening is account-wide (telegram:): getUpdates confirms updates for every chat at once, so narrowing to one chat is routing's job, and every update is logged locally because the Bot API has no history.
• The web inbox collector is a plain ASGI app with no server dependency; the deployment picks the server. No identity is claimed; a valid host-application signature is bound; an invalid or expired signature is refused, not stored.
• No config2py, for startup cost; the data root and config file are resolved with the stdlib (XDG on POSIX, %LOCALAPPDATA% / %APPDATA% on Windows).

Provisional

• Seam 2's non-test replacements (githubkit with a GitHub App, imap-tools, aiogram) are extras the design names; none is built in v0.1.
• The rate limiter in the web inbox is per process and in memory.

[thorwhalen]

Changes to the record above, after the independent review of v0.1 (PR #22):

• Seam 2, corrected. Its non-test replacement is imap-tools behind imap= / smtp=. A GitHub App through githubkit, or Telegram through aiogram, is not a transport swap: the GitHub adapter parses gh api output. Either would be a second adapter for its channel, registered at seam 1.
• The dry-run promise, sharpened. A dry run reads only the environment and the config file. A value kept in the Keychain or on a remote host is looked up when sending, and the plan says where. A test dry-runs every write of every built-in channel with subprocesses, the Keychain, HTTP and stores all refusing.
• Web inbox. trusted_proxies (how many reverse proxies stand in front) replaces trust_forwarded: the rate-limited address is read that many hops from the right of X-Forwarded-For, never from the entries a client wrote. Several sites on one collector need one secret each (CORRESPOND_WEBINBOX_SECRET_<SITE>), so no site's server can sign identities for another.
• Routing. Capabilities.native_fields names the fields a channel's messages carry, and check_binding() reports, when bindings are loaded, a binding that could never match (an unknown channel, or a condition such as ?label= where GitHub messages carry labels).

The seams themselves and the NOT-seams line are unchanged; the proxy count and per-site secrets are configuration values.