@hyperscale0/hsx 1.0.0 → 1.0.124

package/src/std-library.ts

@@ -1,12 +1,7 @@
 import { BUNDLED_STD_FILES } from "./std-bundle.ts";
-
 export interface StandardLibrary {
-  readonly source: (specifier: string, name: string) => string | undefined;
+  source(header: string): string | undefined;
 }
-
 export const bundledStandardLibrary: StandardLibrary = {
-  source(specifier: string, name: string): string | undefined {
-    if (specifier !== "std/settlements") return undefined;
-    return BUNDLED_STD_FILES.get(`settlements/${name}.hsx`);
-  },
+  source: (header) => BUNDLED_STD_FILES.get(`${header}.hsx`),
 };

package/src/tunables.ts

@@ -0,0 +1,36 @@
+import { fail } from "./diagnostics.ts";
+import type { Expr } from "./ast.ts";
+
+/** Bounds use UDL units: minor units, basis points and milliseconds. */
+export function tunableBounds(
+  type: Expr,
+): { minimum: number | string; maximum: number | string } | undefined {
+  const name =
+    type.kind === "call" || type.kind === "type"
+      ? type.name
+      : type.kind === "name"
+        ? type.value
+        : "";
+  if (name === "money") return { minimum: "0", maximum: "999999999999999999" };
+  if (name === "percent") return { minimum: 0, maximum: 10000 };
+  if (name === "duration")
+    return { minimum: 1, maximum: Number.MAX_SAFE_INTEGER };
+  if (name !== "integer") return;
+  if (type.kind === "call") {
+    const numbers = type.args.map((arg) =>
+      arg.kind === "number" ? Number(arg.value) : NaN,
+    );
+    if (
+      numbers.length !== 2 ||
+      numbers.some((value) => !Number.isSafeInteger(value)) ||
+      numbers[0]! > numbers[1]!
+    )
+      fail(
+        type,
+        "integer tunable needs ordered safe integer bounds",
+        "write integer(1, 12)",
+      );
+    return { minimum: numbers[0]!, maximum: numbers[1]! };
+  }
+  return { minimum: 0, maximum: Number.MAX_SAFE_INTEGER };
+}

package/std/cards.hsx

