> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Domain Mode

> Domain Mode reads and writes entities through the types of one published Shape, with a short program that Penumbra checks before it runs.

Concept · domain-mode

> **Use when**
>
> You read or change many entities of a Shape in one step, or you build code against a Shape's types.

> **Looking for something else?**
>
> Designing or changing a Shape (card [shape](https://docs.pnbr.io/concepts/shape.md), card [shape-draft](https://docs.pnbr.io/concepts/shape-draft.md)). One search or one read (card [search](https://docs.pnbr.io/concepts/search.md), card [entity](https://docs.pnbr.io/concepts/entity.md)). Staging changes by hand with the CLI (card [workspace](https://docs.pnbr.io/concepts/workspace.md)).

## For

A domain is a published Shape seen as a set of types and relationships. Domain
Mode gives you those types as calls in a program. The program lists entities,
reads one, follows relationships, and stages or saves changes. Penumbra checks
the program before it runs, and each call acts with your credential.

The program is written in a checked subset of JavaScript. It has no network, no
files and no clock. A program can only call what the domain offers.

## Use when

* You must read many entities of one Shape, or follow relationships across
  them, in one step.
* You stage many changes from a pattern, and a workspace by hand is too slow.
* Your own code must read and write a Shape's types. Then you generate a typed
  client.

## Not this

* You design or change the Shape itself: use card [shape](https://docs.pnbr.io/concepts/shape.md) and card
  [shape-draft](https://docs.pnbr.io/concepts/shape-draft.md).
* You need one search or one entity: use card [search](https://docs.pnbr.io/concepts/search.md) or card [entity](https://docs.pnbr.io/concepts/entity.md).
* You stage a few changes by hand: use card [workspace](https://docs.pnbr.io/concepts/workspace.md).

## Rules

1. `domain-mode.1` Read the domain before you write the program. **Your job:**
   on the default connection, call `grammar` and name the domain with `domain`
   when the project has several. In a Kit connection, call
   `domain_mode_introspect`. The answer lists the types, the relationships, the
   rules and the calls that the program may use. **Enforced:** with several
   domains and no choice, the answer is `domain_selection_required` and names the
   choices. A domain that does not exist is `domain_not_found`.
2. `domain-mode.2` A program is a checked subset of JavaScript. **Enforced:** a
   program with a form that Domain Mode does not accept is refused before it
   runs, with `program_syntax_refused`. The first line gives that code. Each
   further line names one form, its place and the form to use instead. A refused
   program leaves no run behind, so a fixed one may reuse the run id.
   **Your job:** use `const`, `for…of` over arrays, `await` on calls and array
   methods with one-expression arrows. Do not use `let` that is reassigned,
   `while`, functions, `try`, `new` or regular expressions.
3. `domain-mode.3` Penumbra repairs a few forms with one safe meaning.
   **Your job:** read the `healed` list in the result. It shows each form that
   Penumbra rewrote and why. Write the repaired form next time.
4. `domain-mode.4` A program has limits. **Enforced:** a program over 256 KiB is
   refused with `program_too_large`. More than 64 calls to the host ends it with
   `host_call_budget_exceeded`. A result over 64 KiB is refused with
   `program_result_too_large`. A program that runs over its deadline stops with
   `execution_deadline_exceeded`. The default deadline is 10 seconds.
   **Your job:** split a large job into several programs, and page reads with
   `limit` and the cursor. A page holds at most 100 entities.
5. `domain-mode.5` A write has an outcome, and the program must read it.
   **Your job:** check each write for `applied`, `queued`, `pending` or
   `unknown`. A run with `status: completed` means that the program returned. It
   does not mean that every effect finished. `pending` waits for an approval
   (card [approval](https://docs.pnbr.io/concepts/approval.md)), and `unknown` follows problem [reply-lost](https://docs.pnbr.io/troubleshooting/reply-lost.md).
6. `domain-mode.6` A write that the domain refuses is a value, not an error.
   **Enforced:** the call returns `outcome: "refused"` with a `code`, such as
   `domain_rules_rejected`, and nothing is applied. Later writes in that run are
   held with `run_effects_held`. Reads still work. **Your job:** test the outcome
   before the next write. A program has no `try`, and any other failure ends the
   program with its error.
7. `domain-mode.7` Keep the reference of a run and resume it after a lost reply.
   **Your job:** `execute` gives `execution:<id>`. Call it again with `resume` set
   to that reference and the same code. **Enforced:** other code under the same
   reference is refused with `run_contract_or_program_changed`. A run is kept for
   24 hours. Call `check_status` with no reference to list your recent runs.
8. `domain-mode.8` A domain runs at its current published version. **Enforced:**
   an entity saved under an older version reads when the changes since are
   non-breaking. **Your job:** after a breaking change, read problem
   [breaking-shape-change](https://docs.pnbr.io/troubleshooting/breaking-shape-change.md) before you run programs on the old entities.
9. `domain-mode.9` A generated client is a file you keep. **Your job:** run
   `penumbra domain generate <shape> --out <file>`, review the file, and keep it
   in source control. Pass `--artifact-digest` for an exact version. **Enforced:**
   a file that differs is refused with `output_exists` unless you pass `--force`.
   With `--check`, a file that differs is refused with
   `domain_generation_changed`, and nothing is written.
10. `domain-mode.10` Neither the client nor a program adds authority.
    **Enforced:** every call uses the credential, the View and the approval
    rules of the connection that runs it. **Your job:** do not use a generated
    client to read what your credential cannot read.
11. `domain-mode.11` A Kit can limit Domain Mode to some Shapes. **Enforced:** a
    connection at such an address refuses other Shapes with
    `domain_outside_endpoint_slice`. Create the address with
    `penumbra kits addresses create <kit-id> --domain-mode-shape <shape-id>`.

## Failure signs

* A program is refused with `program_syntax_refused`: rule [domain-mode.2](https://docs.pnbr.io/concepts/domain-mode.md#rule-domain-mode-2).
* A call is refused with `domain_selection_required`: rule [domain-mode.1](https://docs.pnbr.io/concepts/domain-mode.md#rule-domain-mode-1).
* A run reports `completed`, and the entities did not change: rules
  [domain-mode.5](https://docs.pnbr.io/concepts/domain-mode.md#rule-domain-mode-5) and [domain-mode.6](https://docs.pnbr.io/concepts/domain-mode.md#rule-domain-mode-6).
* A run does not finish and the reply was lost: rule [domain-mode.7](https://docs.pnbr.io/concepts/domain-mode.md#rule-domain-mode-7) and problem
  [reply-lost](https://docs.pnbr.io/troubleshooting/reply-lost.md).
* An older entity refuses a property that the Shape now has: problem
  [breaking-shape-change](https://docs.pnbr.io/troubleshooting/breaking-shape-change.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra domain generate`. The CLI has no command that runs a program. |
| MCP (default) | `grammar` reads a domain. `discover_actions` finds the calls. `execute` runs a program. `check_status` follows a run. |
| MCP (Kit) | `domain_mode_search`, `domain_mode_introspect` and `domain_mode_execute` in a Kit that has them, such as one made for a Shape (see the Kit card). |
| Program | `penumbra.domain.types.<Type>`, `penumbra.domain.stage`, `penumbra.workspaces.open` and `penumbra.shapes` in `execute`. |
| SDK | `project.domain` with a generated definition, and `project.domains.compile`. |

`penumbra.shapes` authors Shapes (card [shape-draft](https://docs.pnbr.io/concepts/shape-draft.md)).

## Keep going

[Shape](https://docs.pnbr.io/concepts/shape.md) · [Entity](https://docs.pnbr.io/concepts/entity.md) · [Relationship](https://docs.pnbr.io/concepts/relationship.md) · [Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [Kit](https://docs.pnbr.io/concepts/kit.md) · [The reply to a change was lost](https://docs.pnbr.io/troubleshooting/reply-lost.md) · [A Shape change renamed or removed something](https://docs.pnbr.io/troubleshooting/breaking-shape-change.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.