@hyperscale0/hsx 2.1.1 → 2.2.0

package/std/money_flows/held_payment.hsx

@@ -42,6 +42,8 @@ module std.money_flows.held_payment
 //   A zero charge keeps the flow with a zero fee.
 // - `cancel_offer_life`: ISO 8601 duration a cancellation quote stays open, required with `cancel_charge_bps`.
 //
+// - `private_actions`: Suppress automatic aliases. Publish chosen actions with `expose`.
+//
 // ### Decision ports
 // - `release`: Port deciding release authorization, answered by allowed parties declared in the port.
 //
@@ -61,7 +63,7 @@ module std.money_flows.held_payment
 // }
 // port confirm_delivery { allowed: [buyer] }
 // ```
-export instrument held_payment<C>(payer: party, payee: party, amount: money<C>, release: condition, fees: optional<block>, on_cancel: optional<block>, derived_amount: optional<block>, release_to: optional<party>, whole_amount: optional<block>, release_action: optional<text>, whole_fee: optional<money<C>>, reference: optional<text>, upstream: optional<ref>, id_prefix_override: optional<text>, cancel_charge_bps: optional<integer>, cancel_offer_life: optional<text>) {
+export instrument held_payment<C>(payer: party, payee: party, amount: money<C>, release: condition, fees: optional<block>, on_cancel: optional<block>, derived_amount: optional<block>, release_to: optional<party>, whole_amount: optional<block>, release_action: optional<text>, whole_fee: optional<money<C>>, reference: optional<text>, upstream: optional<ref>, id_prefix_override: optional<text>, cancel_charge_bps: optional<integer>, cancel_offer_life: optional<text>, private_actions: optional<boolean>) {
   let(release_name): release;
   let(release_actor_text): if_eq(len(release_allowed), 1, words(at(release_allowed, 1)), concat("a party allowed by ", release));
   let(payer_account_field): camel(concat(payer, "_account_id"));
@@ -300,6 +302,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
   when(payee_fee) {
     when(on_cancel) {
       action fund_piece_2 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -310,6 +313,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action fund_piece_3 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -321,6 +325,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       }
       when_eq(payer_fee_kind, percent) {
         action collect_service_fee {
+    when(private_actions) { public: none; }
           let(metadata_instrument): "metadata.instrumentId";
           let(metadata_instance): "metadata.instrumentInstanceId";
           let(metadata_phase): "metadata.phase";
@@ -331,6 +336,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         }
       }
       action release_piece_2 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -342,6 +348,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action release_piece_3 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -351,6 +358,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action refund_piece_2 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -362,6 +370,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action refund_piece_3 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -371,6 +380,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action unfund_piece_1 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -380,6 +390,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action unfund_piece_2 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -390,6 +401,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       }
       when_eq(payer_fee_kind, percent) {
         action unfund_piece_3 {
+    when(private_actions) { public: none; }
           let(metadata_instrument): "metadata.instrumentId";
           let(metadata_instance): "metadata.instrumentInstanceId";
           let(metadata_phase): "metadata.phase";
@@ -430,6 +442,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     computes derived: { field: derived_field; source_field: derived_source; rounding: floor; rule: { kind: percentage_of; bps: derived_rule; }; };
   }
   action create {
+    when(private_actions) { public: none; }
     let(owner_id): "owner.id";
     let(owner_type): "owner.type";
     agent_description: concat("Open the ", words(instrument), " and provision the escrow account that holds the funds. This is the first call, and every funding and release action moves money through that account. It does not move the held amount itself.");
@@ -444,6 +457,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     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; }; }];
   }
   action fund_piece_1 {
+    when(private_actions) { public: none; }
     let(metadata_instrument): "metadata.instrumentId";
     let(metadata_instance): "metadata.instrumentInstanceId";
     let(metadata_phase): "metadata.phase";
@@ -465,6 +479,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     steps: [];
   }
   action [release_name] {
+    when(private_actions) { public: none; }
     let(metadata_instrument): "metadata.instrumentId";
     let(metadata_instance): "metadata.instrumentInstanceId";
     let(metadata_phase): "metadata.phase";
@@ -498,6 +513,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
   }
   when(release_deadline) {
     action release_on_deadline {
+    when(private_actions) { public: none; }
       let(metadata_instrument): "metadata.instrumentId";
       let(metadata_instance): "metadata.instrumentInstanceId";
       let(metadata_phase): "metadata.phase";
@@ -514,6 +530,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
   }
   when(on_cancel) {
     action cancel {
+    when(private_actions) { public: none; }
       let(metadata_instrument): "metadata.instrumentId";
       let(metadata_instance): "metadata.instrumentInstanceId";
       let(metadata_phase): "metadata.phase";
@@ -530,6 +547,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
   }
   when(has_cancel_quote) {
     action quote_cancellation {
+    when(private_actions) { public: none; }
       agent_description: concat("Price the cancellation and hold that price open. No money moves. The charge the ", words(payee), " keeps and the refund the ", words(payer), " gets back are worked out here and frozen for ", cancel_offer_life, ", after which a fresh call prices it again. Call cancel to spend the quote.");
       summary: "Price the cancellation and hold that price open";
       when(release_deadline) { deadline { field: release_deadline; }; }
@@ -546,6 +564,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
     action cancel {
+    when(private_actions) { public: none; }
       let(metadata_instrument): "metadata.instrumentId";
       let(metadata_instance): "metadata.instrumentInstanceId";
       let(metadata_phase): "metadata.phase";
@@ -557,6 +576,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
     action retain_cancellation_charge {
+    when(private_actions) { public: none; }
       let(metadata_instrument): "metadata.instrumentId";
       let(metadata_instance): "metadata.instrumentInstanceId";
       let(metadata_phase): "metadata.phase";
@@ -574,6 +594,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
   when(payee_fee) {
     when_not(on_cancel) {
       action fund_piece_2 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -585,6 +606,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action release_piece_2 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -595,6 +617,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action unfund_piece_1 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -608,6 +631,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
   when_not(payee_fee) {
     when(cancel_splits) {
       action fund_piece_2 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -618,6 +642,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action release_piece_2 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -627,6 +652,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action refund_piece_2 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -636,6 +662,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
         steps: [];
       }
       action unfund_piece_1 {
+    when(private_actions) { public: none; }
         let(metadata_instrument): "metadata.instrumentId";
         let(metadata_instance): "metadata.instrumentInstanceId";
         let(metadata_phase): "metadata.phase";
@@ -647,6 +674,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     }
   }
   action abandon {
+    when(private_actions) { public: none; }
     agent_description: concat("Close a ", words(instrument), " 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 with no way back.");
     summary: "Abandon the settlement before any money is held";
     requires drained: { path: refs.escrowAccountId; };
@@ -654,6 +682,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     steps: [];
   }
   action dispute {
+    when(private_actions) { public: none; }
     agent_description: concat("Freeze a funded ", words(instrument), " so neither release nor refund can run until the parties settle the disagreement. No money moves and the whole balance stays put. Only a funded ", words(instrument), " disputes.");
     description: concat("Freezes funded ", words(instrument), ", preserving the entire balance while the parties decide what happens next.");
     summary: concat("Dispute a ", words(instrument), " settlement");
@@ -662,6 +691,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     steps: [];
   }
   action resume {
+    when(private_actions) { public: none; }
     agent_description: concat("Lift the dispute hold and put the ", words(instrument), " back where it was, funded and ready to release. No money moves and the balance was never touched. Only a disputed ", words(instrument), " resumes. Use this when the parties settled without a refund.");
     description: concat("Ends the dispute hold without moving money and returns the fully funded ", words(instrument), " to its first milestone.");
     summary: concat("Resume a ", words(instrument), " settlement");
@@ -707,6 +737,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
     parties { beneficiary: payee_account_field; payer: payer_account_field; }
     required: [payer_account_field, payee_account_field, platformAccountId, amount, whole_fee_field, currency, release_deadline];
     action create {
+    when(private_actions) { public: none; }
       let(owner_id): "owner.id";
       let(owner_type): "owner.type";
       agent_description: concat("Open the ", words(instrument), " and provision the escrow account that holds the money. No money moves on this call. ", release_deadline, " is fixed here and never moves again, so one date governs the early release, the cancellation, and the automatic payout.");
@@ -715,6 +746,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       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; }; }];
     }
     action fund {
+    when(private_actions) { public: none; }
       agent_description: concat("Move ", amount, " from the ", words(payer), " into escrow and charge ", whole_fee_field, " on top to the platform account, as one linked batch. This moves money and the ", words(payer), " pays both. Only a created hold funds. The fee never enters escrow, so it is non-refundable however the hold ends.");
       summary: "Fund the hold and collect the custody fee";
       moves: [
@@ -725,6 +757,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
     action [release_action] {
+    when(private_actions) { public: none; }
       agent_description: concat("Pay the ", words(payee), " the whole ", amount, " out of escrow ahead of ", release_deadline, ". This moves money and does not reverse. Only a funded hold releases, the caller must act as ", words(at(release_allowed, 1)), ", and the call is refused once ", release_deadline, " passes. The custody fee stays posted.");
       summary: concat("Release the hold to the ", words(payee), " early");
       deadline: { field: release_deadline; };
@@ -734,6 +767,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
     action release_on_deadline {
+    when(private_actions) { public: none; }
       summary: concat("Release the hold to the ", words(payee), " on its release date");
       due: { field: release_deadline; };
       event_name: concat(instrument, ".released_on_deadline");
@@ -741,6 +775,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
     action cancel {
+    when(private_actions) { public: none; }
       agent_description: concat("Return the whole ", amount, " from escrow to the ", words(payer), " and end the hold. This moves money and does not reverse. Only a funded hold cancels, and only before ", release_deadline, " passes. The custody fee stays posted because the custody it paid for was already provided.");
       summary: "Cancel the hold and return the held amount";
       deadline: { field: release_deadline; };
@@ -749,6 +784,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
     action abandon {
+    when(private_actions) { public: none; }
       agent_description: concat("Close a ", words(instrument), " that was opened and never funded. No money has moved and the escrow must be empty, so this is a lifecycle transition only. A funded hold refuses. Release it to the ", words(payee), " or cancel it back to the ", words(payer), " instead.");
       summary: "Abandon the hold before it is funded";
       moves: [];
@@ -756,6 +792,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
     action dispute {
+    when(private_actions) { public: none; }
       agent_description: concat("Freeze a funded ", words(instrument), " so neither release nor refund can run until the parties settle the disagreement. No money moves and the whole balance stays put. Only a funded ", words(instrument), " disputes.");
       description: concat("Freezes funded ", words(instrument), ", preserving the entire balance while the parties decide what happens next.");
       summary: concat("Dispute a ", words(instrument), " settlement");
@@ -764,6 +801,7 @@ export instrument held_payment<C>(payer: party, payee: party, amount: money<C>,
       steps: [];
     }
     action resume {
+    when(private_actions) { public: none; }
       agent_description: concat("Lift the dispute hold and put the ", words(instrument), " back where it was, funded and ready to release. No money moves and the balance was never touched. Only a disputed ", words(instrument), " resumes. Use this when the parties settled without a refund.");
       description: concat("Ends the dispute hold without moving money and returns the fully funded ", words(instrument), " to its first milestone.");
       summary: concat("Resume a ", words(instrument), " settlement");

package/std/money_flows/index.hsx

@@ -1,3 +1,4 @@
 module std.money_flows
 
-// Money flows are imported by their full std.money_flows.<name> path.
+// Import named exports from "std/money_flows".
+// SEMANTICS.md groups modules by lifecycle and explains their money effects.

package/std/money_flows/metered.hsx

@@ -11,10 +11,6 @@ module std.money_flows.metered
 // - vs `scheduled`: `metered` charges variable amounts per event calculated from consumed units and committed
 //   rate card prices. `scheduled` executes transfers on fixed calendar recurrence intervals (`every`, `first_due`)
 //   with predetermined amounts or installments.
-// - vs `recurring_collection`: `metered` calculates and executes real ledger transfers for each usage charge.
-//   `recurring_collection` is a lightweight status tracker for collection runs without balance transfers or rate cards.
-// - vs `instant_transfer`: `instant_transfer` executes a single immediate payment. `metered` manages a stateful
-//   open billing cycle accepting multiple usage charges under a fixed rate card.
 //
 // ### Parameters
 // - `payer`: The customer being billed for usage.
@@ -49,7 +45,7 @@ export instrument metered(
 ) {
   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.";
+  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 scheduled 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";
 

package/std/money_flows/scheduled.hsx

@@ -5,6 +5,7 @@ module std.money_flows.scheduled
 // ### Purpose
 // `scheduled` automates time-anchored payment series between one payer and one payee.
 // It supports three modes:
+//
 // 1. Installment plan: Partitions a fixed total amount into `count` installments, each collected on its own stored date.
 // 2. Open recurring subscription: Charges a recurring amount on an interval `every` until an `until` port fires.
 // 3. Debt obligation: Manages legally binding multi-installment debt with delinquency tracking, mandate evidence, and child payment records.
@@ -12,8 +13,6 @@ module std.money_flows.scheduled
 // ### Selection guidance
 // - vs `metered`: `scheduled` executes calendar-based recurring charges or fixed installment plans.
 //   `metered` bills variable usage per event based on a committed rate card.
-// - vs `recurring_collection`: `scheduled` actively moves ledger balances and partitions amounts.
-//   `recurring_collection` is a lightweight status tracker for collection runs without balance transfers.
 // - vs `rotating_pool`: `scheduled` coordinates one payer to one payee on a calendar.
 //   `rotating_pool` coordinates a multi-party peer circle where members rotate turns receiving the entire pot.
 //
@@ -73,8 +72,6 @@ export instrument scheduled<C>(
   agent_description: "Reach for scheduled when one payer owes one payee on a calendar. It covers a plan of fixed installments partitioning one total, an obligation whose installments are paid through child payment records and can go delinquent, and an open period charge that repeats until a cancel port fires. Rotating pool is for a group taking turns.";
   when_not(mode) {
     let(instrument_words): words(instrument);
-    let(first_percent): if_eq(count, 3, "33.34%", if_eq(count, 2, "50%", "25%"));
-    let(other_percent): if_eq(count, 3, "33.33%", if_eq(count, 2, "50%", "25%"));
 
     title: sentence(instrument);
     summary: "{count}-installment schedule from {payer} to {payee}";
@@ -91,11 +88,10 @@ export instrument scheduled<C>(
         description: "Due date of the first installment; installment k falls {every} after its predecessor";
       }
       for i in count {
-        let(piece_percent): if_eq(i, 1, first_percent, other_percent);
         let(remainder_words): if_eq(i, 1, " (carries the integer-division remainder)", "");
         installment[i]Amount: {
           type: money<C>;
-          description: "Installment {i} of {count}{remainder_words}: about {piece_percent} of {amount}, collected on its own stored-date anchor";
+          description: "Installment {i} of {count}{remainder_words}: a stored share of {amount}, collected on its own stored-date anchor";
         }
       }
     }
@@ -153,13 +149,7 @@ export instrument scheduled<C>(
       let(parent_ref_field): camel(concat(instrument, "_id"));
       let(has_advance): advance_to;
       let(same_debtor): if_eq(payer, debtor, true, false);
-      let(parent_statuses): if_eq(count, 2,
-        ["active", "installment_1_delinquent", "installment_2_delinquent"],
-        if_eq(count, 3,
-          ["active", "installment_1_delinquent", "installment_2_delinquent", "installment_3_delinquent"],
-          ["active", "installment_1_delinquent", "installment_2_delinquent", "installment_3_delinquent", "installment_4_delinquent"]
-        )
-      );
+      let(parent_statuses): concat_lists(["active"], names("installment_", count, "_delinquent"));
       let(delinquent_statuses): names("installment_", count, "_delinquent");
       let(last_offset): scale_duration(every, sub(count, 1));
       let(reference_filter_key): "x-hyperscale-reference-filter";
@@ -196,51 +186,13 @@ export instrument scheduled<C>(
           parent_field: concat("installment", i, "Amount");
         };
       }
-      when(has_advance) {
-        when_not(same_debtor) {
-          required: if_eq(count, 2,
-            [advance_field, payee_field, payer_field, debtor_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount"],
-            if_eq(count, 3,
-              [advance_field, payee_field, payer_field, debtor_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount", "installment3Amount"],
-              [advance_field, payee_field, payer_field, debtor_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount", "installment3Amount", "installment4Amount"]
-            )
-          );
-        }
-        when(same_debtor) {
-          when_not(derived_amount) {
-            required: if_eq(count, 3,
-              [advance_field, payee_field, payer_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount", "installment3Amount"],
-              [advance_field, payee_field, payer_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount", "installment3Amount", "installment4Amount"]
-            );
-          }
-          when(derived_amount) {
-            required: if_eq(count, 2,
-              [advance_field, payee_field, payer_field, "platformAccountId", "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount"],
-              [advance_field, payee_field, payer_field, "platformAccountId", "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount", "installment3Amount", "installment4Amount"]
-            );
-          }
-        }
-      }
-      when_not(has_advance) {
-        when_not(same_debtor) {
-          required: if_eq(count, 2,
-            [payee_field, payer_field, debtor_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount"],
-            if_eq(count, 3,
-              [payee_field, payer_field, debtor_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount", "installment3Amount"],
-              [payee_field, payer_field, debtor_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount", "installment3Amount", "installment4Amount"]
-            )
-          );
-        }
-        when(same_debtor) {
-          required: if_eq(count, 2,
-            [payee_field, payer_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount"],
-            if_eq(count, 3,
-              [payee_field, payer_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount", "installment3Amount"],
-              [payee_field, payer_field, "currency", amount_field, first_due_field, "installment1Amount", "installment2Amount", "installment3Amount", "installment4Amount"]
-            )
-          );
-        }
-      }
+      required: concat_lists(
+        [payee_field, payer_field, "currency", amount_field, first_due_field],
+        names("installment", count, "Amount"),
+        if_eq(has_advance, false, [], [advance_field]),
+        if_eq(same_debtor, true, [], [debtor_field]),
+        if_eq(derived_amount, false, [], ["platformAccountId"])
+      );
 
       fields {
         when(has_advance) {
@@ -315,68 +267,26 @@ export instrument scheduled<C>(
         when_not(same_debtor) { payer: payer; }
       }
 
-      let(count_is_2): if_eq(count, 2, true, false);
-      let(count_is_3): if_eq(count, 3, true, false);
-      let(count_is_4): if_eq(count, 4, true, false);
-      when(count_is_2) {
-        lifecycle {
-          states draft;
-          when(has_advance) { states approved; }
-          states active installment_1_delinquent installment_2_delinquent written_off repaid;
-          initial draft;
-          when(has_advance) { on approve: draft -> approved; }
-          when_not(has_advance) { on approve: draft -> active; }
-          when(has_advance) { on advance: approved -> active; }
-          on collect_installment_1: installment_1_delinquent|installment_2_delinquent -> active;
-          on collect_installment_2: installment_1_delinquent|installment_2_delinquent -> active;
-          on mark_installment_1_delinquent: active|installment_2_delinquent -> installment_1_delinquent;
-          on mark_installment_2_delinquent: active|installment_1_delinquent -> installment_2_delinquent;
-          on complete: active|installment_1_delinquent|installment_2_delinquent -> repaid;
-          when(has_advance) { on write_off: draft|approved|active|installment_1_delinquent|installment_2_delinquent -> written_off; }
-          when_not(has_advance) { on write_off: draft|active|installment_1_delinquent|installment_2_delinquent -> written_off; }
-        }
-      }
-      when(count_is_3) {
-        lifecycle {
-          states draft;
-          when(has_advance) { states approved; }
-          states active installment_1_delinquent installment_2_delinquent installment_3_delinquent written_off repaid;
-          initial draft;
-          when(has_advance) { on approve: draft -> approved; }
-          when_not(has_advance) { on approve: draft -> active; }
-          when(has_advance) { on advance: approved -> active; }
-          on collect_installment_1: installment_1_delinquent|installment_2_delinquent|installment_3_delinquent -> active;
-          on collect_installment_2: installment_1_delinquent|installment_2_delinquent|installment_3_delinquent -> active;
-          on collect_installment_3: installment_1_delinquent|installment_2_delinquent|installment_3_delinquent -> active;
-          on mark_installment_1_delinquent: active|installment_2_delinquent|installment_3_delinquent -> installment_1_delinquent;
-          on mark_installment_2_delinquent: active|installment_1_delinquent|installment_3_delinquent -> installment_2_delinquent;
-          on mark_installment_3_delinquent: active|installment_1_delinquent|installment_2_delinquent -> installment_3_delinquent;
-          on complete: active|installment_1_delinquent|installment_2_delinquent|installment_3_delinquent -> repaid;
-          when(has_advance) { on write_off: draft|approved|active|installment_1_delinquent|installment_2_delinquent|installment_3_delinquent -> written_off; }
-          when_not(has_advance) { on write_off: draft|active|installment_1_delinquent|installment_2_delinquent|installment_3_delinquent -> written_off; }
-        }
-      }
-      when(count_is_4) {
-        lifecycle {
-          states draft;
-          when(has_advance) { states approved; }
-          states active installment_1_delinquent installment_2_delinquent installment_3_delinquent installment_4_delinquent written_off repaid;
-          initial draft;
-          when(has_advance) { on approve: draft -> approved; }
-          when_not(has_advance) { on approve: draft -> active; }
-          when(has_advance) { on advance: approved -> active; }
-          on collect_installment_1: installment_1_delinquent|installment_2_delinquent|installment_3_delinquent|installment_4_delinquent -> active;
-          on collect_installment_2: installment_1_delinquent|installment_2_delinquent|installment_3_delinquent|installment_4_delinquent -> active;
-          on collect_installment_3: installment_1_delinquent|installment_2_delinquent|installment_3_delinquent|installment_4_delinquent -> active;
-          on collect_installment_4: installment_1_delinquent|installment_2_delinquent|installment_3_delinquent|installment_4_delinquent -> active;
-          on mark_installment_1_delinquent: active|installment_2_delinquent|installment_3_delinquent|installment_4_delinquent -> installment_1_delinquent;
-          on mark_installment_2_delinquent: active|installment_1_delinquent|installment_3_delinquent|installment_4_delinquent -> installment_2_delinquent;
-          on mark_installment_3_delinquent: active|installment_1_delinquent|installment_2_delinquent|installment_4_delinquent -> installment_3_delinquent;
-          on mark_installment_4_delinquent: active|installment_1_delinquent|installment_2_delinquent|installment_3_delinquent -> installment_4_delinquent;
-          on complete: active|installment_1_delinquent|installment_2_delinquent|installment_3_delinquent|installment_4_delinquent -> repaid;
-          when(has_advance) { on write_off: draft|approved|active|installment_1_delinquent|installment_2_delinquent|installment_3_delinquent|installment_4_delinquent -> written_off; }
-          when_not(has_advance) { on write_off: draft|active|installment_1_delinquent|installment_2_delinquent|installment_3_delinquent|installment_4_delinquent -> written_off; }
+      lifecycle {
+        states draft;
+        when(has_advance) { states approved; }
+        states active;
+        let(states_key): "states";
+        [states_key]: delinquent_statuses;
+        states written_off repaid;
+        initial draft;
+        when(has_advance) { on approve: draft -> approved; on advance: approved -> active; }
+        when_not(has_advance) { on approve: draft -> active; }
+        for i in count {
+          let(target): concat("installment_", i, "_delinquent");
+          let(other_states): without(parent_statuses, target);
+          on collect_installment_[i]: delinquent_statuses -> active;
+          let(mark_action): concat("mark_installment_", i, "_delinquent");
+          on [mark_action]: other_states -> target;
         }
+        on complete: parent_statuses -> repaid;
+        when(has_advance) { on write_off: draft|approved|parent_statuses -> written_off; }
+        when_not(has_advance) { on write_off: draft|parent_statuses -> written_off; }
       }
 
       action create {

package/std/money_flows/threshold_pool.hsx

@@ -14,7 +14,7 @@ module std.money_flows.threshold_pool
 //   `weighted_distribution` pays funds outward from one source pool to many weighted recipients.
 //
 // ### Parameters
-// - `contributor`: The archetype party representing individual contributors.
+// - `contributor`: The party representing individual contributors.
 // - `beneficiary`: The beneficiary party receiving the settled pool if the target is met.
 // - `target`: Total target funding threshold in minor units of currency `C`.
 // - `commitment`: Binding name for individual contributor commitment amounts.
@@ -51,6 +51,13 @@ module std.money_flows.threshold_pool
 //   fail_policy: whole_commitment_refund
 // }
 // ```
+// ### Funding join
+// funding_join configures the flat contribution-instrument mode for a priced
+// obligation. Opening freezes minimum ticket, investor cap, profit and schedule
+// terms. Closing binds the obligation, freezes committed ticket identities and
+// moves the principal once into its funding account. A ticket's engine-owned
+// collection action has no independent payment or clock trigger.
+//
 export instrument threshold_pool<C>(
   contributor: optional<party>,
   beneficiary: optional<party>,
@@ -66,6 +73,7 @@ export instrument threshold_pool<C>(
   memo: optional<text>,
   contribution_instrument: optional<block>,
   wording: optional<block>,
+  funding_join: optional<block>,
 ) {
   when(wording) {
     let(wording_unknown_keys): keys_except(wording, "pool_summary", "pool_description", "create_summary", "commitment_create_summary", "commitment_cancel_summary", "commitment_refund_summary");
@@ -217,6 +225,7 @@ export instrument threshold_pool<C>(
     let(beneficiary_account_field): camel(beneficiary_account);
     let(target_field): camel(target);
     let(close_field): camel(close_by);
+    let(obligation_type): get(funding_join, "obligation");
 
     fields {
       [beneficiary_account_field] { type: account<C>; description: beneficiary_account_description; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
@@ -224,6 +233,18 @@ export instrument threshold_pool<C>(
       currency { type: text; description: currency_description; maxLength: 3; minLength: 3; pattern: "^[A-Z]{3}$"; }
       when(memo) { [memo] { type: text; optional: true; maxLength: 180; minLength: 1; } }
       [target_field] { type: money<C>; description: target_description; }
+      when(funding_join) {
+        fundingAccountId { type: account<C>; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
+        obligationId { type: ref<obligation_type>; optional: true; }
+        minimumTicket: money<C>;
+        investorCapBps { type: integer; minimum: 1; maximum: 9999; }
+        maximumTicket { type: money<C>; optional: true; }
+        fixedProfit: money<C>;
+        installmentCount { type: integer; minimum: 1; maximum: 360; }
+        earningRule { type: text; enum: [per_slice_on_due, on_disbursement]; }
+      }
+    }
+    when(funding_join) { computes derived: { field: maximumTicket; source_field: target_field; rule: { kind: percentage_of; bps: { field: investorCapBps; }; }; rounding: floor; };
     }
     lifecycle {
       states open active failed settled;
@@ -233,14 +254,15 @@ export instrument threshold_pool<C>(
       on fail: open -> failed;
     }
     parties { beneficiary: beneficiary_account_field; }
-    required: [beneficiary_account_field, target_field, currency, close_field];
+    when_not(funding_join) { required: [beneficiary_account_field, target_field, currency, close_field]; }
+    when(funding_join) { required: [beneficiary_account_field, target_field, currency, close_field, fundingAccountId, minimumTicket, investorCapBps, fixedProfit, installmentCount, earningRule]; }
     aggregate_invariants { childField: contribution_amount_field; childInstrumentId: contribution_id; childRefField: contribution_ref_field; childStatuses: [committed_status, collected_status]; parentField: target_field; }
     caller_parked_states { active: active_parked; }
     id_prefix: instrument_id_prefix;
     action create {
       public: none;
       agent_description: "Open the pool before any contribution exists. The caller supplies the target, the currency, the beneficiary account, and the close anchor, and the pool provisions its escrow account. No money moves.";
-      examples: create_examples;
+      when_not(funding_join) { examples: create_examples; }
       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: { [custody_ref]: accountId; }; }];
     }
@@ -263,8 +285,21 @@ export instrument threshold_pool<C>(
     action close {
       public: none;
       agent_description: "Settle the pool once every contribution has been collected into the beneficiary account. No money moves. Refused while any contribution is still uncollected, so wait for the per-contribution collections to run rather than retrying.";
-      examples: close_examples;
-      requires aggregate { instrumentId: contribution_id; over: children; refField: contribution_ref_field; statuses: [collected_status]; check: { kind: all_in; }; }
+      when_not(funding_join) { examples: close_examples; }
+      when_not(funding_join) { requires aggregate { instrumentId: contribution_id; over: children; refField: contribution_ref_field; statuses: [collected_status]; check: { kind: all_in; }; } }
+      when(funding_join) {
+        input: { type: object; additionalProperties: false; properties: { obligationId: { type: string; pattern: get(funding_join, "obligation_pattern"); }; }; required: [obligationId]; };
+        updates: [obligationId];
+        requires refs: { field: obligationId; statuses: [created]; match: { "fields.fundingAccountId": fields.fundingAccountId; "fields.currency": fields.currency; }; };
+        funding: {
+          obligation_field: obligationId; ticket_instrument_id: contribution_id; ticket_ref_field: contribution_ref_field;
+          ticket_amount_field: contribution_amount_field; ticket_investor_field: get(funding_join, "investor_field"); ticket_account_field: get(funding_join, "wallet_account_field");
+          ticket_status: committed_status; collect_action: collect; principal_field: target_field;
+          source_account_path: concat("refs.", custody_ref); destination_account_field: fundingAccountId;
+          terms: { [target_field]: principal; fixedProfit: fixedProfit; installmentCount: installmentCount; earningRule: earningRule; [beneficiary_account_field]: borrowerAccountId; currency: currency; };
+          capture: fundingSnapshot;
+        };
+      }
       moves: [];
       steps: [];
     }