Domain Mode

​

For

​

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 and card shape-draft.
• You need one search or one entity: use card search or card entity.
• You stage a few changes by hand: use card workspace.

​

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), and unknown follows problem reply-lost.
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 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.
• A call is refused with domain_selection_required: rule domain-mode.1.
• A run reports completed, and the entities did not change: rules domain-mode.5 and domain-mode.6.
• A run does not finish and the reply was lost: rule domain-mode.7 and problem reply-lost.
• An older entity refuses a property that the Shape now has: problem breaking-shape-change.

​

Doors

​

Keep going