@hyperscale0/udl 1.0.0-beta.1 → 1.0.0

package/docs/reference/clauses.md

@@ -0,0 +1,986 @@
+<!-- Generated by scripts/docs/build.ts from @hyperscale0/udl 1.0.0. Edit the source, not clauses.md. -->
+
+# Clause reference
+
+This page lists every entry in `udlClauseVocabulary`. The examples are copied from admitted documents under `conformance/valid`.
+
+## agent description
+
+- Scope: action
+- UDL target: `agentDescription`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `agent-description.udl`
+
+```json
+"Close a note that has already been filed. Takes the note id and nothing else, and moves no money."
+```
+
+## capture input
+
+- Scope: action
+- UDL target: `captureInput`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+{
+  "snapshotEvidenceReference": "evidenceReference"
+}
+```
+
+## commit
+
+- Scope: action
+- UDL target: `commit`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `commerce-escrow.udl`
+
+A commit has no separate effect row. The committing action consumes the quote through its `moves.*` row.
+
+```json
+"quote"
+```
+
+## quote
+
+- Scope: action
+- UDL target: `quote`
+- Cardinality: one
+- Linear outputs: `netRef`
+- Effects: holds.quote per clause; schedules.expiry per clause
+- Law: Requirements-as-data law and closure law
+- Conformance source: `commerce-escrow.udl`
+
+```json
+{
+  "baseField": "amount",
+  "chargeRef": "unwindPenalty",
+  "charges": [
+    {
+      "bps": 0
+    }
+  ],
+  "expires": {
+    "offset": "PT15M"
+  },
+  "fixes": ["amount", "buyerAccountId"],
+  "netDestinationField": "buyerAccountId",
+  "netRef": "unwindRefund"
+}
+```
+
+## decided amount
+
+- Scope: action
+- UDL target: `decidedAmount`
+- Cardinality: one
+- Linear outputs: `field`
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `compiled-watch-club.udl`
+
+```json
+{
+  "boundField": "depositAmount",
+  "field": "damageAmount",
+  "remainderAction": "return_deposit"
+}
+```
+
+## deadline
+
+- Scope: action
+- UDL target: `deadline`
+- Cardinality: one
+- Linear outputs: none
+- Effects: schedules.deadline per clause
+- Law: Time law and closure law
+- Conformance source: `compiled-watch-club.udl`
+
+```json
+{
+  "field": "clawbackAt"
+}
+```
+
+## decision
+
+- Scope: action
+- UDL target: `decision`
+- Cardinality: one
+- Linear outputs: none
+- Effects: decides.value from capability per clause
+- Law: Requirements-as-data law and closure law
+- Conformance source: `cards.udl`
+
+```json
+{
+  "capability": "banking_or_card_issuing",
+  "deadlineMs": 1500,
+  "onTimeout": "decline"
+}
+```
+
+## computes distribute
+
+- Scope: action
+- UDL target: `distribute`
+- Cardinality: one
+- Linear outputs: `amountRef`
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+{
+  "amountRef": "payoutShare",
+  "onZero": "skip_steps",
+  "pool": {
+    "from": "parent",
+    "path": "fields.distributableAmount"
+  },
+  "refField": "repaymentDistributionId",
+  "statuses": ["recorded", "paid"],
+  "weightField": "committedWeight"
+}
+```
+
+## description
+
+- Scope: action
+- UDL target: `description`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: One-sentence law, uniform object law, and naming law
+- Conformance source: `cards.udl`
+
+```json
+"Approves the customer to hold and use cards."
+```
+
+## due
+
+- Scope: action
+- UDL target: `due`
+- Cardinality: one
+- Linear outputs: none
+- Effects: schedules.due per clause
+- Law: Time law and closure law
+- Conformance source: `cards.udl`
+
+```json
+{
+  "field": "expiresAt"
+}
+```
+
+## earnable
+
+- Scope: action
+- UDL target: `earnable`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `cards.udl`
+
+```json
+true
+```
+
+## event name
+
+- Scope: action
+- UDL target: `eventName`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Event law and naming law
+- Conformance source: `cards.udl`
+
+```json
+"card.issued"
+```
+
+## examples
+
+- Scope: action
+- UDL target: `examples`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `cards.udl`
+
+```json
+[
+  {
+    "input": {
+      "cardholderId": "chd_sandbox_customer0001",
+      "tenantId": "ten_sandbox_cards000001"
+    },
+    "name": "activate_approved_cardholder"
+  }
+]
+```
+
+## input
+
+- Scope: action
+- UDL target: `input`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `cards.udl`
+
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "reason": {
+      "maxLength": 180,
+      "minLength": 1,
+      "type": "string"
+    }
+  },
+  "required": ["reason"],
+  "type": "object"
+}
+```
+
+## moves
+
+- Scope: action
+- UDL target: `moves`
+- Cardinality: many
+- Linear outputs: none
+- Effects: moves.movement class per element; holds.reserve per element
+- Law: One-spine law and closure law
+- Conformance source: `agent-description.udl`
+
+```json
+[]
+```
+
+## payout
+
+- Scope: action
+- UDL target: `payout`
+- Cardinality: one
+- Linear outputs: none
+- Effects: moves.payout.external per clause
+- Law: One-spine law and closure law
+- Conformance source: `compiled-watch-club.udl`
+
+```json
+{
+  "amount": "refs.netPayable",
+  "beneficiaryField": "payoutBeneficiaryId",
+  "beneficiaryPartyField": "payoutDestinationAccountId",
+  "capture": "payoutId",
+  "currencyField": "currency",
+  "sourceAccountField": "clubAccountId",
+  "speed": "standard"
+}
+```
+
+## port
+
+- Scope: action
+- UDL target: `port`
+- Cardinality: one
+- Linear outputs: none
+- Effects: decides.tenant_port per clause
+- Law: Requirements-as-data law and closure law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+{
+  "allowedParties": ["beneficiary"]
+}
+```
+
+## principal
+
+- Scope: action
+- UDL target: `principal`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `complete-contract.udl`
+
+```json
+"user_session"
+```
+
+## public action
+
+- Scope: action
+- UDL target: `publicAction`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Event law and naming law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+"abandonLenderCommitment"
+```
+
+## reconcile
+
+- Scope: action
+- UDL target: `reconcile`
+- Cardinality: many
+- Linear outputs: none
+- Effects: reads.reconcile per element
+- Law: Requirements-as-data law and closure law
+- Conformance source: `compiled-watch-club.udl`
+
+`exception.amountField` must name a required money field on the exception child. `exception.reasonField` must name a required text field on that child. UDL evolution supplies no default for either name.
+
+```json
+[
+  {
+    "amount": "refs.netPayable",
+    "capture": "settlementEvidenceId",
+    "counterpartyRef": "payoutId",
+    "currencyField": "currency",
+    "direction": "debit",
+    "evidence": "statement_line",
+    "exception": {
+      "amountField": "amount",
+      "childInstrumentId": "seller_payout_debit_adjustment",
+      "maxOpen": 1,
+      "reasonField": "adjustmentReference",
+      "refField": "sellerPayoutId"
+    },
+    "match": {
+      "law": "exact"
+    },
+    "within": {
+      "offset": "P30D"
+    }
+  }
+]
+```
+
+## computes remainder
+
+- Scope: action
+- UDL target: `remainder`
+- Cardinality: one
+- Linear outputs: `amountRef`
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `complete-contract.udl`
+
+```json
+{
+  "amountRef": "remainingAmount",
+  "onZero": "refuse",
+  "totalPath": "fields.amount"
+}
+```
+
+## requires aggregate
+
+- Scope: action
+- UDL target: `requiresAggregate`
+- Cardinality: many
+- Linear outputs: none
+- Effects: reads.requires_aggregate per clause
+- Law: Requirements-as-data law and closure law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+[
+  {
+    "check": {
+      "amountField": "amount",
+      "kind": "sum_exactly",
+      "targetField": "installment1Amount"
+    },
+    "instrumentId": "borrower_loan_installment_1_payment",
+    "over": "children",
+    "refField": "borrowerLoanId",
+    "statuses": ["paid"]
+  }
+]
+```
+
+## requires checks
+
+- Scope: action
+- UDL target: `requiresChecks`
+- Cardinality: many
+- Linear outputs: none
+- Effects: reads.requires_checks per clause
+- Law: Requirements-as-data law and closure law
+- Conformance source: `complete-contract.udl`
+
+```json
+[
+  {
+    "checkKind": "identity_verification",
+    "family": "national_identity",
+    "maxAge": "P30D",
+    "statuses": ["completed"],
+    "subjectField": "subjectId"
+  }
+]
+```
+
+## requires drained
+
+- Scope: action
+- UDL target: `requiresDrainedAccount`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `commerce-escrow.udl`
+
+```json
+{
+  "path": "refs.escrowAccountId"
+}
+```
+
+## requires exposure
+
+- Scope: action
+- UDL target: `requiresExposure`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+[
+  {
+    "amountField": "amount",
+    "anchorField": "borrowerLoanId",
+    "capField": "installment1Amount",
+    "capOnAnchor": true,
+    "childInstrumentId": "borrower_loan_installment_1_payment",
+    "statuses": ["paid"]
+  }
+]
+```
+
+## requires refs
+
+- Scope: action
+- UDL target: `requiresRefs`
+- Cardinality: many
+- Linear outputs: none
+- Effects: reads.requires_refs per clause
+- Law: Requirements-as-data law and closure law
+- Conformance source: `cards.udl`
+
+```json
+[
+  {
+    "field": "cardholderId",
+    "statuses": ["active"]
+  }
+]
+```
+
+## sandbox failure point
+
+- Scope: action
+- UDL target: `sandboxFailurePoint`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `commerce-escrow.udl`
+
+```json
+"funding"
+```
+
+## sets at
+
+- Scope: action
+- UDL target: `setsAt`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Time law and closure law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+{
+  "field": "installment1DelinquentAfter",
+  "marker": true,
+  "offset": "PT1S"
+}
+```
+
+## computes signed_sum
+
+- Scope: action
+- UDL target: `signedSum`
+- Cardinality: one
+- Linear outputs: `amountRef`
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `compiled-watch-club.udl`
+
+```json
+{
+  "amountRef": "netPayable",
+  "onNegative": "refuse",
+  "onZero": "refuse",
+  "sources": [
+    {
+      "amountField": "amount",
+      "instrumentId": "seller_payout_capture_entry",
+      "refField": "sellerPayoutId",
+      "sign": "add",
+      "statuses": ["accrued"],
+      "subtotalRef": "grossCaptureAmount"
+    },
+    {
+      "amountField": "amount",
+      "instrumentId": "seller_payout_credit_adjustment",
+      "refField": "sellerPayoutId",
+      "sign": "add",
+      "statuses": ["applied"],
+      "subtotalRef": "creditAdjustmentAmount"
+    },
+    {
+      "amountField": "amount",
+      "instrumentId": "seller_payout_debit_adjustment",
+      "refField": "sellerPayoutId",
+      "sign": "subtract",
+      "statuses": ["applied"],
+      "subtotalRef": "debitAdjustmentAmount"
+    }
+  ]
+}
+```
+
+## steps
+
+- Scope: action
+- UDL target: `steps`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: One-spine law and closure law
+- Conformance source: `agent-description.udl`
+
+```json
+[]
+```
+
+## summary
+
+- Scope: action
+- UDL target: `summary`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: One-sentence law, uniform object law, and naming law
+- Conformance source: `agent-description.udl`
+
+```json
+"Close the note."
+```
+
+## updates
+
+- Scope: action
+- UDL target: `updates`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `commerce-escrow.udl`
+
+```json
+["escrowOrderId"]
+```
+
+## notify
+
+- Scope: action
+- UDL target: `effects.notifies`
+- Cardinality: many
+- Linear outputs: none
+- Effects: notifies.value from channel per element
+- Law: Requirements-as-data law and closure law
+- Conformance source: `effect-signatures.udl`
+
+```json
+[
+  {
+    "channel": "email",
+    "role": "beneficiary",
+    "signature": "notifies.email",
+    "source": "effects.notifies[0]"
+  }
+]
+```
+
+## agent description
+
+- Scope: instrument
+- UDL target: `agentDescription`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `agent-description.udl`
+
+```json
+"Close a note that has already been filed. Takes the note id and nothing else, and moves no money."
+```
+
+## aggregate invariants
+
+- Scope: instrument
+- UDL target: `aggregateInvariants`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: Closure law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+[
+  {
+    "childField": "amount",
+    "childInstrumentId": "borrower_loan_installment_1_payment",
+    "childRefField": "borrowerLoanId",
+    "childStatuses": ["paid"],
+    "parentField": "installment1Amount"
+  },
+  {
+    "childField": "amount",
+    "childInstrumentId": "borrower_loan_installment_2_payment",
+    "childRefField": "borrowerLoanId",
+    "childStatuses": ["paid"],
+    "parentField": "installment2Amount"
+  }
+]
+```
+
+## caller parked states
+
+- Scope: instrument
+- UDL target: `callerParkedStates`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Time law and closure law
+- Conformance source: `cards.udl`
+
+```json
+{
+  "active": "a cardholder in good standing stays active until the issuer or holder acts",
+  "pending": "activation follows the issuer's verification outcome",
+  "suspended": "reinstatement or closure is an issuer decision"
+}
+```
+
+## description
+
+- Scope: instrument
+- UDL target: `description`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: One-sentence law, uniform object law, and naming law
+- Conformance source: `cards.udl`
+
+```json
+"Approves the customer to hold and use cards."
+```
+
+## dials
+
+- Scope: instrument
+- UDL target: `dials`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: Requirements-as-data law and closure law
+- Conformance source: `cards.udl`
+
+```json
+[
+  {
+    "field": "expiresAt",
+    "key": "authorization_window",
+    "kind": "window",
+    "maxOffset": "P30D",
+    "summary": "Grace beyond the authorization expiry timestamp before an uncaptured hold expires.",
+    "title": "Authorization window"
+  },
+  {
+    "action": "approve",
+    "key": "policy_decision_deadline_ms",
+    "kind": "decision_deadline_ms",
+    "maxMs": 5000,
+    "minMs": 500,
+    "summary": "How long approve waits for the card policy's just-in-time decision before the timeout default declines.",
+    "title": "Policy decision deadline"
+  }
+]
+```
+
+## distinct parties
+
+- Scope: instrument
+- UDL target: `distinctParties`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Closure law
+- Conformance source: `compiled-watch-club.udl`
+
+```json
+true
+```
+
+## computes derived
+
+- Scope: instrument
+- UDL target: `derivedAmounts`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: One-spine law and closure law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+[
+  {
+    "field": "platformFee",
+    "rounding": "floor",
+    "rule": {
+      "bps": 200,
+      "kind": "percentage_of"
+    },
+    "sourceField": "principalAmount"
+  }
+]
+```
+
+## computes fees
+
+- Scope: instrument
+- UDL target: `feeRules`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: One-spine law and closure law
+- Conformance source: `compiled-watch-club.udl`
+
+```json
+[
+  {
+    "amountField": "checkoutFee",
+    "baseField": "purchasePrice",
+    "bearerField": "memberAccountId",
+    "position": "on_top",
+    "rule": {
+      "currencyField": "currency",
+      "field": "checkoutFee",
+      "kind": "exact"
+    }
+  },
+  {
+    "amountField": "carvedFeeAmount",
+    "baseField": "purchasePrice",
+    "bearerField": "sellerAccountId",
+    "position": "carved",
+    "rule": {
+      "kind": "tiered",
+      "tiers": [
+        {
+          "fromInclusive": "0",
+          "rule": {
+            "bps": 100,
+            "kind": "bps"
+          },
+          "toExclusive": "10000"
+        },
+        {
+          "fromInclusive": "10000",
+          "rule": {
+            "currencyField": "currency",
+            "field": "highValueFee",
+            "kind": "exact"
+          }
+        }
+      ]
+    }
+  }
+]
+```
+
+## id prefix
+
+- Scope: instrument
+- UDL target: `idPrefix`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: One-sentence law, uniform object law, and naming law
+- Conformance source: `agent-description.udl`
+
+```json
+"note"
+```
+
+## nav
+
+- Scope: instrument
+- UDL target: `nav`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: One-sentence law, uniform object law, and naming law
+- Conformance source: `cards.udl`
+
+```json
+["Blueprints", "Cardholders"]
+```
+
+## partitions
+
+- Scope: instrument
+- UDL target: `partitions`
+- Cardinality: many
+- Linear outputs: none
+- Effects: none
+- Law: One-spine law and closure law
+- Conformance source: `compiled-crowdfunding.udl`
+
+```json
+[
+  {
+    "pieceFields": ["installment1Amount", "installment2Amount"],
+    "totalField": "principalAmount"
+  }
+]
+```
+
+## subject
+
+- Scope: instrument
+- UDL target: `subject`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Closure law
+- Conformance source: `commerce-escrow.udl`
+
+```json
+{
+  "kinds": ["vehicle", "merchandise"]
+}
+```
+
+## summary
+
+- Scope: instrument
+- UDL target: `summary`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: One-sentence law, uniform object law, and naming law
+- Conformance source: `agent-description.udl`
+
+```json
+"Close the note."
+```
+
+## surface visibility
+
+- Scope: instrument
+- UDL target: `surfaceVisibility`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: One-sentence law, uniform object law, and naming law
+- Conformance source: `complete-contract.udl`
+
+```json
+"public"
+```
+
+## template id
+
+- Scope: instrument
+- UDL target: `templateId`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: One-sentence law, uniform object law, and naming law
+- Conformance source: `cards.udl`
+
+```json
+"wallet_cards"
+```
+
+## title
+
+- Scope: instrument
+- UDL target: `title`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: One-sentence law, uniform object law, and naming law
+- Conformance source: `agent-description.udl`
+
+```json
+"Note"
+```
+
+## update
+
+- Scope: instrument
+- UDL target: `update`
+- Cardinality: one
+- Linear outputs: none
+- Effects: none
+- Law: Closure law
+- Conformance source: `cards.udl`
+
+```json
+{
+  "examples": [
+    {
+      "input": {
+        "cardholderId": "chd_sandbox_customer0001",
+        "displayName": "Noura Al Saud",
+        "email": "noura@example.test",
+        "tenantId": "ten_sandbox_cards000001"
+      },
+      "name": "update_cardholder_contact"
+    }
+  ],
+  "fields": ["displayName", "email", "phoneNumber"],
+  "states": ["pending", "active", "suspended"]
+}
+```