@hyperscale0/hsx 2.4.1 → 3.0.0

package/skills/hsx/SKILL.md

@@ -1,449 +0,0 @@
----
-name: hsx
-description: Write, review, and repair HSX programs that compile financial-product rules to canonical UDL.
----
-
-# Write HSX
-
-Use this skill when a task creates or changes an `.hsx` program, chooses a money flow from the money flows library (open/hsx/std), explains an HSX diagnostic, or reviews authored money rules. Do not use it to hand-edit canonical UDL or runtime state.
-
-## Program shape
-
-One file declares one `program`. Declare parties and assets before using them. Import money flows from `std/money_flows`. Apply each selected instrument as a `settlement`, and declare every decision port it names. A program may also declare general instruments and subjects.
-
-Start with [the first-program guide](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/01-first-program.md). Read the [instruments](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/03-instruments.md), [lifecycles](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/04-lifecycles.md), [composition](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/07-composition.md), and [writing a module](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/08-writing-a-module.md) chapters for instrument architecture. Read the generated [grammar](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/reference/grammar.md), [types](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/reference/types.md), and [money flows reference](https://github.com/hyperscale0/hyperscale-hsx/tree/main/docs/reference/std) for the exact surface.
-
-## Choose a money flow
-
-Choose the module whose lifecycle and money path already match the product. Do not copy its emitted mechanics into a custom instrument.
-
-- `instant_transfer` sends money without custody.
-- `held_payment` holds money until a decision or deadline.
-- `security_deposit` reserves value for a bounded claim or return.
-- `cancellable_booking` quotes a cancellation penalty before commitment.
-- `captured_payment` reserves, captures, settles, voids, or corrects a payment.
-- `scheduled` expands finite installments or a bounded obligation.
-- `advance` disburses now against finite repayment or a referenced release.
-- `credit_facility` controls draws against a referenced obligation.
-- `conditional_disbursement` releases a capped amount on stored evidence.
-- `pooled_split`, `weighted_distribution`, and `rotating_pool` divide bounded pools.
-- `threshold_pool` closes a bounded contribution campaign.
-- `premium_forward` holds and forwards an insurance premium.
-- `reconciled_payout` matches an instructed payout against bank evidence.
-- `metered` commits a finite usage rate card for a period.
-- `settlement_batch` closes, calculates, approves, instructs, acknowledges, and reconciles a batch.
-- `swap` exchanges two independently typed sides.
-
-The money flows are demonstrated below. The marker before each program lets the repository test read the module list from disk and compile one matching example per module.
-
-## Diagnostic loop
-
-Run `hsx check` after each coherent edit. Read the first error code, open the [diagnostics guide](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/10-diagnostics.md) and [diagnostics reference](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/reference/diagnostics.md), apply the catalog fix, and compile again. Match tools on the stable `HSX####` code, not the message. Never patch emitted UDL to bypass a refusal.
-
-## Money rules
-
-- Money uses integer minor units and carries a currency type.
-- Money in different currencies never unifies.
-- Percent literals have basis-point precision.
-- Every percentage partition totals 100 percent.
-- Every computed amount is consumed exactly once.
-- Every held balance drains on each reachable exit.
-- Schedules and comprehensions have compile-time finite bounds.
-- A port supplies typed evidence or a bounded decision. It cannot invent money or a new route.
-
-The [money](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/02-money.md), [fees and splits](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/05-fees-and-splits.md), [schedules](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/06-schedules.md), and [cost](https://github.com/hyperscale0/hyperscale-hsx/blob/main/docs/guide/09-cost.md) chapters explain these rules.
-
-## Money flow witnesses
-
-<!-- hsx-brick: advance -->
-
-```hsx
-program advance_example "Advance example"
-import { advance } from "std/money_flows"
-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
-}
-```
-
-<!-- hsx-brick: cancellable_booking -->
-
-```hsx
-program cancellable_booking_example "Cancellable booking example"
-import { cancellable_booking } from "std/money_flows"
-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
-}
-```
-
-<!-- hsx-brick: captured_payment -->
-
-```hsx
-program captured_payment_example "Captured payment example"
-import { captured_payment } from "std/money_flows"
-party payer: person
-party payee: business
-settlement card_payment = captured_payment {
-  payer: payer
-  payee: payee
-  amount: authorizedAmount: money(SAR)
-  reserve_until: reserveUntil
-  correction: port correct_capture
-  external_reversal: port reverse_capture within P14D
-}
-port correct_capture { allowed: [payee] }
-port reverse_capture {
-  allowed: [payee]
-  shape: { externalReference: text }
-}
-```
-
-<!-- hsx-brick: conditional_disbursement -->
-
-```hsx
-program conditional_disbursement_example "Conditional disbursement example"
-import { conditional_disbursement } from "std/money_flows"
-party source: business
-party claimant: person
-settlement claim_payment = conditional_disbursement {
-  source: source
-  destination: claimant
-  cap: policyLimit: money(SAR)
-  amount: approvedAmount: money(SAR)
-  decision: port approve_claim
-}
-port approve_claim {
-  allowed: [source]
-  shape: { evidenceReference: text }
-}
-```
-
-<!-- hsx-brick: credit_facility -->
-
-```hsx
-program credit_facility_example "Credit facility example"
-import { credit_facility, scheduled } from "std/money_flows"
-party lender: business
-party borrower: business
-party draw_destination: business
-party repayment_source: business
-settlement repayment = scheduled {
-  mode: obligation
-  payer: repayment_source
-  payee: lender
-  debtor: borrower
-  amount: principal: money(SAR)
-  count: 2
-  every: P30D
-  first_due: firstDueAt
-}
-settlement facility = credit_facility {
-  lender: lender
-  borrower: borrower
-  draw_destination: draw_destination
-  limit: facilityLimit: money(SAR)
-  expires_at: expiresAt
-  obligation: repayment.obligation
-}
-```
-
-<!-- hsx-brick: security_deposit -->
-
-```hsx
-program deposit_example "Deposit example"
-import { security_deposit } from "std/money_flows"
-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] }
-```
-
-<!-- hsx-brick: threshold_pool -->
-
-```hsx
-program capital_pool_example "Capital pool example"
-import { threshold_pool } from "std/money_flows"
-party contributor: person
-party company: business
-settlement round = threshold_pool {
-  contributor: contributor
-  beneficiary: company
-  target: targetAmount: money(SAR)
-  commitment: commitmentAmount: money(SAR)
-  max_contributors: 100
-  close_by: closeBy
-  close_policy: threshold
-  overfund_policy: reject
-  cancel_policy: before_close
-  fail_policy: whole_commitment_refund
-}
-```
-
-<!-- hsx-brick: held_payment -->
-
-```hsx
-program held_payment_example "Held payment example"
-import { held_payment } from "std/money_flows"
-party buyer: person
-party seller: business
-settlement sale = held_payment {
-  payer: buyer
-  payee: seller
-  amount: price: money(SAR)
-  fees { buyer: 1% }
-  on_cancel(funded) { buyer: 100% }
-  release: port confirm_delivery | at(releaseDueAt)
-}
-port confirm_delivery { allowed: [buyer] }
-```
-
-<!-- hsx-brick: instant_transfer -->
-
-```hsx
-program instant_transfer_example "Instant transfer example"
-import { instant_transfer } from "std/money_flows"
-party customer: person
-party merchant: business
-settlement transfer = instant_transfer {
-  payer: customer
-  payee: merchant
-  amount: transferAmount: money(SAR)
-  fees {
-    customer: checkoutFee: money(SAR)
-    merchant {
-      tier { from: 0, to: 10000, fee: 1% }
-      tier { from: 10000, fee: highValueFee: money(SAR) }
-    }
-  }
-}
-```
-
-<!-- hsx-brick: metered -->
-
-```hsx
-program metered_example "Metered example"
-import { metered } from "std/money_flows"
-party customer: business
-party provider: business
-settlement usage = metered {
-  payer: customer
-  payee: provider
-  close_by: periodEnd
-  rates {
-    api_call: callRate: money(SAR)
-    storage_gib: storageRate: money(SAR)
-  }
-}
-```
-
-<!-- hsx-brick: pooled_split -->
-
-```hsx
-program pooled_split_example "Pooled split example"
-import { pooled_split } from "std/money_flows"
-party payer: business
-party first_recipient: business
-party second_recipient: business
-settlement pool = pooled_split {
-  payer: payer
-  amount: poolAmount: money(SAR)
-  payout_due: payoutDueAt
-  split {
-    first_recipient: 60%
-    second_recipient: 40%
-    remainder_to: first_recipient
-  }
-}
-```
-
-<!-- hsx-brick: premium_forward -->
-
-```hsx
-program premium_forward_example "Premium forward example"
-import { premium_forward } from "std/money_flows"
-party policyholder: person
-party carrier: business
-settlement premium = premium_forward {
-  payer: policyholder
-  carrier: carrier
-  amount: premiumAmount: money(SAR)
-  commission: 2%
-  bind: port bind_policy
-  policy_ref: policyReference
-  renewal_due: renewalDueAt
-  endorsement: port record_endorsement
-}
-port bind_policy { allowed: [policyholder, carrier] }
-port record_endorsement {
-  allowed: [carrier]
-  shape: { evidenceReference: text }
-}
-```
-
-<!-- hsx-brick: reconciled_payout -->
-
-```hsx
-program reconciled_payout_example "Reconciled payout example"
-import { reconciled_payout } from "std/money_flows"
-party treasury: business
-party supplier: business
-settlement supplier_payout = reconciled_payout {
-  payer: treasury
-  beneficiary: supplier
-  amount: netPayable: money(SAR)
-  beneficiary_ref: supplierBeneficiaryId
-  settle_by: settleBy
-  matched_within: 100
-  matched_ceiling: 500
-}
-```
-
-<!-- hsx-brick: rotating_pool -->
-
-```hsx
-program rotating_pool_example "Rotating pool example"
-import { rotating_pool } from "std/money_flows"
-party member_a: person
-party member_b: person
-party member_c: person
-party guarantor: business
-settlement pool = rotating_pool {
-  members: [member_a, member_b, member_c]
-  contribution: contributionAmount: money(SAR)
-  count: 3
-  every: P30D
-  first_due: firstContributionAt
-  payout_order: [member_b, member_c, member_a]
-  default_policy: due_condition
-  guarantee_policy: funded_only
-  guarantor: guarantor
-  exit_policy: before_activation_only
-}
-```
-
-<!-- hsx-brick: scheduled -->
-
-```hsx
-program scheduled_example "Scheduled example"
-import { scheduled } from "std/money_flows"
-party payer: business
-party payee: business
-settlement installments = scheduled {
-  payer: payer
-  payee: payee
-  amount: totalAmount: money(SAR)
-  count: 3
-  every: P30D
-  first_due: firstDueAt
-}
-```
-
-<!-- hsx-brick: settlement_batch -->
-
-```hsx
-program settlement_batch_example "Settlement batch example"
-import { settlement_batch } from "std/money_flows"
-party settlement_account: business
-party payout_destination: business
-settlement batch = settlement_batch {
-  settlement_account: settlement_account
-  source_capture_refs: captureReference
-  fee_entries: feeReference
-  external_reversal_offsets: reversalReference
-  close_trigger: closeAt
-  payout_destination: payout_destination
-  negative_position: reject
-  payout_acknowledgement: port acknowledge_payout
-  payout_beneficiary_ref: payoutBeneficiaryId
-}
-port acknowledge_payout {
-  allowed: [payout_destination]
-  shape: { acknowledgementReference: text }
-}
-```
-
-<!-- hsx-brick: swap -->
-
-```hsx
-program swap_example "Swap example"
-import { swap } from "std/money_flows"
-party buyer: business
-party seller: business
-settlement exchange = swap {
-  between: [buyer, seller]
-  amounts {
-    buyer: buyerAmount: money(SAR)
-    seller: sellerAmount: money(SAR)
-  }
-  fees {
-    buyer: buyerFee: money(SAR)
-    seller: sellerFee: money(SAR)
-  }
-  release: port release_exchange
-  dispute: port dispute_exchange within P7D
-}
-port release_exchange { allowed: [buyer, seller] }
-port dispute_exchange { allowed: [buyer, seller] }
-```
-
-<!-- hsx-brick: weighted_distribution -->
-
-```hsx
-program weighted_distribution_example "Weighted distribution example"
-import { weighted_distribution } from "std/money_flows"
-party distribution_source: business
-party recipient: business
-settlement proceeds = weighted_distribution {
-  source: distribution_source
-  recipient: recipient
-  amount: distributableAmount: money(SAR)
-  weight: entitlementWeight: money(SAR)
-  max_recipients: 12
-  record_at: recordAt
-  snapshot: port snapshot_entitlements
-  rounding_policy: largest_remainder
-  withholding_policy: refuse
-  correction_policy: new_distribution
-}
-port snapshot_entitlements {
-  allowed: [distribution_source]
-  shape: { evidenceReference: text }
-}
-```
-
-## Output boundary
-
-Use `compile` or the Hyperscale CLI to obtain canonical UDL, the origin map, and the cost manifest. The engine reads UDL and never HSX. When a task needs direct UDL work, use the UDL skill instead.
-
-Programs that `use` published instruments need the selected catalogue when checked outside the engine: `hsx check --strict --catalog catalog.udl company.hsx`. Obtain that canonical UDL from the catalogue publisher. The CLI does not fetch or choose a revision.