Channel pushes an ask question to a human on a specific
medium (Telegram, Slack, SMS, …) and bridges the human’s reply back into the
interactions store by forwarding it to the delivery’s public callback_url.
Channels are registered on the app handle (tai42_app.channels) by channel
plugins and looked up by name when ask is called with channel=....
Delivery either returns a SendOutcome (success) or raises
ChannelDeliveryError (any failure) — never a bool.
A channel also sends fire-and-forget notifications: notify pushes one
ChannelNotification to a human with no interaction, no ticket, and no
reply path, under the same loud-failure rule; it returns a SendOutcome
naming the identity and address it sent from and to and the per-message ids the
medium assigned the send (empty when the medium exposes none), never a bool.
Before either send, resolve_address gives the ChannelAddress the
channel would send to, or raises ChannelAddressError.
When the platform takes a delivered question down by a path that is not the channel’s own
forwarded reply, it hands the channel a ChannelWithdrawal through the channel’s
optional withdraw member, so the channel releases what it kept for that question.
A channel whose medium limits free-form replies to a window after the client’s last message
reports that window as a ReplyWindow through its optional reply_window member.
NOTIFICATION_FOOTER_MAX_CHARS
tai42_contract.channels.options.NOTIFICATION_FOOTER_MAX_CHARS
NOTIFICATION_SECTIONS_MAX
tai42_contract.channels.options.NOTIFICATION_SECTIONS_MAX
OPTION_ID_MAX_CHARS
tai42_contract.channels.options.OPTION_ID_MAX_CHARS
AnswerForwardError
tai42_contract.channels.errors.AnswerForwardError
AppChannels.handle_inbound_answer WITHOUT releasing the
correlation, so the channel’s transport-level retry (the provider’s webhook
redelivery) re-runs the ladder and the answer is never silently lost. A channel
lets it propagate out of its inbound webhook so the provider redelivers.
Channel
tai42_contract.channels.protocol.Channel
tai42_app.channels.register); ask resolves it by name and calls
deliver after the interaction is persisted and its callback ticket is
minted. A channel never reaches the interactions store directly: the
human’s reply travels back through the delivery’s public callback_url.
A channel MAY advertise richer support with seven OPTIONAL, class-level
capability flags — supports_media_notifications,
supports_template_notifications, supports_interactive_notifications,
supports_location_notifications, supports_form_notifications (all
five for notify), supports_form_delivery and
supports_form_reaction (both for deliver) — set
as plain class
attributes. They are a documented convention, NOT Protocol members: a
channel that supports the richer form sets the matching attribute to
True; a channel that omits it advertises no support (absent =
False). Because they are not part of the Protocol, a text-only channel
that declares none is still a valid Channel (both structurally and under
runtime isinstance). The ask/notify helpers read them defensively with
getattr(channel, "<flag>", False) and refuse the matching richer send to
a channel that does not advertise the flag: notify_user refuses a media,
template, options, sections, location or schema notification, and the
ask helper
refuses a form delivery, to a channel without the flag — so a channel
that reads only the plain fields can never silently drop the extra content.
A channel that does not advertise supports_form_delivery never receives
a form delivery, and one that does not advertise
supports_form_notifications never receives a schema notification. A
channel that advertises supports_form_notifications MUST, when a form
notification carries a form_tag, carry that opaque per-send tag with the
form on its own medium (never into the published form artefact) and hand it
back on the participant’s submission as accept(form_tag=...) — the tag
rides the form’s gate, so it needs no capability flag of its own.
supports_form_reaction is the delivery-side flag for a REACTING form (one
whose ask names a reaction_tool and carries reactions triggers): the
ask helper, having already confirmed supports_form_delivery, refuses a
reacting form to a channel that does not ALSO advertise
supports_form_reaction — so a form that reacts while open is never
delivered to a medium that cannot route its triggers back (it is refused
loudly at the ask door, never silently rendered inert). A non-reacting form
needs only supports_form_delivery.
A form channel MAY also declare one OPTIONAL method, validate_form_schema,
following the same convention as the capability flags — a documented member,
NOT a Protocol method, so declaring it never tightens the runtime structural
check. ask reads it defensively with
getattr(channel, "validate_form_schema", None) right after the generic
channel-deliverable subset check and, when present, calls
channel.validate_form_schema(schema, question) at ask-time, BEFORE any
state is written. It enforces the channel’s OWN ask-time-knowable form limits
(reserved property names, per-medium Block Kit / Flow caps, question-text caps)
over the schema AND the question text — limits the generic subset does not
know — raising ValueError naming the offending property/limit on a
violation, so a question or schema the channel could never render is refused up
front instead of persisting a question that only fails at delivery. A channel
that omits it advertises no extra ask-time limits; its delivery path still
refuses an unrenderable question or schema (a permanent
ChannelInputError). The SAME hook is reused for a form notification:
the notify helper calls channel.validate_form_schema(schema, message) with
the notification’s message as the question argument before the send, so
one declared method covers both the ask and the notify form surfaces. A
conversation’s send admission runs the same hook once per form part, with the
part’s final message as the question, before any part of the reply is sent.
A channel that advertises supports_template_notifications MAY also declare one OPTIONAL
method, validate_template, following the same documented-member convention (read
defensively with getattr(channel, "validate_template", None), NOT a Protocol method, so
declaring it never tightens the runtime structural check). The send helpers call
channel.validate_template(template) right after the capability gate, BEFORE the send: it
parses the template’s OPAQUE parameters against the channel’s OWN template-parameter schema
and raises ValueError on a shape the channel could never map — so a template the channel
could never render is refused up front instead of failing at delivery. A channel that omits the
hook advertises no ask-time parameter check; its notify still refuses an unmappable template
at send time (a permanent ChannelInputError). A conversation’s send admission runs the
same hook once per template part, before any part of the reply is sent. The platform never
looks inside parameters itself; the declaring channel owns the shape end to end.
A channel MAY also declare the OPTIONAL outbound message-length cap it splits a long answer
against — an OPTIONAL ClassVar max_message_chars: int giving the medium’s own per-message
character limit, read defensively with getattr(channel, "max_message_chars", None) (the
same documented-member convention, NOT a Protocol member). The conversation-delivery machine
resolves a routed channel’s split width as the operator override
(CONVERSATIONS_MAX_MESSAGE_CHARS) when set, else this declared cap; a channel that declares
neither (and has no override) is a loud config error at send, never a silent unbounded or
truncated send.
A channel MAY also declare an OPTIONAL ClassVar identity_hint: str — one plain sentence
telling an operator what to enter as a conversation route’s our_identity on this channel
(which address of the medium clients message). The same documented-member convention, NOT a
Protocol member, read with getattr(channel, "identity_hint", None). Absent means the
channel offers no hint. A declared value must be a non-blank string; registering a channel
that declares anything else is refused.
A channel MAY also declare the OPTIONAL “working-on-it” (typing) signal — the
same documented-member convention as validate_form_schema
and the capability flags, NOT Protocol members (so declaring them never tightens
the runtime structural check and a channel that omits them stays a valid
Channel). It is two members. An OPTIONAL ClassVar working_signal_expiry_seconds: float | None gives the vendor indicator’s lifetime
in seconds; None (or absent) means the channel emits no working signal and the
caller’s refresh loop never starts, read defensively with getattr(channel, "working_signal_expiry_seconds", None). An OPTIONAL method async def signal_working(self, *, recipient: str, sender_identity: str | None = None, provider_message_id: str | None = None, active: bool = True) -> None asserts
(active=True) or clears (active=False) the working-on-it indicator to
recipient (the participant address, as notify addresses one), optionally
from sender_identity (None = channel default). provider_message_id is the
id of the newest inbound message from the recipient that this work answers, as the
channel reported it, or None when there is none; a medium whose API ties the
indicator to a specific inbound message references it. A channel whose indicator
self-expires implements only the assert and treats active=False as a no-op; a
channel that emits explicit frames sends a start frame on True and a stop frame
on False. It is fire-and-forget, carries no reply, and raises
ChannelDeliveryError ONLY on a genuine send failure the caller logs, never
for a transient it can ignore.
A channel that keeps something per delivered question MAY also declare one OPTIONAL
method, async def withdraw(self, withdrawal: ChannelWithdrawal) -> None — the same
documented-member convention, NOT a Protocol method, read defensively with
getattr(channel, "withdraw", None). The platform calls it when it takes a delivered
question down by a path that is not the channel’s own forwarded reply (a cancel, an erase
of the question’s thread, route or person, an expiry). The channel releases EVERYTHING it
reserved or cached for withdrawal.interaction_id at delivery — the per-address pending
correlation and any per-interaction sidecar — resolving the address from
withdrawal.recipient exactly as its deliver resolved delivery.recipient. It
MUST compare the stored interaction id and never drop a hold another ask now has on the
same address. It MUST be idempotent and a no-op when nothing is held (expired, already
forwarded, never reserved — a link-answered format reserves nothing). It touches no
message on the medium: the question already sent stays where it is, and a late reply to
it takes the inbound answer ladder’s no-longer-pending path. It raises
ChannelDeliveryError (retryable=True for a transient store fault) only on a
fault, never for “nothing to release”. A channel that keeps nothing withdrawable omits the
member (absent = nothing to release).
A channel whose medium allows a free-form reply only within a window after the client’s
last message MAY also declare one OPTIONAL method, async def reply_window(self, *, recipient: str, sender_identity: str | None = None) -> ReplyWindow — the same
documented-member convention, NOT a Protocol method, read defensively with
getattr(channel, "reply_window", None). It reports the window for recipient (the
client address, as deliver addresses one) and sender_identity (our identity on the
medium; None = the channel default, resolved exactly as deliver resolves it): a
ReplyWindow that is open with its closes_at, closed, or none for a
pair the medium keeps no window for. It reads state only and sends nothing. It raises on a
fault (an unreachable store, a corrupt stored value, an unaddressable pair), never answers a
guessed state. A channel that omits the member has no reply window: the platform reports
none. The medium’s own rejection of a send outside its window stays the final check.
Members
resolve_address
tai42_contract.channels.protocol.Channel.resolve_address
recipient and sender_identity are the send’s own values
(None = the channel’s default), resolved exactly as notify / deliver resolve
them. The identity is the one the send goes from, and a completed send’s
SendOutcome reports the same identity. The address may not be the canonical
one: a medium that resolves a handle only when it sends returns the handle here. The
platform uses this address only to place a send that never reported an outcome (it
raised, it timed out, it was cancelled, or the process stopped); a completed send is
placed by its SendOutcome. Raises ChannelAddressError when the target
cannot be resolved (a recipient off the operator allowlist, no recipient and no
configured default).
Parameters
deliver
tai42_contract.channels.protocol.Channel.deliver
delivery to the medium, or raise ChannelDeliveryError.
Send the question to the resolved recipient — delivery.recipient
when set (after checking it against the plugin’s operator allowlist),
else the plugin’s operator-configured default — and arrange for
the reply to reach delivery.callback_url — either a tappable link
carrying the URL, or an inbound-route correlation the plugin stores.
Any delivery failure — an unreachable or rejecting medium, a recipient
outside the operator allowlist, a required credential or recipient not
configured, a bad send response — raises
ChannelDeliveryError; a return is the only success signal and
yields the SendOutcome of the question’s messages (the identity
and participant address it went from and to, and the per-message ids the
medium assigned, empty when it exposes none). One send attempt only:
retrying is the caller’s decision, never
an implicit loop here — the raised error’s retryable and
retry_after drive that decision, so a fault the medium can recover
from is classified rather than blind-retried here. The dispatcher never
hands a delivery whose timeout_at has passed.
Parameters
notify
tai42_contract.channels.protocol.Channel.notify
ChannelDeliveryError.
No interaction, no ticket, no callback, no reply. Any delivery failure raises
ChannelDeliveryError; a permanent refusal of the input’s shape or
content (an input the medium cannot render BY NATURE) raises
ChannelInputError instead — retrying it cannot succeed. A return means
the medium ACCEPTED the message —
not that a human saw it — and yields the SendOutcome: the identity and
participant address the message went from and to, and the per-message ids the
medium assigned this send (several when the medium splits a long message, empty
when it exposes no id), which later correlate an out-of-band delivery receipt or a
quote back to this send. One send attempt only, no retry. A channel that cannot
notify raises NotImplementedError.
Parameters
ChannelAddress
tai42_contract.channels.delivery.ChannelAddress
our_identity is the identity the send goes from; a completed send’s
SendOutcome reports the same identity. address may not be the canonical
one: a medium that resolves a handle only when it sends gives the handle here.
Attributes
ChannelAddressError
tai42_contract.channels.errors.ChannelAddressError
Channel.resolve_address when the send’s target cannot be resolved.
A caller-supplied recipient off the channel’s operator allowlist, or no recipient and no
configured default: the send is refused before anything is recorded or sent. It is a
ChannelDeliveryError that is never retryable, so every caller that handles a
refused send handles this one the same way.
ChannelDelivery
tai42_contract.channels.delivery.ChannelDelivery
callback_url is the public /api/interactions/callback/{ticket}
answer sink; the channel arranges for the human’s reply to reach it.
recipient is the OPTIONAL caller-requested address (chat id, phone
number, …): the channel plugin validates it against its operator-set
allowlist and refuses to send to an unlisted address; when omitted the
plugin sends to its operator-configured default recipient. It is an
address only, never a secret or credential.
media is OPTIONAL display media the channel renders alongside the
question (reusing MediaItem, the same shape and list-level caps the
ask REQUEST carries); a present list is non-empty. It is a pure enhancement,
NOT structure: a channel that renders only text simply ignores it and shows
the question, so it rides no capability flag and is never refused for a
channel that cannot render it. options is REQUIRED for select (the
answer set) and OPTIONAL for text as SUGGESTED REPLIES — a tapped option
submits its own text as the free-text answer; every other format carries none.
Attributes
ChannelDeliveryError
tai42_contract.channels.errors.ChannelDeliveryError
Channel when delivering a question fails.
Every failure mode — an unreachable medium API, a rejected send, a missing
credential, a misconfigured recipient — raises this single typed error.
deliver NEVER returns a bool and NEVER silently drops a message: an
undeliverable question is a loud failure, so the only success signal is a
plain return.
retryable classifies the failure for the caller’s retry decision: True
means transient (a medium 5xx, a rate limit, a transport fault or timeout)
and a fresh attempt may land. It defaults to False — a rejected recipient, a
bad credential, and any unrecognised fault fail on the first try rather than
being blind-retried. retry_after is the seconds the medium asked the
caller to wait (an HTTP Retry-After, say); meaningful only when
retryable is True.
Attributes
ChannelInputError
tai42_contract.channels.errors.ChannelInputError
data: image URL to a channel that sends only public https sources.
Retrying the same input can never succeed, so this is distinct from
ChannelDeliveryError (a delivery failure the caller may retry): the
operation door maps it to the client-error (400) class, never the retryable
503 a transient delivery failure earns.
ChannelNotification
tai42_contract.channels.notification.ChannelNotification
callback_url and
no deadline: the channel sends the message and nothing travels back.
recipient is the OPTIONAL caller-requested address (chat id, phone
number, …): the channel plugin validates it against its operator-set
allowlist and refuses to send to an unlisted address; when omitted the
plugin sends to its operator-configured default recipient. It is an
address only, never a secret or credential.
sender_identity is the OPTIONAL address to send FROM when the channel fronts
several operator identities: an internal routing control set by the sending side,
never caller-supplied, and an address only — never a secret.
message is the human-readable text, non-blank BY DEFAULT — EXCEPT it may be the empty
string "" for a CONTENT-ONLY send: a caption-less bubble that is just media or a
location, with no text carrier. The admissible states are “message non-blank” OR
“blank message WITH non-empty media OR a location”; a blank message with no
such content has nothing to deliver and is refused. (message stays REQUIRED — a
content-only sender passes "" explicitly — because every caller constructs it in code
with the text in hand.) An interactive surface (options, sections or schema)
REQUIRES a non-blank message — a choice or a form needs a prompt — so a content-only
send carries none; a template likewise rides a non-blank message.
The OPTIONAL richer-send forms reuse the same message as the human-readable
equivalent. media is display media the channel sends alongside the message (reusing
MediaItem, image/document/video/audio/link); a present list is non-empty.
location is a shared geographic point (LocationElement). template sends a
pre-approved ChannelTemplate for out-of-window delivery. options is a flat
list of tappable Option entries — a ReplyOption (a tap submits its text
as a visitor message) or a LinkOption (a tap opens its url) — at most
NOTIFICATION_OPTIONS_MAX. sections is the sectioned alternative: titled
OptionSection groups of reply rows (rows summed across sections stay within
NOTIFICATION_OPTIONS_MAX). header is a single display-media header and footer a
short trailing line, each composing an interactive message (they REQUIRE options or
sections).
The composition rules (check_interactive_composition): options XOR
sections (one choice surface); schema excludes both (one interactive surface); a
template is the standalone out-of-window send, MUTUALLY EXCLUSIVE with every other
content and interactive field; options/sections and schema MAY each combine
with media and location. A channel that does not advertise the matching capability
flag (supports_media_notifications / supports_location_notifications /
supports_template_notifications / supports_interactive_notifications /
supports_form_notifications, the OPTIONAL class-attribute convention documented on
Channel) never receives the matching field.
schema is the form answer schema for an ASK-LESS FORM: the channel renders
message as the form’s prompt and schema as the fillable form, and the
participant’s submission enters the conversation as a participant message — no interaction,
no ticket, no callback, the same inbound path a tapped option takes. A present
schema is a non-empty dict; its deep shape is the sender’s shared
channel-deliverable subset walk (the same split ChannelDelivery keeps),
never re-checked here. schema REQUIRES a non-blank message — a form needs
a prompt — and is MUTUALLY EXCLUSIVE with template and with options (one
message carries ONE interactive surface); it MAY combine with media. It rides
the supports_form_notifications capability flag, and a form channel’s OPTIONAL
validate_form_schema(schema, question) hook (see Channel) is reused
at notify time with this message as the question argument, so the
channel’s own form limits refuse an unrenderable form before the send. A conversation
part’s delivery notification is held to the same hook before its reply’s first chunk,
with this message as the question. Some channels
also constrain WHEN a form may be sent: WhatsApp delivers a notify-form only inside
the provider’s customer-service window, and an out-of-window send fails loudly at the
channel — never silently downgraded.
Attributes
ChannelTemplate
tai42_contract.channels.templates.ChannelTemplate
name in an approved language locale — both
required and non-blank.
parameters is the template’s runtime arguments as an OPAQUE object: the platform
threads it UNOPENED (never looking inside it), and the channel that declares the
supports_template_notifications capability owns its shape — it validates parameters
against its OWN template-parameter schema through its OPTIONAL validate_template hook
(see Channel) and maps it to its own send API in its own
code. A template with no runtime arguments carries no parameters; a present
parameters is a non-empty dict.
Attributes
ChannelWithdrawal
tai42_contract.channels.withdrawal.ChannelWithdrawal
interaction_id and recipient are the two facts the channel reserved under at
delivery: the id of the question and the address the ChannelDelivery carried
(None when the delivery named none, so the channel resolves its own default exactly
as its deliver did).
Attributes
Correlation
tai42_contract.channels.correlation.Correlation
ask is delivered on a medium whose reply arrives as a fresh
inbound message (not a tap on a signed link), the channel stores this record
against a channel-computed correlation key and, when the participant’s next reply
lands on that key, forwards it to callback_url (the delivery’s public
answer sink). interaction_id identifies the parked ask (carried into
operator alerts, never re-derived); ttl_deadline is the tz-aware instant
past which the pending ask is stale and the key may be reclaimed. One pending
ask per address: a channel reserves the key before delivering and drops it
once the reply is forwarded, withdrawn or expired.
Attributes
CorrelationStore
tai42_contract.channels.correlation.CorrelationStore
ask questions whose replies arrive as fresh
inbound messages keeps a Correlation per waiting address so the
participant’s next reply resolves the right parked ask. This port is the minimal
set/get/release surface over that store; the LADDER that interprets a
forwarded answer’s outcome (forward, retry-in-place, bridge) lives in core and
reads this port — it is not the store’s concern.
key is an OPAQUE channel-computed correlation key: it absorbs the divergent
per-channel shapes — a Twilio number pair, a Slack thread_ts, a Telegram
ForceReply message_id, a WhatsApp address — collapsing them to one string
the store never interprets. A channel with no correlated replies (a link-tap
or an external-answer medium) simply does not provide a store.
This is a STANDALONE optional port, NOT an extension of Channel: a
channel implements it separately (or not at all), and the core handler is
handed one explicitly rather than reaching it off the channel instance.
Members
set_correlation
tai42_contract.channels.correlation.CorrelationStore.set_correlation
key for entry with a ttl_seconds expiry, NX.
Returns True when the key was free and is now held; False when the key is
already held — the one-pending-per-address guarantee, so a second parked
ask for the same address never silently overwrites the first. ttl_seconds
bounds how long the reservation survives without a reply.
Parameters
get_correlation
tai42_contract.channels.correlation.CorrelationStore.get_correlation
key, or None when none is held.
A non-destructive peek: it neither drops nor refreshes the reservation, so
the handler can inspect the pending ask and decide the outcome before
releasing.
Parameters
release_correlation
tai42_contract.channels.correlation.CorrelationStore.release_correlation
key, idempotently.
A no-op when the key is already free (expired, forwarded, or never held),
so releasing twice — or racing an expiry — is never an error.
Parameters
InboundAnswerOutcome
tai42_contract.channels.inbound.InboundAnswerOutcome
InboundAnswerResult
tai42_contract.channels.inbound.InboundAnswerResult
outcome is the ladder’s decision. retry_reason and retry_field carry the
door’s OWN (already length-bounded) rejection message and the failing field name so a
channel that OWNS its correction surface (a re-opened WhatsApp Flow, a Slack modal’s
inline Block-Kit error) can render the door’s SPECIFIC message rather than a generic
line. Both are populated when the door rejected the answer’s content — on
InboundAnswerOutcome.RETRY_KEPT (either notice_owner variant) and on a
hard-mismatch InboundAnswerOutcome.BRIDGED — and are None on every other
outcome (no correlation, a clean forward, a gone-ask 404 bridge). A channel that
renders no correction of its own simply ignores them and maps outcome.
Attributes
InboundBridge
tai42_contract.channels.inbound.InboundBridge
AppChannels.handle_inbound_answer alongside
the correlation key and answer value. channel_id is the registered channel
name; our_identity and client_address are the conversation’s two addresses
(the operator identity the turn answers from, and the participant’s attested address /
thread); cap_key is the party the per-address turn cap holds accountable;
provider_message_id dedupes a provider redelivery at the conversation seam;
medium_message_id is the id the medium gives the message itself, the one a later
quote names (None only when the medium has no such id);
reply_to_medium_message_id is the medium’s id of the message this reply quotes (None
when it quotes none); both arms carry it, so the asker or the bridged turn reads the quote;
bridge_text is the channel’s faithful rendering of the participant’s message for a
bridged turn.
owns_retry_notice lets a channel OWN the participant-facing correction message on a
retryable rejection. The default (False) is that the ladder sends the generic
“that didn’t match, try again” notice on InboundAnswerOutcome.RETRY_KEPT.
When True, the channel’s correction surface IS a re-ask the channel renders off
RETRY_KEPT (a re-opened WhatsApp Flow, a Slack modal’s inline Block-Kit error), so
the ladder SKIPS its notice to avoid double-messaging — it still keeps the
correlation and still emits the operator event (tagged notice_owner="channel").
It applies ONLY to the retryable path: on a hard mismatch (a closed ask) the
channel’s re-ask surface is moot, so the ladder always sends the final “question is
closed” notice regardless of this flag.
params is the OPTIONAL opaque channel enrichment this inbound reply carries — the
ANSWER-path counterpart of a conversation entry’s params: a tapped reply id, a template
button payload, a referral. The ladder threads it BOTH
ways with the same seam symmetry — forwarded to the ask’s callback door alongside the answer
(landing on params, read by
the asking run beside answer) AND, when the reply is instead BRIDGED as a fresh turn,
passed to accept as its params — so enrichment is never dropped on either arm. The
SAME transport vocabulary (validate_entry_params) bounds
it; the platform attaches no meaning and NO TRUST. None means no enrichment.
Attributes
LinkOption
tai42_contract.channels.options.LinkOption
url (an absolute http(s) URL) in the human’s
browser — NO message is submitted, distinct from a ReplyOption. label is the
button text. The URL-button / call-to-action case. Frozen.
Attributes
Option
tai42_contract.channels.options.Option
OptionSection
tai42_contract.channels.options.OptionSection
title is the section header; rows are
its entries — a sectioned list holds ReplyOption rows ONLY (a tapped row submits its
text; a link action is a button, never a list row). A present rows is non-empty. Frozen.
Attributes
ReplyOption
tai42_contract.channels.options.ReplyOption
text as the participant’s next inbound message —
the quick-reply / list-row case, where the option’s own text becomes the turn. description
is an OPTIONAL secondary line a sectioned-list row renders under its text; a channel that
renders flat buttons (no descriptions) ignores it.
id is an OPTIONAL author-set stable identifier for the button/list row. When set, a channel
sends it verbatim on the wire and the participant’s tap echoes it back (a channel surfaces the echoed
id to the inbound turn as opaque enrichment — e.g. Slack forwards it as params.reply_id);
when None the channel mints its own id. Bounded by the platform abuse bound
OPTION_ID_MAX_CHARS and a single-line non-blank label; a channel with a tighter id cap
enforces it in its own code. Frozen.
Attributes
ReplyWindow
tai42_contract.channels.reply_window.ReplyWindow
state is one of:
"none"— the pair has no reply window: a free-form send is not limited by time."closed"— a window exists for the pair and is not open now (never opened, or expired)."open"— a free-form send is allowed untilcloses_at.
closes_at is set (an aware datetime, kept in UTC and in whole seconds) exactly when
state is "open" and is None otherwise; any other combination raises. A
sub-second close time is rounded down to its second, so the window is never reported
longer than it is and every channel dumps the same YYYY-MM-DDTHH:MM:SSZ form. The state
is what the channel knows when it is read; the medium’s own rejection of a send outside its
window stays the final check.
Attributes
SendOutcome
tai42_contract.channels.delivery.SendOutcome
our_identity is the identity the message went out from. address is the
participant address the medium delivered to, in the same form the channel’s inbound
door passes to accept as client_address (taken from the send response where
the medium reveals that form only there). message_ids are the provider ids of the
messages sent, in send order (several when the medium splits a long message, empty
when it exposes no id).
Attributes
check_footer
tai42_contract.channels.options.check_footer
NOTIFICATION_FOOTER_MAX_CHARS.
Raises ValueError.
Parameters
check_header
tai42_contract.channels.options.check_header
link (an
anchor is content, not a header). The item’s own url/kind shape is MediaItem’s
concern. Raises ValueError.
Parameters
check_interactive_composition
tai42_contract.channels.composition.check_interactive_composition
ChannelNotification and AnswerPart share these,
so the two can never drift. noun names the carrier for the raised messages
("notification" / "part"). Rules:
- message is non-blank BY DEFAULT, EXCEPT blank for a CONTENT-ONLY send — a blank message
carried by non-empty
mediaOR alocation(a caption-less image / a bare pin). - an interactive surface (
options,sections,schema) REQUIRES a non-blank message — a choice or a form needs a prompt — so a content-only send carries none of them. optionsXORsections— one choice surface (flat buttons OR a sectioned list).schemais exclusive with bothoptionsandsections— one interactive surface (a form’s fields OR a choice list), never both.headerandfootercompose an interactive message, so each REQUIRESoptionsorsectionspresent.- each per-send
wordingmember is admitted only on the surface that draws it — a form (schema), a flatoptionslist, or a sectionedsectionslist (the one admission table,check_wording_for_notification);wording.form.submitis refused when the form carriespages(has_pages). templateis the standalone out-of-window send: exclusive with every other content and interactive field (media,location,options,sections,schema; and transitivelyheader/footer, which requireoptions/sections).- a form
schemadeclares no top-level property named__proto__(check_form_property_names), the one name a form drawn in a browser cannot keep — the same refusal an asked form meets. - a form
schema’s date keys make sense (check_form_date_rules), the same build-time date rules an asked form meets.
check_options
tai42_contract.channels.options.check_options
NOTIFICATION_OPTIONS_MAX entries. Each option’s own shape
(reply text / link label+url bounds) is the ReplyOption/LinkOption concern.
Raises ValueError.
Parameters
check_sections
tai42_contract.channels.options.check_sections
NOTIFICATION_SECTIONS_MAX sections, and its rows summed across every section
stay within NOTIFICATION_OPTIONS_MAX (one message never fans out an unbounded tap set).
Raises ValueError.
Parameters

