@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0

package/examples/05-watch-club/watch-club.hsx

@@ -0,0 +1,124 @@
+// A watch club whose money rules remain explicit from member checkout through
+// seller payout. Each item owns its sale, deposit, and trade lifecycle. The
+// club membership schedule opens periods but never moves money on a timeout.
+
+program watch_club "Watch club"
+
+import {
+  security_deposit,
+  instant_transfer,
+  recurring_collection,
+  scheduled,
+  settlement_batch,
+  swap
+} from "std/settlements"
+
+party member: person
+party seller: business
+party club: business
+party payout_destination: business
+
+asset watch: good { title_transfer: on_platform }
+
+settlement purchase = instant_transfer {
+  payer: member
+  payee: seller
+  amount: purchasePrice: money(SAR)
+  fees {
+    member: checkoutFee: money(SAR)
+    seller {
+      tier {
+        from: 0
+        to: 10000
+        fee: 1%
+      }
+      tier {
+        from: 10000
+        fee: highValueFee: money(SAR)
+      }
+    }
+  }
+}
+
+settlement inspection_deposit = security_deposit {
+  payer: member
+  holder: seller
+  amount: depositAmount: money(SAR)
+  claim: port assess_watch
+  claim_amount: decided {
+    field: damageAmount
+    bound: depositAmount
+    remainder: return
+  }
+  return: port return_deposit
+}
+
+settlement membership = scheduled {
+  mode: obligation
+  payer: member
+  payee: club
+  debtor: member
+  amount: monthlyFee: money(SAR)
+  every: P1M
+  first_due: firstPeriodAt
+  until: port cancel_membership
+  month_end: clamp_to_last_day
+  period_liability: one_open
+  termination_drain: cancel_membership
+  mandate: port collect_membership
+}
+
+settlement member_trade = swap {
+  between: [member, seller]
+  amounts {
+    member: memberPays: money(SAR)
+    seller: sellerPays: money(SAR)
+  }
+  fees {
+    member: memberTradeFee: money(SAR)
+    seller: sellerTradeFee: money(SAR)
+  }
+  release: port confirm_trade
+  dispute: port resolve_trade within P14D
+}
+
+settlement seller_payout = settlement_batch {
+  settlement_account: club
+  source_capture_refs: captureReference
+  fee_entries: feeReference
+  external_reversal_offsets: externalReversalReference
+  close_trigger: closeAt
+  payout_destination: payout_destination
+  negative_position: reject
+  payout_acknowledgement: port acknowledge_payout
+  payout_beneficiary_ref: payoutBeneficiaryId
+}
+
+port assess_watch {
+  allowed: [seller]
+  shape {
+    damageAmount: money(SAR)
+    evidence: text
+  }
+}
+
+port return_deposit { allowed: [seller] }
+
+port collect_membership {
+  allowed: [member]
+  shape { evidenceReference: text }
+}
+
+port cancel_membership {
+  allowed: [member]
+  shape { reason: text }
+}
+
+port confirm_trade { allowed: [member, seller] }
+
+port resolve_trade { allowed: [member, seller] }
+
+port acknowledge_payout {
+  allowed: [payout_destination]
+  shape { acknowledgementReference: text }
+}

package/examples/README.md

@@ -0,0 +1,18 @@
+# Examples
+
+Each standard-library module has its own directory with an HSX program, a
+short lesson, and pinned canonical UDL bytes. The test suite reads the module
+list from `std/settlements`, compiles every program, and compares each emitted
+document byte for byte.
+
+The numbered examples remain as longer lessons. They cover a first program,
+imports, diagnostic repair, a composed product, and a multi-instrument club.
+
+Run an example with the installed CLI:
+
+```sh
+hsx check examples/instant_transfer/instant_transfer.hsx
+hsx build examples/instant_transfer/instant_transfer.hsx --out program.udl
+```
+
+Every company and person in these files is invented.

package/examples/advance/README.md

@@ -0,0 +1,3 @@
+# advance
+
+This example applies the `advance` standard-library module. Its sibling UDL file pins the canonical compiler output byte for byte. The company and parties are invented.

package/examples/advance/advance.hsx

@@ -0,0 +1,13 @@
+program advance_example "Advance example"
+import { advance } from "std/settlements"
+party funder: business
+party recipient: business
+settlement advance_payment = advance {
+  funder: funder
+  to: recipient
+  amount: principal: money(SAR)
+  fee: 2.5%
+  count: 2
+  every: P30D
+  first_due: firstDueAt
+}

package/examples/advance/advance.udl

