cock, maybe balls too idk

design.md

Smalltalk Conversational Protocol

Abstract

Smalltalk is a conversational protocol for interaction between automated systems and human operators. It was designed to allow for structured but natural interaction while remaining lightweight, without the need to rely on natural language processing.

What Smalltalk is

Smalltalk is in essence a transport layer protocol. It handles peer discovery and addressing, conversation multiplexing and common pitfalls like conversation channel handover and character limits automatically. Smalltalk is packet based, but it builds further on this concept by providing a composable suit of atomic instructions called directives to allow for simple but flexible application specific protocol design.

What Smalltalk is not

Smalltalk is not an application layer protocol. Smalltalk is only concerned with the structure and syntax of the conversation and makes zero assumptions about the structure or content of the underlying directives (excluding builtin directives used to control the channel).

General Conventions

• Casing for directives is ignored
• Only respond to messages which consist exclusively of directives understood by the receiver
• Only respond to messages which are either directed at the receiver or are brodcast/anycast messages

Concepts

Command

• Some task which may be executed and its result retrieved
• Interaction is done via messages

Message

• Single packet of conversation
• Contains one or multiple directives

Conversation

• Consists of multiple messages
• Identified through message replies

Directive

• Atomic instruction
• Separated by an empty line
• Ends in an optional terminator

Terminator

• May be any of the following: ., !, ?
• Is optional, if absent . is assumed
• Meaning is directive specific

Default Directives

receiver directive

The receiver directive indicates the intended recipient, or group of recipients of a conversation. Its use is optional but restricted to the start of a new conversation.

• may be a role or user mention
• may only appear once at the start of a conversation, as the first directive in the message
• subsequent conversation tracking is done through replies
• absence indicates broadcast/anycast

chunked message directive

This directive is used to split the directives of one command across multiple messages. This may be useful in the case that the directives required for a command do not fit in a single message. When receiving a chunked message directive, the recipient should wait until a message is received which does not contain a chunked message directive before forwarding the directives to the application layer for processing. If no such message is received, the behavior is undefined. It is advised to implement a timeout in case the message can not be delivered.

Special care needs to be taken when receiving an abort directive as a follow up to a chunked message directive. Even if valid chunked messages were already received, the recipient should drop all previous directives recorded for this command that have not yet been processed by the application.

• consists of only the literal also
• may only appear once per message as the last directive
• indicates additional directives following in a subsequent message
• next message is indicated by self reply

switch channel directive

Directive used to switch the transport to a different channel. This may be useful in cases where conversations need to persist across channel, server or even protocol boundaries.

• consists of the literal lets take this to followed by a channel mention or the literal dms
• must be the only directive in the message
• must be sent in reply to a message, may not be used to initialize a new conversation
• sender must retransmit their original message in the designated channel using a receiver directive followed by a referral directive

referral directive

See also "switch channel directive".

• consists of the literal continuing from followed by a message ID
• used to track ongoing conversations across channel boundaries
• see also switch channel directive

switch protocol directive

This directive provides a way of upgrading the conversation to a different protocol in band. Support of additional protocols is not covered by the specification and is application defined.

• consists of the literal requesting protocol change: followed by a protocol name
• receiver must respond with either protocol change accepted or protocol change rejected
• must be the last directive in the message
• must be sent in reply to a message, may not be used to initialize a new conversation
• if protocol change was mutually accepted the conversation continues according to the selected protocol

code block directive

This directive is provided for convenience, as well as to enable other builtin directives such as the error directive described below.

• consists of a markdown codeblock containing arbitrary data, entire block is read as single directive
• meaning is command specific

error directive

Directive used to indicate an error, usually one which occured on the transport layer, but may also be used by application layer protocols running on top of smalltalk.

• consists of the literal there was a problem: followed by a description of the error
• must be the first directive in the message
• must be sent in reply to a message, may not be used to initialize a new conversation
• may only be followed by at most one code block directive describing the error in more detail

abort directive

This directive can be used to immediately cancel a command in flight by either party. It is sent and received asynchronously. If the receiver encounters an abort directive, it should immediately stop processing any other messages connected to this conversation and free any resources associated with it.

• consists of the literal nevermind
• will immediately terminate the conversation. Future replies to it are considered invalid
• must be the only directive in the message
• must be sent in reply to a message, may not be used to initialize a new conversation