@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0

package/examples/scheduled/README.md

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

package/examples/scheduled/scheduled.hsx

@@ -0,0 +1,12 @@
+program scheduled_example "Scheduled example"
+import { scheduled } from "std/settlements"
+party payer: business
+party payee: business
+settlement installments = scheduled {
+  payer: payer
+  payee: payee
+  amount: totalAmount: money(SAR)
+  count: 3
+  every: P30D
+  first_due: firstDueAt
+}

package/examples/scheduled/scheduled.udl

@@ -0,0 +1,335 @@
+{
+  "instruments": [
+    {
+      "actionOrder": [
+        "create",
+        "pay_installment_1",
+        "pay_installment_2",
+        "pay_installment_3"
+      ],
+      "actions": {
+        "create": {
+          "agentDescription": "Create the installment plan. No money moves. The total and its per-installment amounts are fixed here, and each installment collects on its own stored due date from then on.",
+          "moves": [],
+          "publicAction": "createInstallments",
+          "steps": [],
+          "summary": "Create a installments plan"
+        },
+        "pay_installment_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.installment1Amount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.payeeAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "installments"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "pay_installment_1"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.payerAccountId"
+                }
+              },
+              "capture": {
+                "payInstallment1TransferTransferId": "transferId"
+              },
+              "key": "transfer",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "steps": [],
+          "summary": "Collect installment 1 of 3"
+        },
+        "pay_installment_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.installment2Amount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.payeeAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "installments"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "pay_installment_2"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.payerAccountId"
+                }
+              },
+              "capture": {
+                "payInstallment2TransferTransferId": "transferId"
+              },
+              "key": "transfer",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "steps": [],
+          "summary": "Collect installment 2 of 3"
+        },
+        "pay_installment_3": {
+          "due": {
+            "field": "firstDueAt",
+            "offset": "P60D"
+          },
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              }
+            ],
+            "schedules": [
+              {
+                "signature": "schedules.due",
+                "source": "due"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.installment3Amount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.payeeAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "installments"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "pay_installment_3"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.payerAccountId"
+                }
+              },
+              "capture": {
+                "payInstallment3TransferTransferId": "transferId"
+              },
+              "key": "transfer",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "steps": [],
+          "summary": "Collect installment 3 of 3"
+        }
+      },
+      "agentDescription": "Reach for scheduled when one payer owes one payee on a calendar. It covers a plan of fixed installments partitioning one total, an obligation whose installments are paid through child payment records and can go delinquent, and an open period charge that repeats until a cancel port fires. Rotating pool is for a group taking turns.",
+      "description": "Scheduled payment: the payer pays totalAmount to the payee in 3 installments, one every P30D",
+      "fields": {
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "maxLength": 3,
+          "minLength": 3,
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        },
+        "firstDueAt": {
+          "description": "Due date of the first installment; installment k falls P30D after its predecessor",
+          "format": "hyperscale-date-time",
+          "type": "string"
+        },
+        "installment1Amount": {
+          "description": "Installment 1 of 3 (carries the integer-division remainder): about 33.34% of totalAmount, collected on its own stored-date anchor",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "installment2Amount": {
+          "description": "Installment 2 of 3: about 33.33% of totalAmount, collected on its own stored-date anchor",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "installment3Amount": {
+          "description": "Installment 3 of 3: about 33.33% of totalAmount, collected on its own stored-date anchor",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "payeeAccountId": {
+          "description": "The payee account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        },
+        "payerAccountId": {
+          "description": "The payer account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        },
+        "totalAmount": {
+          "description": "The total scheduled amount in SAR minor units; the installment fields below partition it exactly",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        }
+      },
+      "id": "installments",
+      "idPrefix": "inst",
+      "lifecycle": {
+        "initial": "active",
+        "states": [
+          "active",
+          "collecting_1",
+          "collecting_2",
+          "settled"
+        ],
+        "transitions": {
+          "pay_installment_1": {
+            "from": [
+              "active"
+            ],
+            "to": "collecting_1"
+          },
+          "pay_installment_2": {
+            "from": [
+              "collecting_1"
+            ],
+            "to": "collecting_2"
+          },
+          "pay_installment_3": {
+            "from": [
+              "collecting_2"
+            ],
+            "to": "settled"
+          }
+        }
+      },
+      "parties": {
+        "beneficiary": "payeeAccountId",
+        "payer": "payerAccountId"
+      },
+      "partitions": [
+        {
+          "pieceFields": [
+            "installment1Amount",
+            "installment2Amount",
+            "installment3Amount"
+          ],
+          "totalField": "totalAmount"
+        }
+      ],
+      "required": [
+        "payerAccountId",
+        "payeeAccountId",
+        "totalAmount",
+        "firstDueAt",
+        "installment1Amount",
+        "installment2Amount",
+        "installment3Amount",
+        "currency"
+      ],
+      "summary": "3-installment schedule from payer to payee",
+      "title": "Installments"
+    }
+  ],
+  "product": "scheduled_example",
+  "subjects": [],
+  "title": "Scheduled example",
+  "udl": 1,
+  "version": 1
+}

package/examples/security_deposit/README.md

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

package/examples/security_deposit/security_deposit.hsx

@@ -0,0 +1,21 @@
+program deposit_example "Deposit example"
+import { security_deposit } from "std/settlements"
+party renter: person
+party owner: business
+settlement security_deposit = security_deposit {
+  payer: renter
+  holder: owner
+  amount: depositAmount: money(SAR)
+  claim: port assess_damage
+  claim_amount: decided {
+    field: damageAmount
+    bound: depositAmount
+    remainder: return
+  }
+  return: port return_deposit
+}
+port assess_damage {
+  allowed: [owner]
+  shape: { damageAmount: money(SAR), evidence: text }
+}
+port return_deposit { allowed: [owner] }

package/examples/security_deposit/security_deposit.udl

@@ -0,0 +1,293 @@
+{
+  "instruments": [
+    {
+      "actionOrder": [
+        "create",
+        "place_deposit",
+        "assess_damage",
+        "return_deposit"
+      ],
+      "actions": {
+        "assess_damage": {
+          "agentDescription": "Claim the held deposit for the owner. The deposit must be in held. The reservation settles here, whole or up to the decided amount with the exact remainder released back to the renter. There is no return afterwards.",
+          "decidedAmount": {
+            "boundField": "depositAmount",
+            "field": "damageAmount",
+            "remainderAction": "return_deposit"
+          },
+          "effects": {
+            "decides": [
+              {
+                "signature": "decides.tenant_port",
+                "source": "port"
+              }
+            ],
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              },
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[1]"
+              }
+            ]
+          },
+          "input": {
+            "additionalProperties": false,
+            "properties": {
+              "damageAmount": {
+                "description": "Caller-decided amount in minor units",
+                "pattern": "^(0|[1-9][0-9]{0,17})$",
+                "type": "string"
+              },
+              "evidence": {
+                "description": "Required decision reference retained in the operation receipt",
+                "maxLength": 180,
+                "minLength": 1,
+                "type": "string"
+              }
+            },
+            "required": [
+              "damageAmount",
+              "evidence"
+            ],
+            "type": "object"
+          },
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "input",
+                  "path": "damageAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "postMode": {
+                  "from": "const",
+                  "value": "partial_only"
+                },
+                "transferId": {
+                  "from": "instance",
+                  "path": "refs.placeDepositReservationTransferId"
+                }
+              },
+              "key": "post",
+              "operation": "internal_transfer.post"
+            },
+            {
+              "bind": {
+                "reason": {
+                  "from": "const",
+                  "value": "Return the unclaimed deposit remainder"
+                },
+                "transferId": {
+                  "from": "instance",
+                  "path": "refs.placeDepositReservationTransferId"
+                }
+              },
+              "key": "remainder",
+              "operation": "internal_transfer.void"
+            }
+          ],
+          "port": {
+            "allowedParties": [
+              "beneficiary"
+            ]
+          },
+          "publicAction": "assessDamageSecurityDeposit",
+          "steps": [],
+          "summary": "Claim the deposit for the owner through assess_damage"
+        },
+        "create": {
+          "agentDescription": "Open the deposit row before anything is reserved. The caller supplies the depositAmount, the currency, and the renter and owner accounts. Nothing is reserved yet, call place deposit next.",
+          "moves": [],
+          "publicAction": "createSecurityDeposit",
+          "steps": [],
+          "summary": "Create a security deposit"
+        },
+        "place_deposit": {
+          "agentDescription": "Reserve the depositAmount against the renter's account in the owner's favor. The deposit must be created. The money is held, not paid: the claim posts it to the owner and the return releases it back.",
+          "effects": {
+            "holds": [
+              {
+                "signature": "holds.reserve",
+                "source": "moves[0]"
+              }
+            ],
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.depositAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.ownerAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "security_deposit"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "place_deposit"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.renterAccountId"
+                }
+              },
+              "capture": {
+                "placeDepositReservationTransferId": "transferId"
+              },
+              "key": "reservation",
+              "operation": "internal_transfer.reserve"
+            }
+          ],
+          "publicAction": "placeDepositSecurityDeposit",
+          "steps": [],
+          "summary": "Reserve the depositAmount against the renter's account"
+        },
+        "return_deposit": {
+          "agentDescription": "Return the held deposit to the renter. The deposit must be in held and unclaimed. This releases the reservation whole and the owner receives nothing.",
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "reason": {
+                  "from": "const",
+                  "value": "Deposit returned in full"
+                },
+                "transferId": {
+                  "from": "instance",
+                  "path": "refs.placeDepositReservationTransferId"
+                }
+              },
+              "key": "void",
+              "operation": "internal_transfer.void"
+            }
+          ],
+          "publicAction": "returnDepositSecurityDeposit",
+          "steps": [],
+          "summary": "Return the deposit to the renter through return_deposit"
+        }
+      },
+      "agentDescription": "Reach for security deposit when money is reserved against the renter in the owner's favor and later claimed or returned. The funds stay reserved and move only on the claim. Pick captured payment when the holder takes the money in slices, and instant transfer when nothing is held.",
+      "description": "Deposit: the depositAmount is reserved against the renter's account in the owner's favor, then damageAmount is claimed and the exact remainder returned, or the deposit is returned in full",
+      "fields": {
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "maxLength": 3,
+          "minLength": 3,
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        },
+        "depositAmount": {
+          "description": "The deposit amount in SAR minor units, reserved in full and fully accounted on claim or return",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "ownerAccountId": {
+          "description": "The owner account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        },
+        "renterAccountId": {
+          "description": "The renter account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        }
+      },
+      "id": "security_deposit",
+      "idPrefix": "sd",
+      "lifecycle": {
+        "initial": "created",
+        "states": [
+          "created",
+          "held",
+          "claimed",
+          "returned"
+        ],
+        "transitions": {
+          "assess_damage": {
+            "from": [
+              "held"
+            ],
+            "to": "claimed"
+          },
+          "place_deposit": {
+            "from": [
+              "created"
+            ],
+            "to": "held"
+          },
+          "return_deposit": {
+            "from": [
+              "held"
+            ],
+            "to": "returned"
+          }
+        }
+      },
+      "parties": {
+        "beneficiary": "ownerAccountId",
+        "payer": "renterAccountId"
+      },
+      "required": [
+        "renterAccountId",
+        "ownerAccountId",
+        "depositAmount",
+        "currency"
+      ],
+      "summary": "Refundable deposit from renter held for owner",
+      "title": "Security deposit"
+    }
+  ],
+  "product": "deposit_example",
+  "subjects": [],
+  "title": "Deposit example",
+  "udl": 1,
+  "version": 1
+}

package/examples/settlement_batch/README.md

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