@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0-rc.1

package/std/settlements/security_deposit.hsx

@@ -0,0 +1,166 @@
+module std.settlements.security_deposit
+
+export instrument security_deposit<C>(payer: party, holder: party, amount: money<C>, claim: optional<condition>, return: optional<condition>, claim_amount: optional<block>, deadline: optional<date>, claim_to: optional<party>, return_to: optional<party>, memo: optional<text>, claim_input: optional<block>, claim_capture: optional<block>, fund_failure_point: optional<text>, id_prefix_override: optional<text>) {
+  let(claim_name): claim;
+  let(return_name): return;
+  let(payer_account_field): camel(concat(payer, "_account_id"));
+  let(holder_account_field): camel(concat(holder, "_account_id"));
+  let(claim_actor): at(claim_allowed, 1);
+  let(claim_role): if_eq(claim_actor, payer, "payer", "beneficiary");
+  let(claim_field): get(claim_amount, "field");
+  let(claim_bound): get(claim_amount, "bound");
+  let(claim_remainder): get(claim_amount, "remainder");
+  let(deadline_field): concat(deadline);
+  let(memo_field): concat(memo);
+  let(claim_to_role): if_eq(claim_to, payer, "payer", "beneficiary");
+  let(return_to_role): if_eq(return_to, payer, "payer", "beneficiary");
+  agent_description: "Reach for security deposit when money is reserved against the {payer} in the {holder}'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.";
+  summary: "Refundable deposit from {payer} held for {holder}";
+  title: sentence(instrument);
+  when(id_prefix_override) { id_prefix: id_prefix_override; }
+  when_not(deadline) {
+    when_not(claim_amount) {
+      description: concat("Deposit: the ", amount, " is reserved against the ", payer, "'s account in the ", holder, "'s favor, then claimed or returned in full");
+    }
+    when(claim_amount) {
+      description: concat("Deposit: the ", amount, " is reserved against the ", payer, "'s account in the ", holder, "'s favor, then ", claim_field, " is claimed and the exact remainder returned, or the deposit is returned in full");
+    }
+  }
+  fields {
+    when_not(deadline) {
+      amount { type: money<C>; description: "The deposit amount in {C} minor units, reserved in full and fully accounted on claim or return"; }
+    }
+    when(deadline) {
+      let(reference_filter_key): "x-hyperscale-reference-filter";
+      amount { type: money<C>; description: "Positive minor-unit integer amount serialized as a string (at most 18 digits)"; }
+      [deadline_field] { type: date; }
+      [holder_account_field] { type: account<C>; description: "Hyperscale account ID"; pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter_key]: { column: role; values: [customer_balance]; }; }
+      [payer_account_field] { type: account<C>; description: "Hyperscale account ID"; pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter_key]: { column: role; values: [customer_balance]; }; }
+      when(memo) { [memo_field] { type: text; max_length: 180; min_length: 1; optional: true; } }
+    }
+  }
+  lifecycle {
+    when_not(deadline) {
+      states created held claimed returned;
+      initial created;
+      on place_deposit: created -> held;
+      on [claim_name]: held -> claimed;
+      on [return_name]: held -> returned;
+    }
+    when(deadline) {
+      states created held claimed returned expired canceled;
+      initial created;
+      on cancel: created -> canceled;
+      on claim: held -> claimed;
+      on expire: held -> expired;
+      on fund: created -> held;
+      on return: held -> returned;
+    }
+  }
+  parties {
+    payer: payer;
+    beneficiary: holder;
+  }
+  when_not(deadline) {
+    action create {
+      agent_description: "Open the deposit row before anything is reserved. The caller supplies the {amount}, the currency, and the {payer} and {holder} accounts. Nothing is reserved yet, call place deposit next.";
+      summary: concat("Create a ", words(instrument));
+      moves: [];
+      steps: [];
+    }
+    action place_deposit {
+    agent_description: "Reserve the {amount} against the {payer}'s account in the {holder}'s favor. The deposit must be created. The money is held, not paid: the claim posts it to the {holder} and the return releases it back.";
+    let(metadata_instrument): "metadata.instrumentId";
+    let(metadata_instance): "metadata.instrumentInstanceId";
+    let(metadata_phase): "metadata.phase";
+    summary: "Reserve the {amount} against the {payer}'s account";
+    moves: [{ key: reservation; operation: internal_transfer.reserve; bind: { amount: { from: instance; path: concat("fields.", amount); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", holder_account_field); }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: place_deposit; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { placeDepositReservationTransferId: transferId; }; }];
+    steps: [];
+    }
+    action [claim_name] {
+    agent_description: "Claim the held deposit for the {holder}. 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 {payer}. There is no return afterwards.";
+    summary: "Claim the deposit for the {holder} through {claim}";
+    when_not(claim_amount) {
+      moves: [{ key: post; operation: internal_transfer.post; bind: { transferId: { from: instance; path: refs.placeDepositReservationTransferId; }; }; }];
+    }
+    when(claim_amount) {
+      let(decided_clause): "decided amount";
+      input {
+        type: object;
+        additional_properties: false;
+        properties {
+          for input_name in keys(claim_fields) {
+            [input_name] { type: string; description: "Required decision reference retained in the operation receipt"; max_length: 180; min_length: 1; }
+          }
+          [claim_field] { type: string; description: "Caller-decided amount in minor units"; pattern: "^(0|[1-9][0-9]{0,17})$"; }
+        }
+        required: keys(claim_fields);
+      }
+      [decided_clause]: { field: claim_field; bound_field: claim_bound; remainder_action: return_name; };
+      port { allowed_parties: [claim_role]; };
+      moves: [{ key: post; operation: internal_transfer.post; bind: { amount: { from: input; path: claim_field; }; currency: { from: instance; path: fields.currency; }; postMode: { from: const; value: partial_only; }; transferId: { from: instance; path: refs.placeDepositReservationTransferId; }; }; }, { key: remainder; operation: internal_transfer.void; bind: { reason: { from: const; value: "Return the unclaimed deposit remainder"; }; transferId: { from: instance; path: refs.placeDepositReservationTransferId; }; }; }];
+    }
+    steps: [];
+    }
+    action [return_name] {
+      agent_description: "Return the held deposit to the {payer}. The deposit must be in held and unclaimed. This releases the reservation whole and the {holder} receives nothing.";
+      summary: "Return the deposit to the {payer} through {return}";
+      moves: [{ key: void; operation: internal_transfer.void; bind: { reason: { from: const; value: "Deposit returned in full"; }; transferId: { from: instance; path: refs.placeDepositReservationTransferId; }; }; }];
+      steps: [];
+    }
+  }
+  when(deadline) {
+    required: [payer_account_field, holder_account_field, amount, currency, deadline_field];
+    caller_parked_states: { created: "funding or canceling an unfunded hold is the payer's decision"; };
+    distinct_parties: true;
+    dials: [{ field: deadline_field; key: holding_window; kind: window; maxOffset: "P90D"; summary: "Maximum time before the machine returns an unclaimed hold."; title: "Holding window"; }];
+    action create {
+      agent_description: "Open the hold by recording the {payer}, the {holder}, the {amount}, and the deadline. No money moves here, so a created hold costs the {payer} nothing until fund runs. The deadline is when the machine returns anything still unclaimed.";
+      deadline: { field: deadline_field; };
+      summary: concat("Create a ", words(instrument));
+      moves: [];
+      steps: [];
+    }
+    action fund {
+      agent_description: "Reserve the whole {amount} out of the {payer}'s balance for the {holder}. This moves money and the {payer} can no longer spend it. Only a created hold funds. The reservation carries no expiry of its own, so the hold's deadline governs when it comes back.";
+      deadline: { field: deadline_field; };
+      moves: [{ key: reservation; operation: internal_transfer.reserve; bind: { amount: { from: instance; path: concat("fields.", amount); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", holder_account_field); }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { holdTransferId: transferId; }; }];
+      when(fund_failure_point) { sandbox_failure_point: fund_failure_point; }
+      steps: [];
+      summary: "Fund the security deposit";
+    }
+    action claim {
+      agent_description: "Post the {holder}'s decided amount out of the reservation and void the remainder back to the {payer} in one linked group. This moves money and does not reverse. Only a funded hold claims, and the claimed amount cannot exceed the held {amount}.";
+      deadline: { field: deadline_field; };
+      when(claim_capture) { capture_input: claim_capture; }
+      when(claim_amount) {
+        decided_amount: { field: claim_field; bound_field: claim_bound; remainder_action: claim_remainder; };
+      }
+      when(claim_input) { input: claim_input; }
+      when(claim_to) { port { allowed_parties: [claim_to_role]; }; }
+      moves: [{ key: "claim"; operation: internal_transfer.post; bind: { amount: { from: input; path: claim_field; }; currency: { from: instance; path: fields.currency; }; postMode: { from: const; value: partial_only; }; transferId: { from: instance; path: refs.holdTransferId; }; }; }, { key: remainder; operation: internal_transfer.void; bind: { reason: { from: const; value: "Return unclaimed deposit remainder"; }; transferId: { from: instance; path: refs.holdTransferId; }; }; }];
+      steps: [];
+      summary: "Claim the security deposit";
+    }
+    action return {
+      agent_description: "Void the whole reservation so the {payer} gets every unit back. Use this when the {holder} decides to keep nothing. This moves money and does not reverse. Only a funded hold returns.";
+      deadline: { field: deadline_field; };
+      when(return_to) { port { allowed_parties: [return_to_role]; }; }
+      moves: [{ key: "return"; operation: internal_transfer.void; bind: { reason: { from: const; value: "Deposit returned in full"; }; transferId: { from: instance; path: refs.holdTransferId; }; }; }];
+      steps: [];
+      summary: "Return the security deposit";
+    }
+    action expire {
+      due: { field: deadline_field; };
+      moves: [{ key: expire; operation: internal_transfer.void; bind: { reason: { from: const; value: "Deposit hold expired"; }; transferId: { from: instance; path: refs.holdTransferId; }; }; }];
+      steps: [];
+      summary: "Expire the security deposit";
+    }
+    action cancel {
+      agent_description: "Close a hold before anyone funds it. No money has moved, so this is a lifecycle transition only. Only a created hold cancels. A funded hold refuses, because its money is already reserved. Claim it or return it instead.";
+      moves: [];
+      steps: [];
+      summary: "Cancel the security deposit";
+    }
+  }
+}

package/std/settlements/settlement_batch.hsx

@@ -0,0 +1,122 @@
+module std.settlements.settlement_batch
+
+export instrument settlement_batch<C>(
+  settlement_account: party,
+  source_capture_refs: text,
+  fee_entries: text,
+  external_reversal_offsets: text,
+  close_trigger: date,
+  payout_destination: party,
+  negative_position: text,
+  payout_acknowledgement: condition,
+  payout_beneficiary_ref: text,
+) {
+  fields {
+    close_trigger { type: date; description: "Date the open batch freezes against later entries"; }
+    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
+    payout_beneficiary_ref { type: text; description: "Beneficiary ID for the payout instruction"; pattern: "^ben_(sandbox|live)_[a-z0-9]{8,64}$"; }
+    [payout_destination]AccountId { type: account<C>; description: concat("The ", words(payout_destination), " account"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
+    [settlement_account]AccountId { type: account<C>; description: concat("The ", words(settlement_account), " account"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
+  }
+  lifecycle {
+    states open closed calculated approved instructed acknowledged reconciled;
+    initial open;
+    on close: open -> closed;
+    on calculate: closed -> calculated;
+    on approve: calculated -> approved;
+    on instruct: approved -> instructed;
+    on [payout_acknowledgement]: instructed -> acknowledged;
+    on reconcile: instructed|acknowledged -> reconciled;
+  }
+  parties { beneficiary: concat(camel(payout_destination), "AccountId"); payer: concat(camel(settlement_account), "AccountId"); }
+  required: [concat(camel(payout_destination), "AccountId"), concat(camel(settlement_account), "AccountId"), close_trigger, currency, payout_beneficiary_ref];
+  title: sentence(instrument);
+  id_prefix: prefix(instrument);
+  agent_description: "Reach for settlement batch when many charges over a period roll up into one payout. Capture entries and adjustments accrue against an open batch, the batch freezes on its close date, calculate proves one signed net payable, and instruct sends a single external payout. Weighted distribution goes the other way, one amount out to many recipients.";
+  summary: concat("Payout batch from ", words(settlement_account), " to ", words(payout_destination));
+  description: "Immutable batch of capture lineage and signed adjustments that creates one payout";
+  action create { agent_description: "Open a batch that capture entries and adjustments can accrue into. No money moves. The batch keeps taking entries until its close date freezes it."; summary: concat("Open a ", words(instrument)); moves: []; steps: []; }
+  action close { summary: "Freeze the batch and stop all new entries"; due { field: close_trigger; } moves: []; steps: []; }
+  action calculate {
+    agent_description: "Prove and freeze the one net payable from gross captures plus credit adjustments minus debit adjustments. The batch must be closed first. A zero or negative net is refused, so a batch in deficit never reaches a payout. No money moves.";
+    summary: "Prove and freeze the one signed net payable amount";
+    computes signed_sum {
+      amountRef: netPayable; onNegative: refuse; onZero: refuse;
+      sources: [
+        { amountField: amount; instrumentId: concat(instrument, "_capture_entry"); refField: concat(camel(instrument), "Id"); sign: add; statuses: [accrued]; subtotalRef: grossCaptureAmount; },
+        { amountField: amount; instrumentId: concat(instrument, "_credit_adjustment"); refField: concat(camel(instrument), "Id"); sign: add; statuses: [applied]; subtotalRef: creditAdjustmentAmount; },
+        { amountField: amount; instrumentId: concat(instrument, "_debit_adjustment"); refField: concat(camel(instrument), "Id"); sign: subtract; statuses: [applied]; subtotalRef: debitAdjustmentAmount; },
+      ];
+    }
+    moves: []; steps: [];
+  }
+  action approve { agent_description: "Sign off on the frozen net payable. The batch must already be calculated. Nothing is recomputed and no money moves. This is the gate instruct waits on."; summary: "Approve the frozen payable without recomputing it"; moves: []; steps: []; }
+  action instruct {
+    agent_description: "Create one external payout for the frozen net payable, drawn on the settlement account and sent to the stored beneficiary. The batch must be approved. This moves money off the platform and is idempotent, so a retry never pays twice.";
+    summary: "Create one idempotent payout from the frozen net payable";
+    payout { amount: "refs.netPayable"; beneficiaryField: payout_beneficiary_ref; beneficiaryPartyField: concat(camel(payout_destination), "AccountId"); capture: payoutId; currencyField: currency; sourceAccountField: concat(camel(settlement_account), "AccountId"); speed: standard; }
+    moves: []; steps: [];
+  }
+  action [payout_acknowledgement] {
+    agent_description: "Record the beneficiary confirmation that the payout landed, with the reference kept in the receipt. The batch must already be instructed. Only the payout destination may call it. No money moves.";
+    summary: "Record the tenant's payout acknowledgement in the receipt";
+    port { allowedParties: [beneficiary]; }
+    input { type: object; properties: { acknowledgementReference: { type: string; description: "Required decision reference retained in the operation receipt"; minLength: 1; maxLength: 180; }; }; required: [acknowledgementReference]; additionalProperties: false; }
+    capture_input { acknowledgementReference: acknowledgementReference; }
+    moves: []; steps: [];
+  }
+  action reconcile {
+    summary: "Match durable evidence that the payout settled";
+    due { field: close_trigger; offset: "P30D"; }
+    reconcile {
+      amount: "refs.netPayable"; capture: settlementEvidenceId; counterpartyRef: payoutId;
+      currencyField: currency; direction: debit; evidence: statement_line;
+      exception { amountField: amount; childInstrumentId: concat(instrument, "_debit_adjustment"); maxOpen: 1; reasonField: adjustmentReference; refField: concat(camel(instrument), "Id"); }
+      match { law: exact; }
+      within { offset: "P30D"; }
+    }
+    moves: []; steps: [];
+  }
+  instruments {
+    instrument {
+      let(parent_name): instrument;
+      id: concat(parent_name, "_capture_entry");
+      id_prefix: concat(prefix(parent_name), "ce");
+      fields {
+        amount { type: money<C>; description: "Gross captured amount in minor units"; }
+        [source_capture_refs] { type: text; description: "Immutable source capture reference"; minLength: 1; maxLength: 180; }
+        currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
+        [parent_name]Id { type: ref<parent_name>; description: "Open batch this capture entry accrues into"; pattern: concat("^", prefix(parent_name), "_(sandbox|live)_[a-z0-9]{8,64}$"); }
+      }
+      lifecycle { states created accrued; initial created; on accrue: created -> accrued; }
+      required: [amount, currency, concat(camel(parent_name), "Id"), source_capture_refs];
+      agent_description: "One gross capture that belongs to an open batch. Record one per source capture so the net payable keeps its lineage back to the original charge.";
+      title: concat(sentence(parent_name), " Capture Entry"); summary: "Gross capture lineage entry"; description: "One gross capture entry linked to an open payout batch";
+      action create { agent_description: "Record one capture with its source reference against an open batch. The batch must be open and share the currency. No money moves, and the entry counts toward the net payable only once it accrues."; summary: "Create a capture lineage entry on an open batch"; requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
+      action accrue { agent_description: "Count this capture toward the batch gross total. The entry must be created and its batch still open, because a closed batch admits nothing new. No money moves."; summary: "Accrue the capture entry into the open batch"; requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
+    }
+    for adjustment_kind in [credit, debit] {
+      instrument {
+        let(parent_name): instrument;
+        id: concat(parent_name, "_", adjustment_kind, "_adjustment");
+        id_prefix: concat(prefix(parent_name), if_eq(adjustment_kind, "credit", "ca", "da"));
+        fields {
+          adjustmentReference { type: text; description: "Immutable explicit adjustment reference"; minLength: 1; maxLength: 180; }
+          amount { type: money<C>; description: concat(title(adjustment_kind), " adjustment amount in minor units"); }
+          [source_capture_refs] { type: text; description: "Original capture reference that this adjustment corrects"; minLength: 1; maxLength: 180; }
+          currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
+          [external_reversal_offsets] { type: text; description: "Optional externally decided reversal reference"; minLength: 1; maxLength: 180; optional: true; }
+          [fee_entries] { type: text; description: "Optional fee entry reference"; minLength: 1; maxLength: 180; optional: true; }
+          [parent_name]Id { type: ref<parent_name>; description: "Open batch this adjustment applies to"; pattern: concat("^", prefix(parent_name), "_(sandbox|live)_[a-z0-9]{8,64}$"); }
+        }
+        lifecycle { states created applied; initial created; on adjust: created -> applied; on correct: created -> applied; }
+        required: [amount, currency, adjustmentReference, concat(camel(parent_name), "Id"), source_capture_refs];
+        agent_description: concat("One ", adjustment_kind, " adjustment against an open batch, carrying the capture reference it corrects. Credit adjustments add to the net payable and debit adjustments subtract from it, so a late correction lands on the current open batch instead of reopening a closed one.");
+        title: concat(sentence(parent_name), " ", title(adjustment_kind), " Adjustment"); summary: concat(title(adjustment_kind), " adjustment with capture lineage"); description: concat("One ", adjustment_kind, " adjustment linked to an open payout batch; closed batches stay unchanged");
+        action create { agent_description: concat("Record a ", adjustment_kind, " adjustment on an open batch, naming the capture reference it corrects. The batch must be open and share the currency. No money moves, and the adjustment counts only once it is applied."); summary: concat("Create a ", adjustment_kind, " adjustment on an open batch"); requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
+        action adjust { agent_description: concat("Apply the ", adjustment_kind, " adjustment so calculate counts it. The adjustment must be created and its batch still open. No money moves. The effect shows up in the batch net payable."); summary: concat("Apply the ", adjustment_kind, " adjustment to the open batch"); requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
+        action correct { agent_description: "Apply this adjustment as a correction on the open batch it names. Use it when the batch carrying the original entry has already closed, because a closed batch never changes. The adjustment must be created and no money moves."; summary: "Record a later correction on this open batch instead of changing the closed source batch"; requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
+      }
+    }
+  }
+}