@hyperscale0/hsx 2.4.1 → 3.0.0

package/std/money_flows/conditional_disbursement.hsx

@@ -1,226 +0,0 @@
-module std.money_flows.conditional_disbursement
-
-// Capped disbursement from a source party to a destination party gated on stored external decision evidence.
-//
-// ### Purpose
-// `conditional_disbursement` manages evidence-contingent payouts subject to a cumulative cap.
-// It fits insurance claim settlements, grant tranches, subsidy distributions, and escrow milestones
-// where each approved payment requires explicit external evidence and the total paid must not exceed `cap`.
-//
-// ### Selection guidance
-// - vs `advance`: `conditional_disbursement` disburses non-repayable funds against external evidence
-//   up to a declared cap. `advance` pays money up front with the expectation of repayment through carved
-//   hold releases or scheduled installments.
-// - vs `instant_transfer`: `instant_transfer` moves money immediately with no evidence gate or cap.
-//   `conditional_disbursement` requires an external decision port and evidence reference before any child amount moves.
-//
-// ### Parameters
-// - `source`: The funding party providing the money.
-// - `destination`: The beneficiary party receiving approved disbursements.
-// - `cap`: Maximum total amount that can be disbursed across all child approvals in minor units of currency `C`.
-// - `amount`: Binding name for child approval amount values.
-// - `decision`: Port conditioning approval, requiring evidence reference.
-//
-// ### Decision ports
-// - `decision`: External port providing decision evidence required to approve child disbursement amounts.
-//
-// ### Example
-// ```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 }
-// }
-// ```
-export instrument conditional_disbursement<C>(
-  source: party,
-  destination: party,
-  cap: money<C>,
-  amount: money<C>,
-  decision: condition,
-) {
-  let(child_id): concat(instrument, "_approved_amount");
-  let(child_amount): "amount";
-  let(parent_field): camel(concat(instrument, "_id"));
-  let(source_field): camel(concat(source, "_account_id"));
-  let(destination_field): camel(concat(destination, "_account_id"));
-  let(currency_path): "fields.currency";
-  let(source_path): concat("fields.", source_field);
-  let(destination_path): concat("fields.", destination_field);
-
-  title: sentence(instrument);
-  agent_description: "Reach for conditional disbursement when the {source} pays the {destination} only against stored external evidence and the payouts must stay under {cap}. Each approved amount is its own child row. Pick instant transfer when no evidence gates the payment.";
-  summary: "Capped disbursement to {destination}";
-  description: "Capped disbursement controlled by stored external evidence";
-  id_prefix: prefix(instrument);
-  fields {
-    cap {
-      type: money<C>;
-      description: "Disbursement cap in {C} minor units";
-    }
-  }
-  required: [destination_field, source_field, currency, cap];
-  lifecycle {
-    states submitted denied;
-    initial submitted;
-    on deny: submitted -> denied;
-  }
-  parties {
-    beneficiary: destination;
-    payer: source;
-  }
-  action create {
-    agent_description: "Open the capped disbursement before any amount is approved. The caller supplies the {cap}, the currency, and the {source} and {destination} accounts. No money moves and nothing is approved yet.";
-    summary: "Submit the capped disbursement";
-    steps: [];
-    moves: [];
-  }
-  action deny {
-    agent_description: "Refuse the whole disbursement without moving money. Every child amount under it must still be unapproved, so call this before any approval lands. The caller passes evidenceReference, which stays in the receipt. Denial is final.";
-    summary: "Record a denial without moving money";
-    when(decision_fields) {
-      input {
-        type: object;
-        additional_properties: false;
-        properties {
-          for input_name in keys(decision_fields) {
-            [input_name]: get(decision_fields, input_name);
-          }
-        }
-        required: keys(decision_fields);
-      }
-      capture_input: {
-        for item in keys(decision_fields) { [item]: item; }
-      };
-    }
-    port { allowed_parties: decision_allowed; };
-    requires aggregate: {
-      check: { kind: all_in; };
-      instrument_id: child_id;
-      over: children;
-      ref_field: parent_field;
-      statuses: [created];
-    };
-    steps: [];
-    moves: [];
-  }
-
-  instruments {
-    instrument {
-      id: child_id;
-      generatedPrefix: true;
-      title: concat(sentence(instrument), " Approved Amount");
-      agent_description: concat("Reach for this child row to hold one evidence-gated amount under a ", words(instrument), ". The parent carries the {cap}, this row carries one approved amount and pays it once.");
-      summary: "Approved amount under {instrument}";
-      description: "One evidence-gated amount under {instrument}";
-      fields {
-        [child_amount] {
-          type: money<C>;
-          description: "Approved amount under the parent cap";
-        }
-        currency {
-          type: text;
-          description: "ISO 4217 currency code";
-          max_length: 3;
-          min_length: 3;
-          pattern: "^[A-Z]{3}$";
-        }
-        [parent_field] {
-          type: ref<instrument>;
-          description: "The exact {instrument}";
-          pattern: concat("^", prefix(instrument), "_(sandbox|live)_[a-z0-9]{8,64}$");
-        }
-      }
-      required: [destination_field, source_field, child_amount, currency, parent_field];
-      lifecycle {
-        states created approved paid;
-        initial created;
-        on approve: created -> approved;
-        on pay: approved -> paid;
-      }
-      parties {
-        beneficiary: destination;
-        payer: source;
-      }
-      action create {
-        agent_description: concat("Create one candidate amount under the parent ", words(instrument), ". The parent must still be submitted and the currency and both accounts must match it. No money moves and the amount is not approved yet.");
-        summary: "Create one candidate amount under the parent";
-        requires refs: {
-          bind: {
-            currency: currency_path;
-            [destination_field]: destination_path;
-            [source_field]: source_path;
-          };
-          field: parent_field;
-          statuses: [submitted];
-          unique: true;
-        };
-        steps: [];
-        moves: [];
-      }
-      action approve {
-        agent_description: "Store one externally approved amount under the parent cap. The row must be created, the parent still submitted, and the already approved and paid amounts plus this one must stay within {cap}. The caller passes evidenceReference. No money moves yet.";
-        summary: "Store one externally approved amount under the cap";
-        input: {
-          additional_properties: false;
-          properties: {
-            evidence_reference: {
-              description: "Required decision reference retained in the operation receipt";
-              max_length: 180;
-              min_length: 1;
-              type: "string";
-            };
-          };
-          required: [evidenceReference];
-          type: "object";
-        };
-        capture_input: { decision_evidence_reference: evidenceReference; };
-        port: { allowed_parties: decision_allowed; };
-        requires exposure: {
-          amount_field: child_amount;
-          anchor_field: parent_field;
-          cap_field: cap;
-          cap_on_anchor: true;
-          child_instrument_id: child_id;
-          statuses: [approved, paid];
-        };
-        requires refs: {
-          field: parent_field;
-          match: {
-            [currency_path]: currency_path;
-            [destination_path]: destination_path;
-            [source_path]: source_path;
-          };
-          statuses: [submitted];
-        };
-        steps: [];
-        moves: [];
-      }
-      action pay {
-        agent_description: "Pay the stored approved amount to the {destination} once. The row must be approved and the parent still submitted. The transfer posts straight out of the {source} and does not unwind.";
-        summary: "Pay the stored approved amount once";
-        requires refs: {
-          field: parent_field;
-          match: {
-            [currency_path]: currency_path;
-            [destination_path]: destination_path;
-            [source_path]: source_path;
-          };
-          statuses: [submitted];
-        };
-        moves: [{ amount: child_amount; from: payer; to: beneficiary; key: payout; operation: create; }];
-        steps: [];
-      }
-    }
-  }
-}

