State and credential contracts; chat_poll() stops returning $client

[TroyHernandez]

Nine verbs, and phase 1f.

corteza's remaining 15 direct mx.* calls were not stragglers of one job. They were two jobs the contract had no shape for, which is what the design in DESIGN.md (merged in #9) worked out. This implements both.

State: chat_channels, chat_history, chat_pending, chat_mark_read

chat_poll() answers "what changed since my cursor". A process that just started has no useful cursor and needs "what is true now".

chat_pending() is a separate verb rather than a mode of chat_poll(). Overloading the cursor would make "start from nothing" and "tell me what is standing" the same call, and a client that asked for pending invitations and thereby reset its read position would replay every channel it is in. An invitation is standing state — which the contract already conceded when chat_invite was given no timestamp.

chat_history() returns oldest-first whatever direction the platform paged in. Matrix and Slack both hand back newest-first and every consumer flips it. One flip in the adapter beats one per consumer, and a reversed transcript reads plausibly enough that nothing errors.

Credentials: chat_matrix_config, chat_config_save, chat_matrix_configure, chat_relogin, chat_set_identity

chat_config keeps the application's own fields — corteza stores its bots list and operator policy in the same file — and carries app/path as attributes rather than fields, so neither is written back into the file as though it were a credential. print() shows field names and never values.

1f

chat_set_identity() is what unblocked it. The Matrix rename is an authenticated call that can rotate the access token underneath the caller, so a consumer that made it had to notice the rotation and get the new token back into its client — which it did through the file they happened to share. Two rotation paths, two owners, one file. Behind the contract the rotation lands in the client that performed it.

So chat_poll() no longer returns $client. The cursor still reports the post-sync token; the refreshed credentials live on the client.

A hole the new verbs exposed

Every mx.api-backed method passed mx_client_session(client$env$mx) straight into its seam, and R made that a promise. No seam double reads its session argument, so the session was never actually built — the test fixture had no token field in it at all and nothing noticed. The methods force it now, which is what production does the instant the real mx.api function touches it.

Verification

815/815. 13 mutations across the new surface, all caught.

One survived and was a real bug: cutting the config reload out of chat_set_identity() left the suite green. Chasing that found the implementation contradicted its own comment — it claimed to reload unconditionally but returned early when the rename threw. A relogin persists a refreshed token before retrying, so a retry that then fails has still rotated it: the live token is on disk and the client holds the rejected one, and nothing relogins on a send.

corteza's consumer is cornball-ai/corteza#173.

[TroyHernandez]

Fixed, and you were right about the shape of the fix. chat_history() now pages by an opaque cursor and returns one:

chat_history(client, channel, limit = 50L, cursor = NULL)
# -> list(messages = <chat_message, oldest first>, cursor = <opaque, NULL at the start of the channel>)

Took option 1. There is no id that means the same thing on both reference transports — Matrix pages by end, Slack by next_cursor — so translation would have been per-adapter guesswork dressed as a contract. This is what chat_poll() already does with its cursor, and consistency there is worth more than message ids being nicer to look at.

Three things the fix turned up that the original would have got wrong even with translation bolted on:

The stop signal is not an empty page. Matrix omits end at the start of a room, and that is the only reliable "nothing behind this". A window can be all state events — joins, topic changes — and still have conversation behind it, so a consumer that stopped on an empty messages would truncate the backfill silently. Tested both directions: empty chunk with an end keeps going, non-empty chunk with no end stops.

Slack sends "" rather than omitting next_cursor at the end of a channel, and handing "" back to conversations.history is an error rather than a no-op. Normalized to NULL.

Loopback pages by a count, deliberately. It is what a new adapter gets read as an example, and a reference implementation that paged by message id would teach a contract the reference transport cannot honour.

corteza reads $messages and ignores $cursor — backfill wants the tail of the conversation, not the room's whole history, so limit is the window and paging further back would grow a restart's context without bound. That is now stated at the call site rather than being implied by the code stopping there.

846/846. 8 mutations on the pagination path, all caught.

One of those mutations found a defect in my own test rather than the code: cutting the loopback cursor out made the page-walk loop spin forever instead of failing. A hung suite is a worse report than a wrong one — no line number, no diff, just a runner that never finishes. Bounded, with expect_null(cursor) after it so a walk that did not terminate on its own is an assertion rather than a timeout.

chat.api 0.0.1.17, corteza floor moved to match. Both branches pushed.