@@ -0,0 +1,85 @@
+header cards
+
+// Activate holder and card before creating and approving an authorization.
+// Expose authorization.create, approve and capture; expose decline and reverse
+// separately if callers need those paths. Issuer declines only from pending;
+// merchant captures or reverses an approved reservation. Expiry voids approved
+// reservations or abandons pending ones; it does not delay a captured refund.
+// Create one transaction for the captured authorization and expose its refund.
+// Refund is available immediately from posted, even before authorization.expiresAt,
+// and moves the whole captured amount from merchant to holder under programOperator.
+// No partial capture, repeated capture or partial transaction refund is provided.
+// Disputes need a posted transaction, issuer review and win before their deadline;
+// win invokes the same refund. The alias never changes the declared action actor.
+
+// Cost: authorization approve, capture and reverse each declare one transfer
+// instruction. Transaction refund declares one transfer; a successful dispute
+// invokes that refund. Card state changes alone declare no transfers.
+
+instrument cardholder(holder: party) {
+  summary: "An account holder whose card access can be activated, suspended or closed."
+  fields { holder: account of holder }
+  lifecycle { states: [pending, active, suspended, closed], initial: pending }
+  action create {}
+  action activate { from: pending, to: active }
+  action suspend { from: active, to: suspended }
+  action resume { from: suspended, to: active }
+  action close { from: [active, suspended], to: closed }
+}
+
+instrument card(holder: ref<cards.cardholder>, spend_limit: money) {
+  summary: "A card with a per-spend ceiling that can be activated, frozen or cancelled."
+  fields { holder: ref<holder>, spendLimit: money = spend_limit }
+  lifecycle { states: [issued, active, frozen, cancelled], initial: issued }
+  action create { requires self.holder in [active] }
+  action activate { from: issued, to: active, requires self.holder in [active] }
+  action freeze { from: active, to: frozen }
+  action unfreeze { from: frozen, to: active, requires self.holder in [active] }
+  action cancel { from: [issued, active, frozen], to: cancelled }
+}
+
+instrument authorization(card: ref<cards.card>, merchant: party, issuer: party = programOperator) {
+  summary: "Reserve a card payment for the merchant, then capture it or release the reservation."
+  fields { card: ref<card>, merchant: account of merchant, amount: money, expiresAt: date, reservation: text? }
+  lifecycle { states: [pending, approved, captured, declined, reversed, expired], initial: pending }
+  action create {
+    requires self.card in [active]
+    requires self.card.holder in [active]
+    requires self.amount <= self.card.spendLimit
+  }
+  action approve {
+    from: pending, to: approved, actor: { party: issuer }, deadline: { at: self.expiresAt }
+    requires self.card in [active]
+    requires self.card.holder in [active]
+    moves reserve self.amount from self.card.holder.holder to merchant capture "reservation"
+  }
+  action capture { from: approved, to: captured, actor: { party: merchant }, deadline: { at: self.expiresAt }, moves post self.reservation }
+  action reverse { from: approved, to: reversed, actor: { party: merchant }, moves void self.reservation }
+  action decline { from: pending, to: declined, actor: { party: issuer } }
+  action expire { from: approved, to: expired, actor: clock, due: { at: self.expiresAt }, moves void self.reservation }
+  action abandon { from: pending, to: expired, actor: clock, due: { at: self.expiresAt } }
+}
+
+instrument transaction(authorization: ref<cards.authorization>) {
+  summary: "Record a captured card payment and return its amount when refunded."
+  fields { authorization: ref<authorization>, amount: money = self.authorization.amount }
+  lifecycle { states: [posted, refunded], initial: posted }
+  action create { requires self.authorization in [captured]; requires unique "captured_authorization" on [self.authorization] }
+  action refund {
+    from: posted, to: refunded, actor: { party: programOperator }, input { reason: text }
+    moves self.amount from self.authorization.merchant to self.authorization.card.holder.holder
+  }
+}
+
+instrument dispute(transaction: ref<cards.transaction>, issuer: party = programOperator, within: duration = 90d) {
+  summary: "Review a disputed card payment before its deadline and refund it when the dispute is won."
+  fields { transaction: ref<transaction>, evidence: text, expiresAt: date = after(self.createdAt, within) }
+  lifecycle { states: [filed, reviewing, won, lost], initial: filed }
+  action create { requires self.transaction in [posted]; requires unique "disputed_transaction" on [self.transaction] }
+  action review { from: filed, to: reviewing, actor: { party: issuer } }
+  action win {
+    from: reviewing, to: won, actor: { party: issuer }, deadline: { at: self.expiresAt }
+    invoke: [{ reference: self.transaction, action: refund, input: { reason: { field: self.evidence } } }]
+  }
+  action lose { from: [filed, reviewing], to: lost, actor: clock, due: { at: self.expiresAt } }
+}

package/std/collections.hsx

