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

package/std/settlements/instant_transfer.hsx

@@ -0,0 +1,190 @@
+module std.settlements.instant_transfer
+
+export instrument instant_transfer<C>(payer: party, payee: party, amount: money<C>, fees: optional<block>, derived_amount: optional<block>) {
+  let(payer_fee): get(fees, payer);
+  let(payee_fee): get(fees, payee);
+  let(payer_fee_kind): kind(payer_fee);
+  let(payee_fee_kind): kind(payee_fee);
+  let(payer_account_field): camel(concat(payer, "_account_id"));
+  let(payee_account_field): camel(concat(payee, "_account_id"));
+  let(net_bps): sub(10000, payee_fee);
+  let(net_percent): percent_text(net_bps);
+  let(payee_bps): basis_points(payee_fee);
+  let(payee_tiers): values(payee_fee);
+  let(first_tier): at(payee_tiers, 1);
+  let(second_tier): at(payee_tiers, 2);
+  let(second_tier_fee): get(second_tier, "fee");
+  when(derived_amount) {
+    let(derived_field): get(derived_amount, "field");
+    let(derived_source): get(derived_amount, "source");
+    let(derived_rule): get(derived_amount, "rule");
+    let(derived_bearer): get(derived_amount, "bearer");
+  }
+  agent_description: concat("Reach for instant transfer when the ", words(payer), " pays the ", words(payee), " straight through with no custody step. The money leaves and lands in one call. Pick deposit when the money must be held first, and captured payment when the payee takes it in slices.");
+  summary: concat("Instant payment from ", words(payer), " to ", words(payee));
+  title: sentence(instrument);
+  description: concat("Instant transfer: the ", words(payer), " pays ", amount, " straight through to the ", words(payee), ", no custody");
+  fields {
+    when_not(fees) {
+      when(derived_amount) {
+        let(fee_collection_key): "x-hyperscale-fee-collection-port";
+        let(reference_filter_key): "x-hyperscale-reference-filter";
+        platformAccountId {
+          type: account<C>;
+          description: "The product fee collection account";
+          pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$";
+          [fee_collection_key]: true;
+          [reference_filter_key]: { column: role; values: [customer_balance, product_revenue]; };
+        }
+      }
+    }
+    when(fees) {
+      let(fee_collection_key): "x-hyperscale-fee-collection-port";
+      let(reference_filter_key): "x-hyperscale-reference-filter";
+      platformAccountId {
+        type: account<C>;
+        description: "The product fee collection account";
+        pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$";
+        [fee_collection_key]: true;
+        [reference_filter_key]: { column: role; values: [customer_balance, product_revenue]; };
+      }
+    }
+    when_not(fees) {
+      amount { type: money<C>; description: "The amount in {C} minor units, paid through whole"; }
+    }
+    when(fees) {
+      amount { type: money<C>; description: "The gross amount in {C} minor units; the piece fields below partition it exactly"; }
+      when_eq(payee_fee_kind, percent) {
+        piece1Amount { type: money<C>; description: concat(net_percent, " of ", amount, " (carries the integer-division remainder): released to the ", payee, ". Computed as floor(", amount, " * ", net_bps, " / 10000) in ", C, " minor units"); pattern: "^[1-9][0-9]{0,17}$"; }
+        piece2Amount { type: money<C>; description: concat(payee_fee, " of ", amount, ": released to the platform. Computed as floor(", amount, " * ", payee_bps, " / 10000) in ", C, " minor units"); pattern: "^[1-9][0-9]{0,17}$"; optional: true; }
+      }
+      when_eq(payee_fee_kind, block) {
+        netOfCarvedFeeAmount { type: money<C>; description: "The remainder of {amount} after the carved platform fee"; pattern: "^[1-9][0-9]{0,17}$"; }
+        carvedFeeAmount { type: money<C>; description: "The carved platform fee selected from {amount}"; pattern: "^[1-9][0-9]{0,17}$"; optional: true; }
+      }
+      when_eq(payer_fee_kind, percent) {
+        serviceFeeAmount { type: money<C>; description: "Machine-owned {payer_fee} service fee computed from {amount}; charged on top"; pattern: "^[1-9][0-9]{0,17}$"; optional: true; }
+      }
+      when_eq(payer_fee_kind, binding) {
+        [payer_fee] { type: payer_fee; description: "Immutable exact {payer} fee in {C} minor units"; pattern: "^[1-9][0-9]{0,17}$"; }
+      }
+      when_eq(payee_fee_kind, block) {
+        [second_tier_fee] { type: second_tier_fee; description: "Immutable exact {payee} fee in {C} minor units"; pattern: "^[1-9][0-9]{0,17}$"; }
+      }
+    }
+    when(derived_amount) {
+      [derived_field] { type: money<C>; description: "Machine-computed {derived_rule} of {derived_source}; callers never supply it"; pattern: "^[1-9][0-9]{0,17}$"; optional: true; }
+    }
+  }
+  lifecycle {
+    when_not(fees) { states created paid; }
+    when(fees) { states created paying_1 paying_2 paid; }
+    initial created;
+    when_not(fees) { on pay_piece_1: created -> paid; }
+    when(fees) {
+      on pay_piece_1: created -> paying_1;
+      on pay_piece_2: paying_1 -> paying_2;
+      on collect_service_fee: paying_2 -> paid;
+    }
+  }
+  parties {
+    payer: payer;
+    beneficiary: payee;
+  }
+  when(derived_amount) {
+    computes derived: { field: derived_field; source_field: derived_source; rounding: floor; rule: { kind: percentage_of; bps: derived_rule; }; };
+  }
+  when(fees) {
+    when_eq(payer_fee_kind, percent) {
+      computes fees: { amount_field: serviceFeeAmount; base_field: amount; bearer_field: payer_account_field; position: on_top; rule: { kind: bps; bps: payer_fee; }; };
+    }
+    when_eq(payer_fee_kind, binding) {
+      computes fees: { amount_field: camel(payer_fee); base_field: amount; bearer_field: payer_account_field; position: on_top; rule: { kind: exact; field: camel(payer_fee); currency_field: currency; }; };
+    }
+    when_eq(payee_fee_kind, percent) {
+      computes fees: { amount_field: piece2Amount; base_field: amount; bearer_field: payee_account_field; position: carved; rule: { kind: bps; bps: payee_fee; }; };
+      partitions: { total_field: amount; piece_fields: [piece1Amount, piece2Amount]; };
+    }
+    when_eq(payee_fee_kind, block) {
+      computes fees: { amount_field: carvedFeeAmount; base_field: amount; bearer_field: payee_account_field; position: carved; rule: { kind: tiered; tiers: [{ from_inclusive: concat("", get(first_tier, "from")); to_exclusive: concat("", get(first_tier, "to")); rule: { kind: bps; bps: get(first_tier, "fee"); }; }, { from_inclusive: concat("", get(second_tier, "from")); rule: { kind: exact; field: camel(second_tier_fee); currency_field: currency; }; }]; }; };
+      partitions: { total_field: amount; piece_fields: [netOfCarvedFeeAmount, carvedFeeAmount]; };
+    }
+  }
+  action create {
+    let(metadata_instrument): "metadata.instrumentId";
+    let(metadata_instance): "metadata.instrumentInstanceId";
+    let(metadata_phase): "metadata.phase";
+    agent_description: "Open the payment row before anything moves. The caller supplies the {amount}, the currency, and both party accounts. Fee and derived pieces are computed from the {amount}, callers never supply them. Call pay piece 1 to move the money.";
+    summary: concat("Create a ", words(instrument), " payment");
+    when(derived_amount) {
+      moves: [{
+        key: "derived_amount";
+        operation: internal_transfer.create;
+        bind: {
+          amount: { from: instance; path: concat("fields.", derived_field); };
+          currency: { from: instance; path: fields.currency; };
+          destinationAccountId: { from: instance; path: fields.platformAccountId; };
+          [metadata_instrument]: { from: const; value: instrument; };
+          [metadata_instance]: { from: instance; path: instrumentInstanceId; };
+          [metadata_phase]: { from: const; value: create; };
+          productId: { from: instance; path: productId; };
+          sourceAccountId: { from: instance; path: concat("fields.", camel(derived_bearer), "AccountId"); };
+        };
+        capture: { createDerivedAmountTransferId: transferId; };
+      }];
+    }
+    steps: [];
+  }
+  action pay_piece_1 {
+    let(metadata_instrument): "metadata.instrumentId";
+    let(metadata_instance): "metadata.instrumentInstanceId";
+    let(metadata_phase): "metadata.phase";
+    agent_description: concat("Move the first piece from the ", words(payer), " to the ", words(payee), ". The payment must be created. This moves the whole amount unless the product carves a payee fee, in which case it moves the net share and pay piece 2 takes the fee.");
+    summary: "Pay piece 1 of the amount through";
+    when_not(fees) {
+      moves: [{ key: transfer; amount: amount; from: payer; to: beneficiary; }];
+    }
+    when(fees) {
+      when_eq(payee_fee_kind, none) {
+        moves: [{ key: transfer; amount: amount; from: payer; to: beneficiary; }];
+      }
+      when_eq(payee_fee_kind, percent) {
+        moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: fields.piece1Amount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payee_account_field); }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: pay_piece_1; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { payPiece1TransferTransferId: transferId; }; }];
+      }
+      when_eq(payee_fee_kind, block) {
+        moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: fields.netOfCarvedFeeAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payee_account_field); }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: pay_piece_1; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { payPiece1TransferTransferId: transferId; }; }];
+      }
+    }
+    steps: [];
+  }
+  when(fees) {
+    action pay_piece_2 {
+      let(metadata_instrument): "metadata.instrumentId";
+      let(metadata_instance): "metadata.instrumentInstanceId";
+      let(metadata_phase): "metadata.phase";
+      agent_description: concat("Move the carved platform fee out of the amount. Call this after pay piece 1. When the product carves no ", words(payee), " fee this only steps the payment forward and moves nothing.");
+      summary: "Pay piece 2 of the amount through";
+      when_eq(payee_fee_kind, percent) {
+        moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: fields.piece2Amount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: fields.platformAccountId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: pay_piece_2; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { payPiece2TransferTransferId: transferId; }; }];
+      }
+      when_eq(payee_fee_kind, block) {
+        moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: fields.carvedFeeAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: fields.platformAccountId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: pay_piece_2; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { payPiece2TransferTransferId: transferId; }; }];
+      }
+      steps: [];
+    }
+    action collect_service_fee {
+      let(metadata_instrument): "metadata.instrumentId";
+      let(metadata_instance): "metadata.instrumentInstanceId";
+      let(metadata_phase): "metadata.phase";
+      agent_description: concat("Finish the payment and collect the service fee the ", words(payer), " owes on top of the amount. Both pieces must already be paid. When the product charges no payer fee this only closes the payment out.");
+      summary: "Collect the payer-side service fee";
+      when_eq(payer_fee_kind, percent) {
+        moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: fields.serviceFeeAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: fields.platformAccountId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: collect_service_fee; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { collectServiceFeeTransferTransferId: transferId; }; }];
+      }
+      when_eq(payer_fee_kind, binding) {
+        moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", payer_fee); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: fields.platformAccountId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: collect_service_fee; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { collectServiceFeeTransferTransferId: transferId; }; }];
+      }
+      steps: [];
+    }
+  }
+}

