@hyperscale0/hsx 1.0.0 → 2.0.1

package/docs/llms-full.txt

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 1.0.0. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.0.1. Do not edit. -->
 
 # HSX full documentation
 
@@ -10,7 +10,7 @@ This program sends a tip from a listener to a host:
 
 ```hsx
 program tip_jar "Tip jar"
-import { instant_transfer } from "std/settlements"
+import { instant_transfer } from "std/money_flows"
 party listener: person
 party host: business
 settlement tip = instant_transfer {
@@ -29,7 +29,7 @@ After package installation, run `npx hsx check product.hsx` while editing and `n
 
 # Money
 
-HSX indexes money by currency. `money<SAR>` is the field type inside a general instrument. `amount: total: money(SAR)` binds a settlement parameter to a new SAR money field. Values use integer minor units, so `1250` means SAR 12.50.
+HSX indexes money by currency. `money<SAR>` is the field type inside a general instrument. `amount: total: money(SAR)` binds a settlement parameter to a new SAR money field. Values use integer minor units, so `1250` means SAR 12.50. The emitted UDL field keeps the currency as `x-hyperscale-currency`, which is how the platform learns a program's ledger currency.
 
 Money of different currencies never unifies. Percent literals use basis-point precision: `2%` is 200 basis points and `2.5%` is 250 basis points. The compiler floors percentage-derived minor units and assigns any declared remainder according to the selected instrument.
 
@@ -55,11 +55,11 @@ Do not use free arithmetic to repair a linearity refusal. Choose a standard-libr
 
 # Instruments
 
-Start with the standard library. Import a settlement module by export name from `std/settlements`, then apply it under a local settlement name. The local name becomes the emitted instrument id.
+Start with the money flows library (open/hsx/std). Import a money flow by export name from `std/money_flows`, then apply it under a local settlement name. The local name becomes the emitted instrument id.
 
 ```hsx
 program equipment_hire "Equipment hire"
-import { scheduled } from "std/settlements"
+import { scheduled } from "std/money_flows"
 party renter: person
 party owner: business
 settlement installments = scheduled {
@@ -74,7 +74,48 @@ settlement installments = scheduled {
 
 Required parameters state the instrument's core contract. Optional parameters add bounded behavior such as a deadline, cancellation allocation, fee, or policy. Omit an optional block when the product does not need it. Do not pass an empty block as a substitute unless the module documents that form.
 
-The generated standard-library reference lists every module, parameter, action, port, and emitted clause. Read that page before choosing a module. Prefer one module that already states the required lifecycle over a custom instrument with copied mechanics.
+The generated money flows reference lists every module, parameter, action, port, and emitted clause. Read that page before choosing a module. Prefer one module that already states the required lifecycle over a custom instrument with copied mechanics.
+
+## Account fields
+
+When declaring fields of type `account<C>`, the HSX compiler automatically lowers the field schema with the UDL2002 account pattern (`^acct_(sandbox|live)_[a-z0-9]{8,64}$`). Authors do not need to write an explicit `pattern` clause on account fields.
+
+```hsx
+fields {
+  customerAccountId: account<SAR>;
+  amount: money<SAR>;
+}
+```
+
+## Port declarations and action clauses
+
+HSX supports two distinct port syntaxes depending on scope:
+
+1. **Top-level port declarations** declare a named port at program scope using `allowed: [...]`.
+2. **Action-level port clauses** define caller permissions directly inside an instrument action using `allowed_parties: [...]`.
+
+Top-level port declaration:
+
+```hsx
+port confirm_delivery {
+  allowed: [buyer];
+}
+```
+
+Action-level port clause:
+
+```hsx
+action release {
+  agent_description: "Release escrowed funds to the payee."
+  steps: [];
+  moves: [];
+  port {
+    allowed_parties: [payer];
+  }
+}
+```
+
+Writing `allowed:` inside an action-level `port` clause triggers diagnostic `HSX1508`. Use `allowed_parties: [...]` inside action clauses, and reserve `allowed: [...]` for top-level port declarations.
 
 # Lifecycles
 
@@ -83,6 +124,7 @@ A lifecycle lists every state, names one initial state, and declares action tran
 ```hsx
 program approvals "Approvals"
 instrument approval {
+  agent_description: "Manage a bounded approval decision across pending, approved, and rejected states."
   title: "Approval"
   summary: "A bounded approval decision"
   fields {}
@@ -92,12 +134,26 @@ instrument approval {
     on approve: pending -> approved;
     on reject: pending -> rejected;
   }
-  action create { steps: []; moves: []; }
-  action approve { steps: []; moves: []; }
-  action reject { steps: []; moves: []; }
+  action create {
+    agent_description: "Create an approval record in pending state."
+    steps: [];
+    moves: [];
+  }
+  action approve {
+    agent_description: "Approve the pending decision."
+    steps: [];
+    moves: [];
+  }
+  action reject {
+    agent_description: "Reject the pending decision."
+    steps: [];
+    moves: [];
+  }
 }
 ```
 
+Every callable custom instrument action becomes an agent tool and requires an `agent_description` string. Instruments that declare callable actions also require an `agent_description` string. Actions that declare a `due` clause are exempt system actions that run on a schedule instead of an agent call. The compiler emits `HSX1509` when an author omits `agent_description` on an instrument or callable action.
+
 Standard-library instruments bind ports to caller decisions. A deadline appears as stored date data and a `due` clause on the action that may run at that date. An unwind states how a failed or cancelled path drains held value. The compiler refuses a reachable exit that strands money.
 
 Keep lifecycle changes additive after composition. Add a new action or state when old instances can still obey the previous contract. Do not rename a state or tighten an active transition in place.
@@ -108,7 +164,7 @@ Standard-library payment modules accept bounded fee forms. A payer fee sits on t
 
 ```hsx
 program lesson_market "Lesson market"