@@ -0,0 +1,90 @@
+header collections
+
+// Economics: Company capital pays agencies as participant payouts; outside capital passes through.
+// A company agency earns outside capital fees; its own capital fee is internal.
+
+// Expose case.create, assign and recover as separate steps. Creation needs overdue
+// outstanding principal and a matching slice/plan. Assignment belongs to capital;
+// recovery belongs to agency and pays the linked payment before the agency fee.
+// Payment must belong to the same plan. Recovered means that payment was processed,
+// not that the entire debt was repaid. Fee debits plan.capital, not the borrower.
+// Expose recall for capital and return_uncollected for agency when needed.
+// Contacts need an assigned case, matching agency, local hours and rolling count.
+// Contact outcomes are separate records. Reminder dispatch is operator-owned;
+// before_due/overdue are clock-owned and require active debt. Scheduled admission
+// does not prove delivery or retry. No collector can infer authority from an alias.
+
+// Cost: case recovery invokes the linked payment and then charges its agency
+// fee. Its count includes those child effects. Contact and reminder delivery costs
+// are not provider prices in hsx cost; the executor supplies commercial tariffs.
+
+instrument case(on: ref<financing.installments>[], agency: party, capital: party = programOperator, overdue: duration = 3d, fee: percent = 20%) {
+  revisioned: true
+  summary: "Refer an overdue installment without creating another debt."
+  fields { assignedAgency: account of agency, plan: ref<on>, slice: ref<on.slice>, payment: ref<on.payment>, eligibleAt: date = after(self.slice.dueAt, overdue), agencyFee: money = rate(self.payment.amount, fee) }
+  lifecycle { states: [opened, assigned, recovered, recalled, returned_uncollected], initial: opened }
+  action create {
+    due: { at: self.eligibleAt }
+    requires self.plan == self.slice.plan
+    requires self.slice.principalReceivable.balance > "0"
+    requires unique "overdue_referral" on [self.slice]
+  }
+  action assign { from: opened, to: assigned, actor: { party: capital } }
+  action recover { expansionLimit: 8192, from: assigned, to: recovered, actor: { party: agency }, requires self.payment.plan == self.plan, invoke: [{ reference: self.payment, action: pay, input: {} }, { reference: self.id, action: pay_fee, input: {} }] }
+  action pay_fee { allowZero: true, from: recovered, to: recovered, actor: { parent: current() }, moves self.agencyFee from self.plan.capital to agency economics { recipient: agency, company: { recipient: capital, company: { purpose: internal, sourceParty: capital }, participant: { purpose: earning, sourceParty: capital } }, participant: { recipient: capital, company: { purpose: participant_payout, sourceParty: capital }, participant: { purpose: pass_through, sourceParty: capital } } } }
+  action recall { from: [opened, assigned], to: recalled, actor: { party: capital } }
+  action return_uncollected { from: assigned, to: returned_uncollected, actor: { party: agency } }
+}
+
+instrument contact(case: ref<collections.case>[], agency: party, max_contacts: integer = 10, window: duration = 30d, contact_from: integer(0, 23) = 8, contact_until: integer(1, 23) = 20, timezone: text = "Asia/Riyadh") {
+  constraints { contact_from: less_than(contact_until) }
+  summary: "An agency contact admitted against the locked rolling count and local hours."
+  fields { agency: account of agency, case: ref<case>, attemptedAt: date?, evidence: text, maximum: integer = max_contacts }
+  lifecycle { states: [recorded], initial: recorded }
+  invariants count of { instrument: current(), reference: "case", anchor: self.case, states: [recorded], limit: 366, window: { field: attemptedAt, milliseconds: window } } <= self.maximum
+  action create {
+    actor: { party: agency }
+    set: { attemptedAt: { field: self.now } }
+    requires self.agency == self.case.assignedAgency; requires self.case in [assigned]; requires hours self.now between contact_from and contact_until timezone timezone
+  }
+  records {
+    outcome: {
+      fields { contact: ref<parent>, agency: account of agency, outcome: enum(reached, no_answer, promise_to_pay, disputed, wrong_contact, refused), evidence: text, recordedAt: date? }
+      lifecycle { states: [recorded], initial: recorded }
+      action create {
+        actor: { party: agency }
+        requires self.agency == self.contact.case.assignedAgency
+        set: { recordedAt: { field: self.now } }
+      }
+    }
+  }
+}
+
+
+instrument reminder(on: ref<financing.installments>[], operator: party = programOperator, before_days: integer(0, 366) = 3, overdue_days: integer(1, 366) = 1, max_per_day: integer(1, 10) = 1, send_from: integer(0, 23) = 8, send_until: integer(1, 24) = 20, timezone: text = "Asia/Riyadh") {
+  constraints { send_from: less_than(send_until) }
+  summary: "Send an email to the installment borrower's stored contact address."
+  fields { slice: ref<on.slice> }
+  lifecycle { states: [ready], initial: ready }
+  action create { requires unique "installment_reminder" on [self.slice] }
+  action dispatch {
+    from: ready, to: ready, actor: { party: operator }
+    invoke: [{ reference: self.id, action: send, input: {} }]
+  }
+  action before_due {
+    from: ready, to: ready, actor: clock
+    due: { at: self.slice.dueAt, localDay: { days: before_days, direction: "before", hour: send_from, timezone: timezone } }
+    invoke: [{ selection: { instrument: current(), reference: "slice", anchor: self.slice, states: [ready], limit: 1, where: { slice.plan.status: { literal: "active" } } }, action: send, guard: { kind: compare, left: { field: self.slice.principalReceivable.balance }, operator: ">", right: { literal: "0" } }, input: {} }]
+  }
+  action overdue {
+    from: ready, to: ready, actor: clock
+    due: { at: self.slice.dueAt, localDay: { days: overdue_days, direction: "after", hour: send_from, timezone: timezone } }
+    invoke: [{ selection: { instrument: current(), reference: "slice", anchor: self.slice, states: [ready], limit: 1, where: { slice.plan.status: { literal: "active" } } }, action: send, guard: { kind: compare, left: { field: self.slice.principalReceivable.balance }, operator: ">", right: { literal: "0" } }, input: {} }]
+  }
+  action send {
+    from: ready, to: ready, actor: { parent: current() }
+    requires self.slice.plan in [active]
+    requires self.slice.principalReceivable.balance > "0"
+    reminder: { installment: self.slice, recipient: self.slice.plan.borrower, dueAt: self.slice.dueAt, channel: "email", template: "payment_reminder", beforeDays: before_days, overdueDays: overdue_days, maxPerDay: max_per_day, startHour: send_from, endHour: send_until, timezone: timezone }
+  }
+}