package/std/settlements/metered.hsx

@@ -0,0 +1,67 @@
+module std.settlements.metered
+
+export instrument metered(
+  payer: party,
+  payee: party,
+  close_by: date,
+  rates: unknown,
+) {
+  let(instrument_words): words(instrument);
+  title: sentence(instrument);
+  agent_description: "Reach for metered when the {payer} is billed per unit at a rate card fixed when the period opens, and the period closes on {close_by}. Every charge is its own transfer. Pick recurring collection for a flat repeating amount and instant transfer for a one-off payment.";
+  summary: "Metered charges from {payer} on a committed rate card";
+  description: "Metered usage: the {payer} is charged per unit at the committed rate card until the period closes on its stored end date";
+
+  fields {
+    close_by: {
+      type: date;
+      description: "End of this metering period; the close makes further charges unreachable";
+    }
+    for item in keys(rates) {
+      let(amount_binding): get(rates, item);
+      let(rate_words): words(item);
+      [amount_binding]: {
+        type: amount_binding;
+        description: "Per-unit price of {rate_words} in SAR minor units, committed at period open";
+      }
+    }
+  }
+
+  parties {
+    payer: payer;
+    beneficiary: payee;
+  }
+
+  lifecycle {
+    states open closed;
+    initial open;
+    for item in keys(rates) {
+      on charge_[item]: open -> open;
+    }
+    on close_period: open -> closed;
+  }
+
+  action create {
+    agent_description: "Open the metering period with its committed rate card. The caller supplies the {close_by} anchor and every per-unit price. The prices are fixed here and no later charge can change them. No money moves.";
+    summary: "Open a {instrument_words} period with its committed rate card";
+    steps: [];
+  }
+
+  for item in keys(rates) {
+    action charge_[item] {
+      let(amount_binding): get(rates, item);
+      let(amount_field): concat(amount_binding);
+      let(rate_words): words(item);
+      agent_description: "Charge one metered {rate_words} at the committed price. The period must still be open, so charge before {close_by}. The transfer posts from the {payer} to the {payee} at once and there is no reversal action.";
+      summary: "Charge one metered {rate_words}; the emission is the transfer itself";
+      moves: [{ amount: amount_field; from: payer; to: beneficiary; key: transfer; }];
+      steps: [];
+    }
+  }
+
+  action close_period {
+    summary: "Close the metering period; no further usage can be charged";
+    due: { field: close_by; };
+    steps: [];
+  }
+}

