@hyperscale0/hsx 1.0.0-alpha.6 → 1.0.0-rc.1

package/examples/04-complete-product/study-hall.hsx

@@ -0,0 +1,67 @@
+// A complete small product: a tutoring marketplace.
+//
+// Three settlements, three different jobs:
+//
+//   lesson       a student's payment is held until the tutor confirms the
+//                lesson happened; the platform's 8% comes out of the payout
+//   kit_deposit  the tutor's equipment deposit is a reservation on the
+//                student's own account, claimed on damage or returned intact
+//   tutor_payout the marketplace's weekly pool, split between the two tutors
+//                who ran the sessions, with the remainder going to the lead
+//
+// Everything a caller can decide goes through a port, and every port names
+// exactly who may answer it.
+
+program study_hall "Study hall"
+
+import { held_payment, security_deposit, pooled_split } from "std/settlements"
+
+party student:     person
+party tutor:       business
+party lead_tutor:  business
+party school:      business
+
+asset lesson_kit: good { title_transfer: on_platform }
+
+settlement lesson = held_payment {
+  payer:   student
+  payee:   tutor
+  amount:  lessonFee: money(SAR)
+  fees { tutor: 8% }
+  release: port confirm_lesson | at(lessonEndsAt)
+}
+
+settlement kit_deposit = security_deposit {
+  payer:  student
+  holder: tutor
+  amount: kitDeposit: money(SAR)
+  claim:  port assess_kit
+  return: port release_kit
+}
+
+settlement tutor_payout = pooled_split {
+  payer:      school
+  amount:     weeklyPool: money(SAR)
+  payout_due: payoutDate
+  split { lead_tutor: 55%, tutor: 45%, remainder_to: lead_tutor }
+}
+
+// The tutor confirms the lesson happened. If nobody answers, `at(lessonEndsAt)`
+// releases the money to the tutor on the stored date: inaction resolves in the
+// direction the parties already agreed on, instead of stranding the payment.
+port confirm_lesson {
+  allowed: [tutor]
+  shape {
+    kitId:       id(lesson_kit)
+    lessonNotes: text
+  }
+}
+
+port assess_kit {
+  allowed: [tutor]
+  shape { damageReport: text }
+}
+
+port release_kit {
+  allowed: [tutor]
+}

package/examples/05-watch-club/README.md

@@ -0,0 +1,9 @@
+# Watch club
+
+This reference program joins the algebra needed for one club product. It keeps
+each watch attached to explicit sale, deposit, and trade rules. Membership due
+dates open periods, while callers still author every money action. Seller
+payouts close through stored provider evidence.
+
+The acceptance proof lives in
+`toolchain/system-tests/test/watch-club.acceptance.spec.ts`.

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
+}