@@ -0,0 +1,339 @@
+{
+  "instruments": [
+    {
+      "actionOrder": [
+        "create",
+        "disburse",
+        "collect_repayment_1",
+        "collect_repayment_2"
+      ],
+      "actions": {
+        "collect_repayment_1": {
+          "due": {
+            "field": "firstDueAt"
+          },
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              }
+            ],
+            "schedules": [
+              {
+                "signature": "schedules.due",
+                "source": "due"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.repayment1Amount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.funderAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "advance_payment"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "collect_repayment_1"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.recipientAccountId"
+                }
+              },
+              "capture": {
+                "collectRepayment1TransferTransferId": "transferId"
+              },
+              "key": "transfer",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "steps": [],
+          "summary": "Collect repayment 1 of 2"
+        },
+        "collect_repayment_2": {
+          "due": {
+            "field": "firstDueAt",
+            "offset": "P30D"
+          },
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              }
+            ],
+            "schedules": [
+              {
+                "signature": "schedules.due",
+                "source": "due"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.repayment2Amount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.funderAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "advance_payment"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "collect_repayment_2"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.recipientAccountId"
+                }
+              },
+              "capture": {
+                "collectRepayment2TransferTransferId": "transferId"
+              },
+              "key": "transfer",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "steps": [],
+          "summary": "Collect repayment 2 of 2"
+        },
+        "create": {
+          "agentDescription": "Open the advance row before any money moves. The caller supplies the principal, the fee amount, the repayable total, and the first repayment date. The repayment fields must partition the repayable total exactly. Nothing is disbursed here.",
+          "moves": [],
+          "publicAction": "createAdvancePayment",
+          "steps": [],
+          "summary": "Create a advance payment"
+        },
+        "disburse": {
+          "agentDescription": "Pay the principal from the funder to the recipient and start the repayment schedule. The advance must be created. The transfer posts straight out and does not unwind. Each repayment is collected on its own stored date anchor.",
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.principal"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.recipientAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "advance_payment"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "disburse"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.funderAccountId"
+                }
+              },
+              "capture": {
+                "disburseTransferTransferId": "transferId"
+              },
+              "key": "transfer",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "publicAction": "disburseAdvancePayment",
+          "steps": [],
+          "summary": "Disburse the principal to the recipient"
+        }
+      },
+      "agentDescription": "Reach for advance when the funder pays the recipient up front and is repaid afterwards, either out of a carved hold release or over scheduled repayments. Pick deposit for a refundable reservation and instant transfer when nobody repays the payer.",
+      "description": "Advance: the funder disburses principal to the recipient, repaid over 2 scheduled repayments plus the funder's discount",
+      "fields": {
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "maxLength": 3,
+          "minLength": 3,
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        },
+        "feeAmount": {
+          "description": "2.5% of principal, the funder's discount repaid on top of the advance",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "firstDueAt": {
+          "description": "Due date of the first repayment; repayment k falls P30D after its predecessor",
+          "format": "hyperscale-date-time",
+          "type": "string"
+        },
+        "funderAccountId": {
+          "description": "The funder account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        },
+        "principal": {
+          "description": "The advanced amount in SAR minor units, disbursed to the recipient up front",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "recipientAccountId": {
+          "description": "The recipient account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        },
+        "repayableAmount": {
+          "description": "principal + feeAmount: the total the repayment fields below partition exactly",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "repayment1Amount": {
+          "description": "Repayment 1 of 2 (carries the integer-division remainder): about 33.34% of repayableAmount, collected on its own stored-date anchor",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "repayment2Amount": {
+          "description": "Repayment 2 of 2: about 33.33% of repayableAmount, collected on its own stored-date anchor",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        }
+      },
+      "id": "advance_payment",
+      "idPrefix": "ap",
+      "lifecycle": {
+        "initial": "created",
+        "states": [
+          "created",
+          "advanced",
+          "repaying_1",
+          "repaid"
+        ],
+        "transitions": {
+          "collect_repayment_1": {
+            "from": [
+              "advanced"
+            ],
+            "to": "repaying_1"
+          },
+          "collect_repayment_2": {
+            "from": [
+              "repaying_1"
+            ],
+            "to": "repaid"
+          },
+          "disburse": {
+            "from": [
+              "created"
+            ],
+            "to": "advanced"
+          }
+        }
+      },
+      "parties": {
+        "beneficiary": "recipientAccountId",
+        "payer": "funderAccountId"
+      },
+      "partitions": [
+        {
+          "pieceFields": [
+            "repayment1Amount",
+            "repayment2Amount"
+          ],
+          "totalField": "repayableAmount"
+        },
+        {
+          "pieceFields": [
+            "principal",
+            "feeAmount"
+          ],
+          "totalField": "repayableAmount"
+        }
+      ],
+      "required": [
+        "funderAccountId",
+        "recipientAccountId",
+        "principal",
+        "feeAmount",
+        "repayableAmount",
+        "firstDueAt",
+        "repayment1Amount",
+        "repayment2Amount",
+        "currency"
+      ],
+      "summary": "Advance to recipient repaid over 2 anchors",
+      "title": "Advance payment"
+    }
+  ],
+  "product": "advance_example",
+  "subjects": [],
+  "title": "Advance example",
+  "udl": 1,
+  "version": 1
+}

package/examples/cancellable_booking/README.md

@@ -0,0 +1,3 @@
+# cancellable_booking
+
+This example applies the `cancellable_booking` standard-library module. Its sibling UDL file pins the canonical compiler output byte for byte. The company and parties are invented.

package/examples/cancellable_booking/cancellable_booking.hsx

@@ -0,0 +1,14 @@
+program cancellable_booking_example "Cancellable booking example"
+import { cancellable_booking } from "std/settlements"
+party guest: person
+party studio: business
+settlement studio_session = cancellable_booking {
+  guest: guest
+  host: studio
+  amount: sessionPrice: money(SAR)
+  starts_at: startsAt
+  late_penalty_bps: 5000
+  late_within: P2D
+  early_penalty_bps: 1000
+  offer_life: PT30M
+}