-import { instant_transfer, pooled_split } from "std/settlements"
+import { instant_transfer, pooled_split } from "std/money_flows"
 party student: person
 party tutor: business
 party assistant: business
@@ -133,7 +189,7 @@ Every percentage partition must total 100 percent. `pooled_split` distributes a
 
 ```hsx
 program studio_booking "Studio booking"
-import { cancellable_booking } from "std/settlements"
+import { cancellable_booking } from "std/money_flows"
 party guest: person
 party studio: business
 settlement session = cancellable_booking {
@@ -154,7 +210,7 @@ HSX schedules are finite. A literal `count`, an interval, and a first due date l
 
 ```hsx
 program installments "Installments"
-import { scheduled } from "std/settlements"
+import { scheduled } from "std/money_flows"
 party buyer: person
 party seller: business
 settlement plan = scheduled {
@@ -177,7 +233,7 @@ One program can apply several instruments. Each instrument keeps its own lifecyc
 
 ```hsx
 program studio_sales "Studio sales"
-import { instant_transfer, scheduled } from "std/settlements"
+import { instant_transfer, scheduled } from "std/money_flows"
 party buyer: person
 party studio: business
 settlement purchase = instant_transfer {
@@ -204,7 +260,7 @@ Keep each money route in one instrument. Connect instruments with evidence and r
 
 ```hsx
 program supplier_payment "Supplier payment"
-import { reconciled_payout } from "std/settlements"
+import { reconciled_payout } from "std/money_flows"
 party treasury: business
 party supplier: business
 settlement payout = reconciled_payout {
@@ -218,6 +274,12 @@ settlement payout = reconciled_payout {
 }
 ```
 
+## Recomposition and exposed actions
+
+When evolving an existing Product with new instruments or flows, the composer plans the candidate program against the active Product Build.
+
+Public action exposures preserve stable semantic identities across builds. Unchanged authored instruments and catalog instruments retain their exposures without false removal and re-addition churn. Only genuinely new, removed, or rebound action aliases appear in the exposure delta.
+
 # Writing a module
 
 A module is ordinary HSX source. It declares a dotted module name and exports templates, types, constants, subjects, or applications. The compiler does not branch on a standard-library module name.
@@ -225,6 +287,7 @@ A module is ordinary HSX source. It declares a dotted module name and exports te
 ```hsx
 program approval_example "Approval example"
 instrument approval() {
+  agent_description: "Reusable approval lifecycle template."
   title: "Approval"
   summary: "A reusable approval lifecycle"
   fields {}
@@ -233,12 +296,22 @@ instrument approval() {
     initial pending;
     on approve: pending -> approved;
   }
-  action create { steps: []; moves: []; }
-  action approve { steps: []; moves: []; }
+  action create {
+    agent_description: "Create a pending approval record."
+    steps: [];
+    moves: [];
+  }
+  action approve {
+    agent_description: "Approve the pending decision."
+    steps: [];
+    moves: [];
+  }
 }
 instrument review = approval()
 ```
 
+Custom instruments and callable actions require `agent_description: "..."`. An agent uses these descriptions as tool instructions when invoking actions on an instance. Actions that declare a `due` clause run without an agent call and remain exempt from this requirement. Omitting `agent_description` on callable actions or their containing instruments triggers `HSX1509`.
+
 A parameter list makes an instrument a template, including an empty list. A concrete instrument without a parameter list emits directly when its file compiles. Export only the declarations that callers need.
 
 Imported exports carry the local declarations they reference. Identical declarations unify. Conflicting declarations report `HSX1009`. Keep module parameters typed, keep loops finite, and use UDL clause vocabulary for instrument and action mechanics.
@@ -251,7 +324,7 @@ Compilation emits a deterministic cost manifest beside the UDL document. The man
 
 ```hsx
 program direct_sale "Direct sale"
-import { instant_transfer } from "std/settlements"
+import { instant_transfer } from "std/money_flows"
 party buyer: person
 party seller: business
 settlement sale = instant_transfer {
@@ -264,9 +337,9 @@ settlement sale = instant_transfer {
 
 Read an action line as `instrument.action`, followed by the effect signature and its count. The payer tells whether the product or end customer bears the row. `perEventMinor` prices one occurrence in the cost table's billing currency. A row with `bps` also names a volume meter.
 
-The monthly estimate is an expression over declared meter variables. Billing supplies observed readings to that frozen expression. Recomposition emits a new manifest for the next commercial snapshot. It does not rewrite a prior manifest.
+The monthly estimate is an expression over declared meter variables. Billing supplies observed readings to that frozen expression. Recomposition emits a new manifest for the next commercial snapshot. It does not rewrite a prior manifest. During recomposition planning, compose plan calculates the candidate program's proposed estimate and reconciles it against the current Build's frozen pricing quote. The existing Product retains its frozen quote until the recomposition is applied.
 
-An effect without a price row reports `HSX1301`. An invalid price reports `HSX1302`. A missing cost table also reports `HSX1301`. Use the single rate card shipped at `examples/cost-table.json`; do not create a second table for documentation.
+An effect without a price row reports `HSX1301`. An invalid price reports `HSX1302`. A missing cost table also reports `HSX1301`. `examples/cost-table.json` ships one rate card per priced billing currency; the compiler picks the card whose currency the program's money fields move. Money in a currency no card prices reports `HSX1304`, and money in two currencies reports `HSX1305`: a program bills in one ledger currency. A move of a `money<SAR>` field moves SAR whatever the caller wrote in the instance currency field: the compiler pins the move's currency binding to the constant, and a binding it cannot pin reports `HSX1306`. Do not create another table for documentation.
 
 Do not confuse an action `quote` with the commercial cost manifest. `cancellable_booking.cancel` quotes a customer-visible cancellation penalty and `confirm` commits it. The compiler counts an instrument that carries a quote as unwind work because an expired or abandoned offer still needs bounded cleanup. The cost manifest prices that runtime work from the shipped rate card. It does not replace, spend, or alter the quoted financial amount.
 
@@ -285,7 +358,7 @@ Use one loop: compile, find the first error code in the diagnostics reference, a
 
 ```hsx
 program repaired_transfer "Repaired transfer"
-import { instant_transfer } from "std/settlements"
+import { instant_transfer } from "std/money_flows"
 party sender: person
 party recipient: business
 settlement transfer = instant_transfer {
@@ -301,7 +374,7 @@ Exit code `0` means the command accepted the program. Exit code `1` means compil
 # CLI
 
 ```text
-hsx 1.0.0, the HSX compiler
+hsx 2.0.1, the HSX compiler
 
 Usage:
   hsx check <file.hsx> [--strict]
@@ -364,9 +437,13 @@ Fix: Keep exactly one program declaration.
 ```hsx expect=HSX1002
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 program second "Second"
@@ -391,9 +468,13 @@ Fix: Keep one declaration or give each declaration a distinct name.
 ```hsx expect=HSX1004
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 instrument probe { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
@@ -439,9 +520,13 @@ Fix: Complete the declaration and bind every referenced decision port.
 ```hsx expect=HSX1008
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 subject vehicle { title: "Vehicle"; }
@@ -564,11 +649,11 @@ Fix: Expose an action on an explicitly used published instrument.
 
 No source-only witness exists. This refusal requires a compiler-host published catalog.
 
-## HSX1022: Authored instrument in a composition
+## HSX1022: Authored instrument collides with published catalog
 
 Stage: `typecheck`
 
-Fix: Publish the instrument separately, then select it with use.
+Fix: Rename the authored instrument to avoid colliding with published catalog instruments.
 
 No source-only witness exists. This refusal requires a compiler-host published catalog.
 
@@ -581,13 +666,61 @@ Fix: List declared, non-optional field names once each.
 ```hsx expect=HSX1023
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   required: missing;
 }
 ```
 
+## HSX1024: Decision party has no matching account binding
+
+Stage: `typecheck`
+
+Fix: Bind the allowed party to an account field and use that binding in the decision action.
+
+```hsx expect=HSX1024
+program decision_binding "Decision binding"
+party buyer: person
+party seller: business
+port approve { allowed: [buyer] }
+instrument gated(decision: condition) {
+  fields {}
+  parties { payer: seller }
+  lifecycle { states created done; initial created; on approve: created -> done; }
+  action create { steps: []; }
+  action [decision] { steps: []; port { allowed_parties: [payer]; } }
+}
+instrument gate = gated(decision: port approve)
+```
+
+## HSX1025: Unknown decision port shape type
+
+Stage: `typecheck`
+
+Fix: Declare the shape field as text, money(CUR), date, integer, boolean, account(CUR), ref<instrument_id>, id(instrument_id), bps, or percent.
+
+```hsx expect=HSX1025
+program catalog_probe "Catalog probe"
+import { security_deposit } from "std/money_flows"
+party buyer: person
+party seller: business
+settlement hold = security_deposit {
+  payer: buyer
+  holder: seller
+  amount: depositAmount: money(SAR)
+  claim: port report_damage
+  claim_amount: { field: damageAmount, bound: depositAmount, remainder: return }
+  return: port pass_inspection
+}
+port report_damage { allowed: [seller] shape { damageAmount: money(SAR) } }
+port pass_inspection { allowed: [seller] shape { invalidField: mystery_type } }
+```
+
 ## HSX1101: Currency mismatch
 
 Stage: `typecheck`
@@ -597,9 +730,13 @@ Fix: Use the declared currency because money values never coerce.
 ```hsx expect=HSX1101
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 const fee: money<SAR> = USD 1.00
@@ -614,9 +751,13 @@ Fix: Round the literal to the currency's minor-unit precision.
 ```hsx expect=HSX1102
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 const fee: money<SAR> = SAR 1.001
@@ -631,9 +772,13 @@ Fix: Use an integer, percent, bps, or valid fixed-money binding.
 ```hsx expect=HSX1103
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   summary: 1.5;
 }
 ```
@@ -647,9 +792,13 @@ Fix: Pass the type declared by the parameter or UDL slot.
 ```hsx expect=HSX1104
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   summary: money(SAR, 2500);
 }
 ```
@@ -680,9 +829,13 @@ Fix: Leave exactly one sink for each produced money value.
 ```hsx expect=HSX1201
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   fields { amount: money<SAR>; }
 action pay { computes remainder rest { amount_ref: total; on_zero: refuse; total_path: fields.amount; }; moves: [{ amount: rest; }, { amount: rest; }]; }
 }
@@ -697,9 +850,13 @@ Fix: Route each produced money value to one explicit sink.
 ```hsx expect=HSX1202
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   fields { amount: money<SAR>; }
 action pay { computes remainder rest { amount_ref: total; on_zero: refuse; total_path: fields.amount; }; }
 }
@@ -714,9 +871,13 @@ Fix: Supply a versioned cost table with a row for every emitted effect.
 ```hsx expect=HSX1301
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
 
 }
 ```
@@ -737,6 +898,66 @@ Fix: Use the supported uppercase cost-table currency.
 
 No source-only witness exists. This refusal requires an invalid compiler-host cost-table currency.
 
+## HSX1304: Unpriced ledger currency
+
+Stage: `typecheck`
+
+Fix: Move money in a currency the shipped cost tables price.
+
+```hsx expect=HSX1304
+program catalog_probe "Catalog probe"
+instrument probe {
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields { amount: money<JPY>; }
+  lifecycle { states created; initial created; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
+
+}
+```
+
+## HSX1305: More than one ledger currency
+
+Stage: `typecheck`
+
+Fix: Move all money in one currency; a program bills in one ledger currency.
+
+```hsx expect=HSX1305
+program catalog_probe "Catalog probe"
+instrument probe {
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields { amount: money<SAR>; fee: money<USD>; }
+  lifecycle { states created; initial created; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
+
+}
+```
+
+## HSX1306: Fixed-currency amount moved in another currency
+
+Stage: `typecheck`
+
+Fix: Bind the currency of a money<CUR> move or account step as the constant CUR; the compiler pins a binding that reads the instrument's currency field.
+
+```hsx expect=HSX1306
+program catalog_probe "Catalog probe"
+instrument probe {
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields { amount: money<SAR>; payeeAccountId: account<SAR>; payerAccountId: account<SAR>; }
+  lifecycle { states created; initial created; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
+  action pay { agent_description: "Pay the amount."; moves: [{ "bind": { "amount": { "from": "instance"; "path": "fields.amount"; }; "currency": { "from": "const"; "value": "USD"; }; "destinationAccountId": { "from": "instance"; "path": "fields.payeeAccountId"; }; "sourceAccountId": { "from": "instance"; "path": "fields.payerAccountId"; }; }; "key": "transfer"; "operation": "internal_transfer.create"; }]; steps: []; }
+}
+```
+
 ## HSX1401: Unbounded action
 
 Stage: `typecheck`
@@ -746,9 +967,13 @@ Fix: Replace runtime iteration with a bounded compile-time comprehension.
 ```hsx expect=HSX1401
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   action run { while { condition: true; }; }
 }
 ```
@@ -790,9 +1015,13 @@ Fix: Reduce the fixed expansion to the compiler limit.
 ```hsx expect=HSX1404
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   for item in 257 { action run_[item] { steps: []; } }
 }
 ```
@@ -835,9 +1064,13 @@ Fix: Use a clause exported by the targeted UDL vocabulary.
 ```hsx expect=HSX1501
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   unknown_clause: true;
 }
 ```
@@ -883,9 +1116,13 @@ Fix: Keep one occurrence of the clause.
 ```hsx expect=HSX1505
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   title: "First"; title: "Second";
 }
 ```
@@ -899,9 +1136,13 @@ Fix: Keep either public: none or a public action name.
 ```hsx expect=HSX1506
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   action finish { public: none; public_action: finishProbe; steps: []; }
 }
 ```
@@ -918,6 +1159,40 @@ export instrument template() { fields {}; lifecycle { states created; initial cr
 instrument probe = template() { fields: {}; }
 ```
 
