# 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.