package/std/settlements/pooled_split.hsx

@@ -0,0 +1,68 @@
+module std.settlements.pooled_split
+
+export instrument pooled_split<C>(payer: party, amount: money<C>, payout_due: date, split: block) {
+  let(recipients): keys_except(split, "remainder_to");
+  let(recipient_count): len(recipients);
+  let(remainder_recipient): get(split, "remainder_to");
+  fields {
+    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
+    [payer]AccountId { type: account<C>; description: concat("The ", words(payer), " account"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
+    amount { type: money<C>; description: concat("The pooled period total in {C} minor units; the share fields below partition it exactly"); }
+    payout_due { type: date; description: "The period's payout date; the pool distributes from it"; }
+    for index in recipient_count {
+      let(recipient): at(recipients, index);
+      let(share_bps): get(split, recipient);
+      [recipient]AccountId { type: account<C>; description: concat("The ", words(recipient), " account"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
+      [recipient]ShareAmount {
+        type: money<C>;
+        description: concat(div_floor(basis_points(share_bps), 100), "% of ", amount, if_eq(recipient, remainder_recipient, " (carries the integer-division remainder): ", ": "), "the ", words(recipient), "'s share. Computed as floor(", amount, " * ", basis_points(share_bps), " / 10000) in {C} minor units");
+      }
+    }
+  }
+  lifecycle {
+    states created;
+    initial created;
+    for index in sub(recipient_count, 1) { states pooling_[index]; }
+    states pooled;
+    for index in sub(recipient_count, 1) { states distributing_[index]; }
+    states distributed;
+    for index in recipient_count {
+      let(fund_from): if_eq(index, 1, "created", concat("pooling_", sub(index, 1)));
+      let(fund_to): if_eq(index, recipient_count, "pooled", concat("pooling_", index));
+      on fund_share_[index]: [fund_from] -> [fund_to];
+      let(distribute_from): if_eq(index, 1, "pooled", concat("distributing_", sub(index, 1)));
+      let(distribute_to): if_eq(index, recipient_count, "distributed", concat("distributing_", index));
+      on distribute_share_[index]: [distribute_from] -> [distribute_to];
+    }
+  }
+  parties { beneficiary: concat(camel(at(recipients, 1)), "AccountId"); payer: concat(camel(payer), "AccountId"); }
+  required: concat_lists([concat(camel(payer), "AccountId")], suffix_each(recipients, "AccountId"), [concat("", amount), concat("", payout_due)], suffix_each(recipients, "ShareAmount"), ["currency"]);
+  title: sentence(instrument);
+  id_prefix: prefix(instrument);
+  agent_description: concat("Reach for ", words(instrument), " when the ", words(payer), " funds one period total that is then split across ", recipient_count, " fixed recipients by stored share amounts. Callers fund the pool one share at a time. Each recipient's payout fires from the stored payout date, not from a call.");
+  summary: concat("Period pool from ", words(payer), " split ", recipient_count, " ways");
+  description: concat("Pooled split: the ", words(payer), " pools the period's ", amount, " share by share; the pool distributes to every recipient in full on the stored payout date");
+  partitions { totalField: amount; pieceFields: suffix_each(recipients, "ShareAmount"); }
+  action create {
+    agent_description: concat("Open a ", words(instrument), " period and provision the escrow account the pool sits in. This is the first call on the period, and funding a share refuses until it lands. It moves no money.");
+    summary: concat("Open a ", words(instrument), " period");
+    moves: [];
+    steps: [{ operation: "account.escrow.provision"; bind: { currency: { from: instance; path: "fields.currency"; }; "owner.id": { from: instance; path: productId; }; "owner.type": { from: const; value: product; }; productId: { from: instance; path: productId; }; role: { from: const; value: product_escrow; }; }; capture: { escrowAccountId: accountId; }; }];
+  }
+  for index in recipient_count {
+    let(recipient): at(recipients, index);
+    let(share_field): concat(camel(recipient), "ShareAmount");
+    action fund_share_[index] {
+      agent_description: concat("Move share ", index, " of the period total, the ", words(recipient), "'s cut, from the ", words(payer), " into the pool escrow. Shares fund in order, so every earlier share must be in already. It debits the ", words(payer), " for real. The pool pays out from the stored payout date with no release call.");
+      summary: concat("Pool share ", index, " of the period total");
+      moves: [{ amount: share_field; from: payer; to: refs.escrowAccountId; key: transfer; }];
+      steps: [];
+    }
+    action distribute_share_[index] {
+      summary: concat("Distribute the ", words(recipient), "'s share of the pool");
+      due { field: payout_due; }
+      moves: [{ amount: share_field; from: refs.escrowAccountId; to: recipient; key: transfer; }];
+      steps: [];
+    }
+  }
+}

package/std/settlements/premium_forward.hsx

@@ -0,0 +1,257 @@
+module std.settlements.premium_forward
+
+export instrument premium_forward<C>(
+  payer: party,
+  carrier: party,
+  amount: money<C>,
+  bind: condition,
+  commission: percent,
+  policy_ref: optional<text>,
+  renewal_due: optional<date>,
+  endorsement: optional<condition>,
+) {
+  let(instrument_words): words(instrument);
+  let(bind_name): concat(bind);
+  let(payer_field): camel(concat(payer, "_account_id"));
+  let(carrier_field): camel(concat(carrier, "_account_id"));
+  let(amount_field): concat(amount);
+  let(net_bps): sub(10000, commission);
+  let(fee_bps): add(commission, 0);
+  let(net_percent): if_eq(net_bps, 9500, "95%", if_eq(net_bps, 9800, "98%", "87.5%"));
+  let(fee_percent): if_eq(fee_bps, 500, "5%", if_eq(fee_bps, 200, "2%", "12.5%"));
+  let(bind_roles): if_eq(len(bind_allowed), 2, ["payer", "beneficiary"], ["beneficiary"]);
+  let(owner_id_key): "owner.id";
+  let(owner_type_key): "owner.type";
+  let(metadata_instrument_key): "metadata.instrumentId";
+  let(metadata_instance_key): "metadata.instrumentInstanceId";
+  let(metadata_phase_key): "metadata.phase";
+  let(bind_capture_key): camel(concat(bind, "_transfer_transfer_id"));
+  let(fee_port_key): "x-hyperscale-fee-collection-port";
+  let(reference_filter_key): "x-hyperscale-reference-filter";
+
+  title: sentence(instrument);
+  agent_description: "Reach for {instrument_words} when the {payer} pays an insurance premium ahead of cover and the {carrier} must not be paid until the policy binds. The {amount_field} sits in this settlement's own escrow until {bind_name} fires. Binding then forwards {net_percent} to the {carrier} and {fee_percent} to the platform.";
+  summary: "Premium held for the {carrier} until the policy binds";
+  description: "Premium forward: the {payer} funds the {amount_field} into this settlement's own escrow; binding through {bind_name} forwards it to the {carrier} exactly once, minus the platform commission";
+  partitions: { total_field: amount_field; piece_fields: [piece1Amount, piece2Amount]; };
+
+  fields {
+    platform_account_id: {
+      type: account;
+      description: "The product fee collection account";
+      pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$";
+      [fee_port_key]: true;
+      [reference_filter_key]: { column: role; values: [customer_balance, product_revenue]; };
+    }
+    amount: {
+      type: money<C>;
+      description: "The gross held amount in {C} minor units; the piece fields below partition it exactly";
+    }
+    piece1_amount: {
+      type: money<C>;
+      description: "{net_percent} of {amount_field} (carries the integer-division remainder): released to the {carrier}. Computed as floor({amount_field} * {net_bps} / 10000) in {C} minor units";
+    }
+    piece2_amount: {
+      type: money<C>;
+      description: "{fee_percent} of {amount_field}: released to the platform. Computed as floor({amount_field} * {fee_bps} / 10000) in {C} minor units";
+    }
+    when(policy_ref) {
+      policy_ref: {
+        type: text;
+        description: "Immutable external policy reference recorded with this forward";
+        max_length: 180;
+        min_length: 1;
+      }
+    }
+    when(renewal_due) {
+      renewal_due: {
+        type: date;
+        description: "Stored renewal due condition for the forwarded policy";
+      }
+    }
+  }
+
+  parties { payer: payer; beneficiary: carrier; }
+
+  lifecycle {
+    states created funding_1 funded releasing_1 released abandoned;
+    when(endorsement) { states endorsed lapsed; }
+    initial created;
+    on fund_piece_1: created -> funding_1;
+    on fund_piece_2: funding_1 -> funded;
+    on [bind]: funded -> releasing_1;
+    on forward_piece_2: releasing_1 -> released;
+    on unfund_piece_1: funding_1 -> abandoned;
+    on abandon: created -> abandoned;
+    when(endorsement) {
+      on [endorsement]: released -> endorsed;
+      on lapse: released|endorsed -> lapsed;
+    }
+  }
+
+  action create {
+    agent_description: "Open the {instrument_words} and provision the escrow account that holds the funds. This is the first call on the settlement, and funding refuses until it lands. It moves no money.";
+    summary: "Create a {instrument_words} settlement";
+    steps: [{
+      operation: "account.escrow.provision";
+      bind: {
+        currency: { from: instance; path: fields.currency; };
+        [owner_id_key]: { from: instance; path: productId; };
+        [owner_type_key]: { from: const; value: product; };
+        product_id: { from: instance; path: productId; };
+        role: { from: const; value: product_escrow; };
+      };
+      capture: { escrow_account_id: accountId; };
+    }];
+  }
+
+  action fund_piece_1 {
+    agent_description: "Move the {carrier}'s share of the premium from the {payer} into escrow. The settlement must exist and be unfunded. It debits the {payer} for real, and piece 2 still has to fund before the policy can bind.";
+    summary: "Fund piece 1 of the held amount into escrow";
+    moves: [{
+      key: transfer; operation: "internal_transfer.create";
+      bind: {
+        amount: { from: instance; path: fields.piece1Amount; };
+        currency: { from: instance; path: fields.currency; };
+        destination_account_id: { from: instance; path: refs.escrowAccountId; };
+        source_account_id: { from: instance; path: concat("fields.", payer_field); };
+        [metadata_instrument_key]: { from: const; value: instrument; };
+        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
+        [metadata_phase_key]: { from: const; value: fund_piece_1; };
+        product_id: { from: instance; path: productId; };
+      };
+      capture: { fund_piece_1_transfer_transfer_id: transferId; };
+    }];
+    steps: [];
+  }
+
+  action fund_piece_2 {
+    agent_description: "Move the platform commission piece from the {payer} into escrow, which completes funding. Piece 1 must be in escrow first. It debits the {payer} for real, and the premium is then held whole.";
+    summary: "Fund piece 2 of the held amount into escrow";
+    moves: [{
+      key: transfer; operation: "internal_transfer.create";
+      bind: {
+        amount: { from: instance; path: fields.piece2Amount; };
+        currency: { from: instance; path: fields.currency; };
+        destination_account_id: { from: instance; path: refs.escrowAccountId; };
+        source_account_id: { from: instance; path: concat("fields.", payer_field); };
+        [metadata_instrument_key]: { from: const; value: instrument; };
+        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
+        [metadata_phase_key]: { from: const; value: fund_piece_2; };
+        product_id: { from: instance; path: productId; };
+      };
+      capture: { fund_piece_2_transfer_transfer_id: transferId; };
+    }];
+    steps: [];
+  }
+
+  action [bind] {
+    agent_description: "Bind the policy through {bind_name} and forward the {carrier}'s share out of escrow. The premium must be fully funded first, and the call carries the decision reference the product asks for. Money leaves escrow here and does not come back.";
+    summary: "Confirm through {bind_name} and start the forward payout";
+    input: {
+      additional_properties: false;
+      properties: {
+        for item in keys(bind_fields) {
+          [item]: {
+            description: "Required decision reference retained in the operation receipt";
+            max_length: 180; min_length: 1; type: string;
+          }
+        }
+      };
+      required: keys(bind_fields);
+      type: object;
+    };
+    port: { allowed_parties: bind_roles; };
+    moves: [{
+      key: transfer; operation: "internal_transfer.create";
+      bind: {
+        amount: { from: instance; path: fields.piece1Amount; };
+        currency: { from: instance; path: fields.currency; };
+        destination_account_id: { from: instance; path: concat("fields.", carrier_field); };
+        source_account_id: { from: instance; path: refs.escrowAccountId; };
+        [metadata_instrument_key]: { from: const; value: instrument; };
+        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
+        [metadata_phase_key]: { from: const; value: bind; };
+        product_id: { from: instance; path: productId; };
+      };
+      capture: { [bind_capture_key]: transferId; };
+    }];
+    steps: [];
+  }
+
+  action forward_piece_2 {
+    agent_description: "Pay the platform commission out of escrow to the fee collection account, which closes the forward. {bind_name} must have run first. Money leaves escrow here and does not come back.";
+    summary: "Forward piece 2 of the held amount";
+    moves: [{
+      key: transfer; operation: "internal_transfer.create";
+      bind: {
+        amount: { from: instance; path: fields.piece2Amount; };
+        currency: { from: instance; path: fields.currency; };
+        destination_account_id: { from: instance; path: fields.platformAccountId; };
+        source_account_id: { from: instance; path: refs.escrowAccountId; };
+        [metadata_instrument_key]: { from: const; value: instrument; };
+        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
+        [metadata_phase_key]: { from: const; value: forward_piece_2; };
+        product_id: { from: instance; path: productId; };
+      };
+      capture: { forward_piece_2_transfer_transfer_id: transferId; };
+    }];
+    steps: [];
+  }
+
+  action unfund_piece_1 {
+    agent_description: "Return the {carrier}'s share from escrow to the {payer} and abandon the forward. It runs only while funding stopped after piece 1, before the policy binds. The settlement ends abandoned.";
+    summary: "Return piece 1 to the {payer} on abandonment";
+    moves: [{
+      key: transfer; operation: "internal_transfer.create";
+      bind: {
+        amount: { from: instance; path: fields.piece1Amount; };
+        currency: { from: instance; path: fields.currency; };
+        destination_account_id: { from: instance; path: concat("fields.", payer_field); };
+        source_account_id: { from: instance; path: refs.escrowAccountId; };
+        [metadata_instrument_key]: { from: const; value: instrument; };
+        [metadata_instance_key]: { from: instance; path: instrumentInstanceId; };
+        [metadata_phase_key]: { from: const; value: unfund_piece_1; };
+        product_id: { from: instance; path: productId; };
+      };
+      capture: { unfund_piece_1_transfer_transfer_id: transferId; };
+    }];
+    steps: [];
+  }
+
+  action abandon {
+    agent_description: "Close a {instrument_words} that was never funded. The escrow account must be empty, so this refuses once any piece is in it. It moves no money and the settlement ends here.";
+    summary: "Abandon the settlement before any money is held";
+    requires drained: { path: refs.escrowAccountId; };
+    steps: [];
+  }
+
+  when(endorsement) {
+    action [endorsement] {
+      agent_description: "Record one endorsement against a policy that already forwarded, from evidence the caller supplies. The forward must be released first, and only the {carrier} may call it. It moves no money and it does not change the premium.";
+      summary: "Record one non-money endorsement from external evidence";
+      input: {
+        additional_properties: false;
+        properties: {
+          for item in keys(endorsement_fields) {
+            [item]: {
+              description: "Required decision reference retained in the operation receipt";
+              max_length: 180; min_length: 1; type: string;
+            }
+          }
+        };
+        required: keys(endorsement_fields);
+        type: object;
+      };
+      capture_input: { endorsement_evidence_reference: evidenceReference; };
+      port: { allowed_parties: [beneficiary]; };
+      steps: [];
+    }
+    action lapse {
+      summary: "Mark the forwarded policy lapsed at its stored renewal due condition";
+      due: { field: renewal_due; };
+      requires drained: { path: refs.escrowAccountId; };
+      steps: [];
+    }
+  }
+}