+## HSX1508: Invalid action-level port syntax
+
+Stage: `typecheck`
+
+Fix: Use allowed_parties: [...] inside an action-level port clause; allowed: is for top-level port declarations.
+
+```hsx expect=HSX1508
+program catalog_probe "Catalog probe"
+party approver: person
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create {
+    steps: [];
+    port { allowed: [approver]; }
+  }
+}
+```
+
+## HSX1509: Callable action without an agent description
+
+Stage: `typecheck`
+
+Fix: Add agent_description: "..." to the instrument and to every action a caller can reach; composer.check refuses the program without them.
+
+```hsx expect=HSX1509
+program catalog_probe "Catalog probe"
+instrument probe {
+  fields {}
+  lifecycle { states created; initial created; }
+  action create { steps: []; }
+}
+```
+
 ## HSX1601: Invalid UDL shape
 
 Stage: `lower`
@@ -943,9 +1218,13 @@ Fix: Correct compile-time block keys or parameter bindings.
 ```hsx expect=HSX1603
 program catalog_probe "Catalog probe"
 instrument probe {
-  fields {}
+  agent_description: "Probe instrument for catalog diagnostics.";
+  fields {  }
   lifecycle { states created; initial created; }
-  action create { steps: []; }
+  action create {
+    agent_description: "Create a probe instance.";
+    steps: [];
+  }
   title: "__hsx_none__";
 }
 ```