package/std/money_flows/credit_facility.hsx

@@ -1,214 +0,0 @@
-module std.money_flows.credit_facility
-
-// Revolving credit line providing reusable borrowing capacity up to a limit backed by scheduled obligations.
-//
-// ### Purpose
-// `credit_facility` manages revolving commercial credit, inventory financing, and overdraft facilities.
-// A borrower can draw funds multiple times up to `limit` into `draw_destination`. Each draw creates a child
-// record linked to a scheduled `obligation`. Repayments restore available borrowing capacity until `expires_at`.
-//
-// ### Selection guidance
-// - vs `advance`: `credit_facility` provides revolving, reusable credit lines where multiple draws can occur
-//   and repayments restore capacity. `advance` is a single upfront lump-sum disbursement with a fixed repayment plan.
-// - vs `scheduled`: `scheduled` defines repayment installments or recurring transfers. `credit_facility` delegates
-//   draw repayments to a `scheduled` obligation while tracking total facility utilization and limit compliance.
-//
-// ### Parameters
-// - `lender`: The financing institution or party providing the credit capacity.
-// - `borrower`: The borrowing party authorized to draw against the facility limit.
-// - `draw_destination`: Account or party receiving disbursed draw proceeds.
-// - `limit`: Total revolving borrowing limit in minor units of currency `C`.
-// - `expires_at`: Expiration date after which new draws cannot be opened.
-// - `obligation`: Reference to a scheduled obligation instrument handling draw repayments.
-//
-// ### Decision ports
-// None on the facility itself. Mandates and decision ports are declared on the linked `obligation` instrument.
-//
-// ### Example
-// ```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
-// }
-// ```
-export instrument credit_facility<C>(
-  lender: party,
-  borrower: party,
-  draw_destination: party,
-  limit: money<C>,
-  expires_at: date,
-  obligation: ref,
-) {
-  let(draw_id): concat(instrument, "_draw");
-  let(parent_field): camel(concat(instrument, "_id"));
-  let(borrower_field): camel(concat(borrower, "_account_id"));
-  let(lender_field): camel(concat(lender, "_account_id"));
-  let(destination_field): camel(concat(draw_destination, "_account_id"));
-  let(currency_path): "fields.currency";
-  let(lender_path): concat("fields.", lender_field);
-  let(destination_path): concat("fields.", destination_field);
-  let(reference_filter): "x-hyperscale-reference-filter";
-  let(obligation_name): owner(obligation);
-  let(obligation_field): camel(concat(obligation_name, "_id"));
-
-  title: sentence(instrument);
-  agent_description: "Reach for credit facility when the {lender} gives the {borrower} reusable capacity up to {limit} and every draw is repaid through its own scheduled obligation. Capacity frees up as each obligation resolves. Pick advance for one up-front payment with no reusable limit.";
-  summary: "Draw capacity for {borrower}";
-  description: "Reusable capacity with repayment delegated to one scheduled obligation";
-  id_prefix: prefix(instrument);
-  fields {
-    [borrower_field] {
-      type: account<C>;
-      description: "The {borrower} account";
-      [reference_filter]: {
-        column: role;
-        values: [customer_balance];
-      };
-    }
-    limit {
-      type: money<C>;
-      description: "Facility limit in {C} minor units";
-    }
-    expires_at {
-      type: date;
-      description: "Stored draw expiry";
-    }
-  }
-  required: [borrower_field, destination_field, lender_field, currency, limit, expires_at];
-  lifecycle {
-    states active frozen closed;
-    initial active;
-    on freeze: active -> frozen;
-    on close: active|frozen -> closed;
-  }
-  parties {
-    beneficiary: draw_destination;
-    payer: lender;
-  }
-  action create {
-    agent_description: "Open the facility before any draw exists. The caller supplies the {limit}, the currency, the {borrower} and {lender} accounts, the draw destination account, and the stored expiry. No money moves.";
-    summary: "Open the facility";
-    steps: [];
-    moves: [];
-  }
-  action freeze {
-    summary: "Freeze new draws at expiry";
-    due: { field: expires_at; };
-    steps: [];
-    moves: [];
-  }
-  action close {
-    agent_description: "Close the facility for good. Every draw under it must already be resolved, so clear the outstanding obligations first. No money moves and a closed facility never lends again.";
-    summary: "Close only when every admitted draw resolved";
-    requires aggregate: {
-      check: { kind: all_in; };
-      instrument_id: draw_id;
-      over: children;
-      ref_field: parent_field;
-      statuses: [resolved];
-    };
-    steps: [];
-    moves: [];
-  }
-
-  instruments {
-    instrument {
-      id: draw_id;
-      generatedPrefix: true;
-      title: concat(sentence(instrument), " Draw");
-      agent_description: concat("Reach for this child row to take one draw against a ", words(instrument), ". The parent carries the {limit}, this row carries one drawn amount and the single obligation that repays it.");
-      summary: "Draw from {instrument}";
-      description: "One capacity-capped draw linked to obligation";
-      fields {
-        amount {
-          type: money<C>;
-          description: "One draw amount";
-        }
-        currency {
-          type: text;
-          description: "ISO 4217 currency code";
-          max_length: 3;
-          min_length: 3;
-          pattern: "^[A-Z]{3}$";
-        }
-        [parent_field] {
-          type: ref<instrument>;
-          description: "The exact {instrument}";
-          pattern: concat("^", prefix(instrument), "_(sandbox|live)_[a-z0-9]{8,64}$");
-        }
-        [obligation_field] {
-          type: ref<obligation_name>;
-          description: "The sole repayment obligation";
-          pattern: concat("^", prefix(obligation_name), "_(sandbox|live)_[a-z0-9]{8,64}$");
-        }
-      }
-      required: [destination_field, lender_field, amount, currency, parent_field, obligation_field];
-      lifecycle {
-        states drawn resolved;
-        initial drawn;
-        on resolve: drawn -> resolved;
-      }
-      parties {
-        beneficiary: draw_destination;
-        payer: lender;
-      }
-      action create {
-        agent_description: "Draw one amount out of the facility to the draw destination account. The facility must be active, the linked obligation active and bound to no other draw, and the drawn amounts plus this one must stay within {limit}. The money leaves the {lender} straight away.";
-        summary: "Create one draw under the locked facility capacity";
-        requires exposure: {
-          amount_field: amount;
-          anchor_field: parent_field;
-          cap_field: limit;
-          cap_on_anchor: true;
-          child_instrument_id: draw_id;
-          statuses: [drawn];
-        };
-        requires refs: [{
-          bind: {
-            currency: currency_path;
-            [destination_field]: destination_path;
-            [lender_field]: lender_path;
-          };
-          field: parent_field;
-          statuses: [active];
-        }, {
-          field: obligation_field;
-          statuses: [active];
-          unique: true;
-        }];
-        moves: [{ amount: amount; from: payer; to: beneficiary; key: draw; operation: create; }];
-        steps: [];
-      }
-      action resolve {
-        agent_description: "Free the drawn capacity back to the facility. The linked obligation must already be repaid or written off. No money moves here, the obligation did the repaying.";
-        summary: "Release revolving capacity only after the linked obligation resolves";
-        requires refs: {
-          field: obligation_field;
-          statuses: [repaid, written_off];
-        };
-        steps: [];
-        moves: [];
-      }
-    }
-  }
-}