package/std/escrow.hsx

@@ -0,0 +1,73 @@
+header escrow
+
+// Economics: Funding and unspent returns are principal. Acceptance realizes earnings for
+// the company or a payout to a bound outside seller; tax is pass-through.
+
+// Expose create, fund, deliver and accept for the purchase path. Create captures
+// subject.price; acceptance pays payee less the configured fee, not payer.
+// Expose dispute, verify_return and refund separately for the return path.
+// Payer disputes delivered goods; payee verifies return evidence from disputed;
+// payee refunds the entire held price from return_verified by default.
+// Acceptance expiry enters disputed, never released. Neither verify_return nor
+// refund becomes public merely because dispute is exposed. Clock actions remain
+// internal. Expose cancel for a pending hold, including a checkout-funded hold;
+// it returns its credited balance to payer before cancelling. Confirm requires
+// the whole captured price in held. This flow has no partial release or refund.
+
+// Cost: create declares one owned account. Fund and refund each declare one
+// transfer; accept expands the configured fee and tax into moves. Run hsx cost
+// on the composed program for instruction counts. The executor supplies prices.
+
+instrument hold(payer: party = party(person), payee: party = programOperator, accept_within: duration = 48h, fee: fee = { seller: 0%, tax: 0% }, dispute: policy = { refund_after: return_verified }) {
+  revisioned: true
+  summary: "Hold the subject price through delivery, acceptance and verified return."
+  fields {
+    payer: account of payer, payee: account of payee
+    held: account of self, deliveredAt: date?
+    price: money = subject.price
+  }
+  lifecycle { states: [pending, funded, delivered, disputed, return_verified, released, refunded, cancelled], initial: pending }
+  action create {
+    subject { price: money }
+    actor: { party: payer }
+  }
+  action fund {
+    from: pending, to: funded, actor: { party: payer }
+    subject { price: money }
+    moves self.price from payer to self.held economics { purpose: principal, sourceParty: payer }
+  }
+  action confirm {
+    from: pending, to: funded
+    requires self.held.balance == self.price
+  }
+  action deliver {
+    from: funded, to: delivered, actor: { party: payee }
+    set: { deliveredAt: { field: self.now } }
+  }
+  action accept { allowZero: true, requires self.price > "0";
+    from: delivered, to: released, actor: { party: payer }
+    input { acceptanceReference: text }
+    deadline: { at: self.deliveredAt, offset: accept_within }
+    moves self.price from self.held to payee fee fee economics { payee: { recipient: payee, company: { purpose: earning, sourceParty: payer }, participant: { purpose: participant_payout, sourceParty: programOperator } }, fee: { purpose: earning, sourceParty: payer }, tax: { purpose: pass_through, sourceParty: programOperator } }
+  }
+  action expire_acceptance {
+    from: delivered, to: disputed, actor: clock
+    due: { at: self.deliveredAt, offset: accept_within }
+  }
+  action dispute {
+    from: delivered, to: disputed, actor: { party: payer }
+    deadline: { at: self.deliveredAt, offset: accept_within }
+  }
+  action verify_return {
+    from: disputed, to: return_verified, actor: { party: payee }
+    input { returnEvidence: text }
+  }
+  action refund {
+    from: dispute.refund_after, to: refunded, actor: { party: payee }
+    moves self.price from self.held to payer economics { purpose: principal, sourceParty: programOperator }
+  }
+  action cancel { allowZero: true,
+    from: pending, to: cancelled, actor: { party: payer }
+    moves self.held.balance from self.held to payer economics { purpose: principal, sourceParty: programOperator }
+  }
+}