@@ -964,7 +1243,7 @@ The parser is hand-written. This page records the exported lexer vocabulary, the
 
 ## Typed clause spellings
 
-`agent description`, `capture input`, `commit`, `quote`, `decided amount`, `deadline`, `decision`, `computes distribute`, `description`, `due`, `earnable`, `event name`, `examples`, `input`, `moves`, `payout`, `port`, `principal`, `public action`, `reconcile`, `computes remainder`, `requires aggregate`, `requires checks`, `requires drained`, `requires exposure`, `requires refs`, `sandbox failure point`, `sets at`, `computes signed_sum`, `steps`, `summary`, `updates`, `notify`, `agent description`, `aggregate invariants`, `caller parked states`, `description`, `dials`, `distinct parties`, `computes derived`, `computes fees`, `id prefix`, `nav`, `partitions`, `subject`, `summary`, `surface visibility`, `template id`, `title`, `update`
+`agent description`, `capture input`, `commit`, `quote`, `decided amount`, `deadline`, `decision`, `computes distribute`, `description`, `due`, `earnable`, `event name`, `examples`, `input`, `moves`, `payout`, `port`, `principal`, `public action`, `reconcile`, `computes remainder`, `requires aggregate`, `requires checks`, `requires drained`, `requires exposure`, `requires refs`, `sandbox failure point`, `sets at`, `computes signed_sum`, `steps`, `summary`, `updates`, `notify`, `agent description`, `aggregate invariants`, `caller parked states`, `description`, `dials`, `distinct parties`, `computes derived`, `computes fees`, `id prefix`, `journeys`, `nav`, `partitions`, `subject`, `summary`, `surface visibility`, `template id`, `title`, `update`
 
 ## Standard-library modules
 
@@ -990,7 +1269,7 @@ The parser is hand-written. This page records the exported lexer vocabulary, the
 
 # advance
 
