Outcomes, effects, and safety rules

This page is the canonical assistant-facing interpretation of Domino's cross-surface execution contract.

Effect classes

Read

Reads inspect current authorized state. They do not require idempotency keys and do not create mutation receipts.

Write

Writes change private or shared Domino state. They require a caller-stable idempotency key on direct MCP and API surfaces. Exact replay returns the stored result; changed input under the same key conflicts.

External send

External effects can reach another person. They require a valid prepared action, current authorization, recipient and destination revalidation, a matching principal and surface, and explicit confirmation.

The hosted model never receives direct send capabilities. Direct v2 callers use actions.commit; SMS uses its deterministic exact-SEND protocol to consume the current SMS preparation.

Capability statuses

Status	Meaning	Correct caller behavior
`completed`	Terminal result was reached	Present only confirmed facts and effects.
`unchanged`	State already matched	Explain that no new change was needed.
`accepted`	Work began asynchronously	Poll or invoke the returned status action.
`needs_input`	A user decision or missing field is required	Ask one useful question, then submit an intentional follow-up.
`failed`	Domino could not safely complete the operation	Follow normalized error and recovery guidance.

Canonical outcome

The canonical contract is domino.capability-outcome.v1.

Facts

outcome.facts contains safe current facts about the result.

Resources

outcome.resources contains authorized resource summaries and opaque handles. Do not expose or fabricate internal database IDs.

Collections

outcome.collection can contain:

a stable snapshot_handle;
ordered items;
a next_cursor;
has_more.

Use snapshot and cursor state for continuation. Do not rediscover merely to recreate a prior numbered choice.

Disclosures

outcome.disclosures contains statements that must be presented before a related next action or commitment.

Next actions

outcome.next_actions contains permitted, typed continuations. A returned next action does not itself grant permission; it tells the caller what operation can follow after satisfying user intent and authorization.

Confirmation

outcome.confirmation.state explains whether no confirmation is needed, an action is prepared, approval is required, or a confirmed effect was consumed. Treat any non-consumed preparation as incomplete.

Confirmed and unconfirmed effects

Only effects.confirmed authorizes a claim that a mutation or external effect happened. effects.unconfirmed describes intended or pending effects and must not be phrased as completed.

Prepared-action invariants

A prepared action binds:

actor and authenticated principal;
surface;
exact action and payload;
subject and revision;
recipient and destination fingerprints;
payload integrity;
expiry;
required authorization.

An edit can supersede it. Expiry invalidates it. Commit rechecks current state immediately before the effect. Replay must not duplicate the effect.

Reference safety

Resolve named people against authorized current state.
Ambiguous people require clarification rather than name matching.
Use handles and public identifiers returned by Domino.
A stale, invisible, revised, or unauthorized reference is unavailable.
Never ask an ordinary user for an internal database ID.

Surface-specific confirmation

Surface	Confirmation
Web	Explicit current UI review and publish/send action
SMS	Current eligible preparation plus entire uppercase `SEND` message
MCP	Later explicit approval followed by same-principal MCP `actions.commit`
API	Later explicit approval followed by same-principal API commit

Safe claims

Say:

“The draft is saved.”
“The share link is ready to copy.”
“Domino is still processing that capture.”
“The invitation was sent to Emily; Andrew still needs the host to share his link.”

Do not say:

“Everyone was invited” when only a draft exists.
“The link was shared” when it was only copied.
“They are free” without current authorized availability evidence.
“The plan changed” when the result is needs_input or failed.

LLM answering guidance

Before making a consequential claim, locate the supporting terminal status, outcome fact, and confirmed effect. If those are absent, describe the current preparation, pending work, or required recovery instead.