-Source: [`std/settlements/advance.hsx`](../../../std/settlements/advance.hsx)
+Source: [`std/money_flows/advance.hsx`](../../../std/money_flows/advance.hsx)
 
 ## Export
 
@@ -1024,7 +1303,7 @@ None.
 
 # cancellable_booking
 
-Source: [`std/settlements/cancellable_booking.hsx`](../../../std/settlements/cancellable_booking.hsx)
+Source: [`std/money_flows/cancellable_booking.hsx`](../../../std/money_flows/cancellable_booking.hsx)
 
 ## Export
 
@@ -1047,18 +1326,18 @@ None.
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                            |
-| ---------- | ---------------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`           |
-| `take`     | `agent description`, `moves`, `steps`, `summary`           |
-| `complete` | `due`, `moves`, `steps`, `summary`                         |
-| `cancel`   | `agent description`, `moves`, `quote`, `steps`, `summary`  |
-| `confirm`  | `agent description`, `commit`, `moves`, `steps`, `summary` |
-| `retain`   | `agent description`, `moves`, `steps`, `summary`           |
+| Action     | Clauses lowered                                                           |
+| ---------- | ------------------------------------------------------------------------- |
+| `create`   | `agent description`, `moves`, `steps`, `summary`                          |
+| `take`     | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `complete` | `due`, `moves`, `steps`, `summary`                                        |
+| `cancel`   | `agent description`, `moves`, `quote`, `steps`, `summary`                 |
+| `confirm`  | `agent description`, `commit`, `moves`, `steps`, `summary`                |
+| `retain`   | `agent description`, `moves`, `steps`, `summary`                          |
 
 # captured_payment
 
-Source: [`std/settlements/captured_payment.hsx`](../../../std/settlements/captured_payment.hsx)
+Source: [`std/money_flows/captured_payment.hsx`](../../../std/money_flows/captured_payment.hsx)
 
 ## Export
 
@@ -1085,22 +1364,22 @@ Source: [`std/settlements/captured_payment.hsx`](../../../std/settlements/captur
 
 ## Actions and clauses
 
-| Action             | Clauses lowered                                                                              |
-| ------------------ | -------------------------------------------------------------------------------------------- |
-| `create`           | `agent description`, `moves`, `steps`, `summary`                                             |
-| `authorize`        | `agent description`, `moves`, `steps`, `summary`                                             |
-| `capture`          | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary`         |
-| `capture_more`     | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary`         |
-| `settle`           | `agent description`, `deadline`, `moves`, `steps`, `summary`                                 |
-| `void`             | `agent description`, `moves`, `steps`, `summary`                                             |
-| `expire`           | `due`, `moves`, `steps`, `summary`                                                           |
-| `settle_on_expiry` | `due`, `moves`, `steps`, `summary`                                                           |
-| `correction_name`  | `agent description`, `moves`, `port`, `steps`, `summary`                                     |
-| `reversal_name`    | `agent description`, `deadline`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| Action             | Clauses lowered                                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `create`           | `agent description`, `moves`, `steps`, `summary`                                                              |
+| `authorize`        | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                                     |
+| `capture`          | `agent description`, `deadline`, `description`, `input`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `capture_more`     | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary`                          |
+| `settle`           | `agent description`, `deadline`, `moves`, `steps`, `summary`                                                  |
+| `void`             | `agent description`, `moves`, `steps`, `summary`                                                              |
+| `expire`           | `due`, `moves`, `steps`, `summary`                                                                            |
+| `settle_on_expiry` | `due`, `moves`, `steps`, `summary`                                                                            |
+| `correction_name`  | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary`                            |
+| `reversal_name`    | `agent description`, `capture input`, `deadline`, `input`, `moves`, `port`, `steps`, `summary`                |
 
 # conditional_disbursement
 
-Source: [`std/settlements/conditional_disbursement.hsx`](../../../std/settlements/conditional_disbursement.hsx)
+Source: [`std/money_flows/conditional_disbursement.hsx`](../../../std/money_flows/conditional_disbursement.hsx)
 
 ## Export
 
@@ -1125,14 +1404,14 @@ Source: [`std/settlements/conditional_disbursement.hsx`](../../../std/settlement
 | Action    | Clauses lowered                                                                                   |
 | --------- | ------------------------------------------------------------------------------------------------- |
 | `create`  | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `deny`    | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `deny`    | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary`                |
 | `create`  | `agent description`, `moves`, `steps`, `summary`                                                  |
 | `approve` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
 | `pay`     | `agent description`, `moves`, `steps`, `summary`                                                  |
 
 # credit_facility
 
-Source: [`std/settlements/credit_facility.hsx`](../../../std/settlements/credit_facility.hsx)
+Source: [`std/money_flows/credit_facility.hsx`](../../../std/money_flows/credit_facility.hsx)
 
 ## Export
 
@@ -1166,7 +1445,7 @@ None.
 
 # held_payment
 
-Source: [`std/settlements/held_payment.hsx`](../../../std/settlements/held_payment.hsx)
+Source: [`std/money_flows/held_payment.hsx`](../../../std/money_flows/held_payment.hsx)
 
 ## Export
 
@@ -1195,41 +1474,45 @@ Source: [`std/settlements/held_payment.hsx`](../../../std/settlements/held_payme
 
 ## Actions and clauses
 
-| Action                | Clauses lowered                                                                               |
-| --------------------- | --------------------------------------------------------------------------------------------- |
-| `fund_piece_2`        | `agent description`, `moves`, `steps`, `summary`                                              |
-| `fund_piece_3`        | `agent description`, `moves`, `steps`, `summary`                                              |
-| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary`                                              |
-| `release_piece_2`     | `agent description`, `moves`, `steps`, `summary`                                              |
-| `release_piece_3`     | `agent description`, `moves`, `steps`, `summary`                                              |
-| `refund_piece_2`      | `agent description`, `moves`, `steps`, `summary`                                              |
-| `refund_piece_3`      | `agent description`, `moves`, `steps`, `summary`                                              |
-| `unfund_piece_1`      | `agent description`, `moves`, `steps`, `summary`                                              |
-| `unfund_piece_2`      | `agent description`, `moves`, `steps`, `summary`                                              |
-| `unfund_piece_3`      | `agent description`, `moves`, `steps`, `summary`                                              |
-| `create`              | `agent description`, `moves`, `steps`, `summary`                                              |
-| `fund_piece_1`        | `agent description`, `moves`, `steps`, `summary`                                              |
-| `release_name`        | `agent description`, `deadline`, `description`, `input`, `moves`, `port`, `steps`, `summary`  |
-| `release_on_deadline` | `due`, `moves`, `steps`, `summary`                                                            |
-| `cancel`              | `agent description`, `deadline`, `moves`, `steps`, `summary`                                  |
-| `fund_piece_2`        | `agent description`, `moves`, `steps`, `summary`                                              |
-| `release_piece_2`     | `agent description`, `moves`, `steps`, `summary`                                              |
-| `unfund_piece_1`      | `agent description`, `moves`, `steps`, `summary`                                              |
-| `fund_piece_2`        | `agent description`, `moves`, `steps`, `summary`                                              |
-| `release_piece_2`     | `agent description`, `moves`, `steps`, `summary`                                              |
-| `refund_piece_2`      | `agent description`, `moves`, `steps`, `summary`                                              |
-| `unfund_piece_1`      | `agent description`, `moves`, `steps`, `summary`                                              |
-| `abandon`             | `agent description`, `moves`, `steps`, `summary`                                              |
-| `create`              | `agent description`, `moves`, `steps`, `summary`                                              |
-| `fund`                | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                     |
-| `release_action`      | `agent description`, `deadline`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
-| `release_on_deadline` | `due`, `event name`, `moves`, `steps`, `summary`                                              |
-| `cancel`              | `agent description`, `deadline`, `event name`, `moves`, `steps`, `summary`                    |
-| `abandon`             | `agent description`, `moves`, `steps`, `summary`                                              |
+| Action                | Clauses lowered                                                                                        |
+| --------------------- | ------------------------------------------------------------------------------------------------------ |
+| `fund_piece_2`        | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
+| `fund_piece_3`        | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
+| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `release_piece_2`     | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `release_piece_3`     | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `refund_piece_2`      | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `refund_piece_3`      | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `unfund_piece_1`      | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `unfund_piece_2`      | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `unfund_piece_3`      | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `create`              | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `fund_piece_1`        | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
+| `release_name`        | `agent description`, `deadline`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `release_on_deadline` | `due`, `moves`, `steps`, `summary`                                                                     |
+| `cancel`              | `agent description`, `deadline`, `moves`, `steps`, `summary`                                           |
+| `fund_piece_2`        | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
+| `release_piece_2`     | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `unfund_piece_1`      | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `fund_piece_2`        | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
+| `release_piece_2`     | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `refund_piece_2`      | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `unfund_piece_1`      | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `abandon`             | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `dispute`             | `agent description`, `deadline`, `description`, `moves`, `steps`, `summary`                            |
+| `resume`              | `agent description`, `description`, `moves`, `steps`, `summary`                                        |
+| `create`              | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `fund`                | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
+| `release_action`      | `agent description`, `deadline`, `moves`, `port`, `sandbox failure point`, `steps`, `summary`          |
+| `release_on_deadline` | `due`, `event name`, `moves`, `steps`, `summary`                                                       |
+| `cancel`              | `agent description`, `deadline`, `event name`, `moves`, `steps`, `summary`                             |
+| `abandon`             | `agent description`, `moves`, `steps`, `summary`                                                       |
+| `dispute`             | `agent description`, `deadline`, `description`, `moves`, `steps`, `summary`                            |
+| `resume`              | `agent description`, `description`, `moves`, `steps`, `summary`                                        |
 
 # instant_transfer
 
-Source: [`std/settlements/instant_transfer.hsx`](../../../std/settlements/instant_transfer.hsx)
+Source: [`std/money_flows/instant_transfer.hsx`](../../../std/money_flows/instant_transfer.hsx)
 
 ## Export
 
@@ -1249,16 +1532,16 @@ None.
 
 ## Actions and clauses
 
-| Action                | Clauses lowered                                  |
-| --------------------- | ------------------------------------------------ |
-| `create`              | `agent description`, `moves`, `steps`, `summary` |
-| `pay_piece_1`         | `agent description`, `moves`, `steps`, `summary` |
-| `pay_piece_2`         | `agent description`, `moves`, `steps`, `summary` |
-| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary` |
+| Action                | Clauses lowered                                                           |
+| --------------------- | ------------------------------------------------------------------------- |
+| `create`              | `agent description`, `moves`, `steps`, `summary`                          |
+| `pay_piece_1`         | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `pay_piece_2`         | `agent description`, `moves`, `steps`, `summary`                          |
+| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary`                          |
 
 # metered
 
-Source: [`std/settlements/metered.hsx`](../../../std/settlements/metered.hsx)
+Source: [`std/money_flows/metered.hsx`](../../../std/money_flows/metered.hsx)
 
 ## Export
 
@@ -1284,7 +1567,7 @@ None.
 
 # pooled_split
 
-Source: [`std/settlements/pooled_split.hsx`](../../../std/settlements/pooled_split.hsx)
+Source: [`std/money_flows/pooled_split.hsx`](../../../std/money_flows/pooled_split.hsx)
 
 ## Export
 
@@ -1309,7 +1592,7 @@ None.
 
 # premium_forward
 
-Source: [`std/settlements/premium_forward.hsx`](../../../std/settlements/premium_forward.hsx)
+Source: [`std/money_flows/premium_forward.hsx`](../../../std/money_flows/premium_forward.hsx)
 
 ## Export
 
@@ -1333,21 +1616,21 @@ Source: [`std/settlements/premium_forward.hsx`](../../../std/settlements/premium
 
 ## Actions and clauses
 
-| Action            | Clauses lowered                                                                          |
-| ----------------- | ---------------------------------------------------------------------------------------- |
-| `create`          | `agent description`, `steps`, `summary`                                                  |
-| `fund_piece_1`    | `agent description`, `moves`, `steps`, `summary`                                         |
-| `fund_piece_2`    | `agent description`, `moves`, `steps`, `summary`                                         |
-| `bind`            | `agent description`, `description`, `input`, `moves`, `port`, `steps`, `summary`         |
-| `forward_piece_2` | `agent description`, `moves`, `steps`, `summary`                                         |
-| `unfund_piece_1`  | `agent description`, `moves`, `steps`, `summary`                                         |
-| `abandon`         | `agent description`, `steps`, `summary`                                                  |
-| `endorsement`     | `agent description`, `capture input`, `description`, `input`, `port`, `steps`, `summary` |
-| `lapse`           | `due`, `steps`, `summary`                                                                |
+| Action            | Clauses lowered                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| `create`          | `agent description`, `steps`, `summary`                                                    |
+| `fund_piece_1`    | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                  |
+| `fund_piece_2`    | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                  |
+| `bind`            | `agent description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `forward_piece_2` | `agent description`, `moves`, `steps`, `summary`                                           |
+| `unfund_piece_1`  | `agent description`, `moves`, `steps`, `summary`                                           |
+| `abandon`         | `agent description`, `steps`, `summary`                                                    |
+| `endorsement`     | `agent description`, `capture input`, `input`, `port`, `steps`, `summary`                  |
+| `lapse`           | `due`, `steps`, `summary`                                                                  |
 
 # reconciled_payout
 
-Source: [`std/settlements/reconciled_payout.hsx`](../../../std/settlements/reconciled_payout.hsx)
+Source: [`std/money_flows/reconciled_payout.hsx`](../../../std/money_flows/reconciled_payout.hsx)
 
 ## Export
 
@@ -1379,7 +1662,7 @@ None.
 
 # recurring_collection
 
-Source: [`std/settlements/recurring_collection.hsx`](../../../std/settlements/recurring_collection.hsx)
+Source: [`std/money_flows/recurring_collection.hsx`](../../../std/money_flows/recurring_collection.hsx)
 
 ## Export
 
@@ -1403,7 +1686,7 @@ None.
 
 # rotating_pool
 
-Source: [`std/settlements/rotating_pool.hsx`](../../../std/settlements/rotating_pool.hsx)
+Source: [`std/money_flows/rotating_pool.hsx`](../../../std/money_flows/rotating_pool.hsx)
 
 ## Export
 
@@ -1444,7 +1727,7 @@ None.
 
 # scheduled
 
-Source: [`std/settlements/scheduled.hsx`](../../../std/settlements/scheduled.hsx)
+Source: [`std/money_flows/scheduled.hsx`](../../../std/money_flows/scheduled.hsx)
 
 ## Export
 
@@ -1475,26 +1758,26 @@ Source: [`std/settlements/scheduled.hsx`](../../../std/settlements/scheduled.hsx
 
 ## Actions and clauses
 
-| Action              | Clauses lowered                                                                                   |
-| ------------------- | ------------------------------------------------------------------------------------------------- |
-| `create`            | `agent description`, `steps`, `summary`                                                           |
-| `create`            | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `approve`           | `agent description`, `steps`, `summary`                                                           |
-| `advance`           | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `delinquent_action` | `due`, `sets at`, `steps`, `summary`                                                              |
-| `complete`          | `due`, `steps`, `summary`                                                                         |
-| `write_off`         | `agent description`, `steps`, `summary`                                                           |
-| `create`            | `agent description`, `steps`, `summary`                                                           |
-| `repay`             | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `refund`            | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `create`            | `agent description`, `steps`, `summary`                                                           |
-| `open_period`       | `due`, `steps`, `summary`                                                                         |
-| `collect_period`    | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `until`             | `agent description`, `capture input`, `description`, `input`, `port`, `steps`, `summary`          |
+| Action              | Clauses lowered                                                                                                            |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `create`            | `agent description`, `steps`, `summary`                                                                                    |
+| `create`            | `agent description`, `moves`, `steps`, `summary`                                                                           |
+| `approve`           | `agent description`, `steps`, `summary`                                                                                    |
+| `advance`           | `agent description`, `moves`, `steps`, `summary`                                                                           |
+| `delinquent_action` | `due`, `sets at`, `steps`, `summary`                                                                                       |
+| `complete`          | `due`, `steps`, `summary`                                                                                                  |
+| `write_off`         | `agent description`, `steps`, `summary`                                                                                    |
+| `create`            | `agent description`, `steps`, `summary`                                                                                    |
+| `repay`             | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary`                          |
+| `refund`            | `agent description`, `moves`, `steps`, `summary`                                                                           |
+| `create`            | `agent description`, `steps`, `summary`                                                                                    |
+| `open_period`       | `due`, `steps`, `summary`                                                                                                  |
+| `collect_period`    | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `until`             | `agent description`, `capture input`, `input`, `port`, `steps`, `summary`                                                  |
 
 # security_deposit
 
-Source: [`std/settlements/security_deposit.hsx`](../../../std/settlements/security_deposit.hsx)
+Source: [`std/money_flows/security_deposit.hsx`](../../../std/money_flows/security_deposit.hsx)
 
 ## Export
 
@@ -1524,22 +1807,22 @@ Source: [`std/settlements/security_deposit.hsx`](../../../std/settlements/securi
 
 ## Actions and clauses
 
-| Action          | Clauses lowered                                                                                                  |
-| --------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `create`        | `agent description`, `moves`, `steps`, `summary`                                                                 |
-| `place_deposit` | `agent description`, `moves`, `steps`, `summary`                                                                 |
-| `claim_name`    | `agent description`, `description`, `input`, `moves`, `port`, `steps`, `summary`                                 |
-| `return_name`   | `agent description`, `moves`, `steps`, `summary`                                                                 |
-| `create`        | `agent description`, `deadline`, `moves`, `steps`, `summary`                                                     |
-| `fund`          | `agent description`, `deadline`, `moves`, `sandbox failure point`, `steps`, `summary`                            |
-| `claim`         | `agent description`, `capture input`, `deadline`, `decided amount`, `input`, `moves`, `port`, `steps`, `summary` |
-| `return`        | `agent description`, `deadline`, `moves`, `port`, `steps`, `summary`                                             |
-| `expire`        | `due`, `moves`, `steps`, `summary`                                                                               |
-| `cancel`        | `agent description`, `moves`, `steps`, `summary`                                                                 |
+| Action          | Clauses lowered                                                                                                                           |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `create`        | `agent description`, `moves`, `steps`, `summary`                                                                                          |
+| `place_deposit` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                                                                 |
+| `claim_name`    | `agent description`, `input`, `moves`, `port`, `steps`, `summary`                                                                         |
+| `return_name`   | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary`                                                        |
+| `create`        | `agent description`, `deadline`, `moves`, `steps`, `summary`                                                                              |
+| `fund`          | `agent description`, `deadline`, `moves`, `sandbox failure point`, `steps`, `summary`                                                     |
+| `claim`         | `agent description`, `capture input`, `deadline`, `decided amount`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `return`        | `agent description`, `deadline`, `moves`, `port`, `steps`, `summary`                                                                      |
+| `expire`        | `due`, `moves`, `steps`, `summary`                                                                                                        |
+| `cancel`        | `agent description`, `moves`, `steps`, `summary`                                                                                          |
 
 # settlement_batch
 
-Source: [`std/settlements/settlement_batch.hsx`](../../../std/settlements/settlement_batch.hsx)
+Source: [`std/money_flows/settlement_batch.hsx`](../../../std/money_flows/settlement_batch.hsx)
 
 ## Export
 
@@ -1580,7 +1863,7 @@ Source: [`std/settlements/settlement_batch.hsx`](../../../std/settlements/settle
 
 # swap
 
-Source: [`std/settlements/swap.hsx`](../../../std/settlements/swap.hsx)
+Source: [`std/money_flows/swap.hsx`](../../../std/money_flows/swap.hsx)
 
 ## Export
 
@@ -1606,26 +1889,26 @@ Source: [`std/settlements/swap.hsx`](../../../std/settlements/swap.hsx)
 
 ## Actions and clauses
 
-| Action    | Clauses lowered                                                                                                             |
-| --------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `abandon` | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
-| `cancel`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
-| `create`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
-| `dispute` | `agent description`, `deadline`, `moves`, `port`, `public action`, `steps`, `summary`                                       |
-| `fund`    | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
-| `post`    | `due`, `moves`, `steps`, `summary`                                                                                          |
-| `release` | `agent description`, `moves`, `port`, `public action`, `sets at`, `steps`, `summary`                                        |
-| `create`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                           |
-| `fund`    | `agent description`, `event name`, `moves`, `public action`, `sandbox failure point`, `steps`, `summary`                    |
-| `release` | `agent description`, `event name`, `moves`, `port`, `public action`, `sandbox failure point`, `sets at`, `steps`, `summary` |
-| `post`    | `due`, `event name`, `moves`, `steps`, `summary`                                                                            |
-| `dispute` | `agent description`, `deadline`, `event name`, `moves`, `port`, `public action`, `steps`, `summary`                         |
-| `cancel`  | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary`                                             |
-| `abandon` | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary`                                             |
+| Action    | Clauses lowered                                                                                                               |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `abandon` | `agent description`, `moves`, `public action`, `steps`, `summary`                                                             |
+| `cancel`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                             |
+| `create`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                             |
+| `dispute` | `agent description`, `capture input`, `deadline`, `input`, `moves`, `port`, `public action`, `steps`, `summary`               |
+| `fund`    | `agent description`, `moves`, `public action`, `sandbox failure point`, `steps`, `summary`                                    |
+| `post`    | `due`, `moves`, `steps`, `summary`                                                                                            |
+| `release` | `agent description`, `moves`, `port`, `public action`, `sandbox failure point`, `sets at`, `steps`, `summary`                 |
+| `create`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                             |
+| `fund`    | `agent description`, `event name`, `moves`, `public action`, `sandbox failure point`, `steps`, `summary`                      |
+| `release` | `agent description`, `event name`, `moves`, `port`, `public action`, `sandbox failure point`, `sets at`, `steps`, `summary`   |
+| `post`    | `due`, `event name`, `moves`, `steps`, `summary`                                                                              |
+| `dispute` | `agent description`, `capture input`, `deadline`, `event name`, `input`, `moves`, `port`, `public action`, `steps`, `summary` |
+| `cancel`  | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary`                                               |
+| `abandon` | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary`                                               |
 
 # threshold_pool
 
-Source: [`std/settlements/threshold_pool.hsx`](../../../std/settlements/threshold_pool.hsx)
+Source: [`std/money_flows/threshold_pool.hsx`](../../../std/money_flows/threshold_pool.hsx)
 
 ## Export
 
@@ -1671,7 +1954,7 @@ None.
 
 # weighted_distribution
 
-Source: [`std/settlements/weighted_distribution.hsx`](../../../std/settlements/weighted_distribution.hsx)
+Source: [`std/money_flows/weighted_distribution.hsx`](../../../std/money_flows/weighted_distribution.hsx)
 
 ## Export