@hyperscale0/hsx 1.0.0-alpha.6 → 1.0.0-rc.1

package/std/settlements/reconciled_payout.hsx

@@ -0,0 +1,77 @@
+module std.settlements.reconciled_payout
+
+export instrument reconciled_payout<C>(
+  payer: party,
+  beneficiary: party,
+  amount: money<C>,
+  beneficiary_ref: text,
+  settle_by: date,
+  matched_within: integer,
+  matched_ceiling: integer,
+) {
+  let(payer_account_field): camel(concat(payer, "_account_id"));
+  let(beneficiary_account_field): camel(concat(beneficiary, "_account_id"));
+  let(reference_filter_key): "x-hyperscale-reference-filter";
+  fields {
+    amount { type: money<C>; description: concat("Amount instructed to the ", words(beneficiary), " in minor units"); }
+    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
+    settle_by { type: date; description: "Instant the expectation stops waiting and the unmatched amount becomes a break"; }
+    beneficiary_ref { type: text; description: "Beneficiary ID for the payout instruction"; pattern: "^ben_(sandbox|live)_[a-z0-9]{8,64}$"; }
+    [beneficiary_account_field] { type: account<C>; description: concat("The ", words(beneficiary), " account"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter_key]: { column: role; values: [customer_balance]; }; }
+    [payer_account_field] { type: account<C>; description: concat("The ", words(payer), " account the payout leaves"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter_key]: { column: role; values: [customer_balance]; }; }
+  }
+  lifecycle {
+    states created instructed settled;
+    initial created;
+    on instruct: created -> instructed;
+    on settle: instructed -> settled;
+  }
+  parties { beneficiary: beneficiary_account_field; payer: payer_account_field; }
+  required: [amount, beneficiary_account_field, beneficiary_ref, currency, payer_account_field, settle_by];
+  title: sentence(instrument);
+  agent_description: concat("Reach for reconciled payout when a payment to the ", words(beneficiary), " is not finished until the bank confirms the debit. The instruction goes out, the expectation waits for a matching statement line, and anything still unmatched at the settle date becomes a break row instead of disappearing. Pick instant transfer when no bank confirmation is involved.");
+  id_prefix: prefix(instrument);
+  summary: concat("Payout from ", words(payer), " to ", words(beneficiary), " that is not done until the bank agrees");
+  description: "A payout the instrument owns end to end: one instruction, one expectation about the debit it will produce, and one break when the debit never matches";
+  dials: [{ key: settlement_tolerance; kind: reconcile_tolerance; maxMinorUnits: matched_ceiling; summary: "Largest difference between the instructed amount and the settled debit that still counts as matched."; title: "Settlement tolerance"; }];
+  action create { summary: concat("Create a ", words(instrument)); agent_description: concat("Open the payout row with the ", words(payer), " and ", words(beneficiary), " accounts, the amount, the beneficiary reference, and the settle date. No money moves and no instruction goes out yet. Call instruct next."); moves: []; steps: []; }
+  action instruct {
+    agent_description: concat("Send the payout instruction and start the expectation clock. This commits the amount to the ", words(beneficiary), " and the payout is not reversible from here. The bank debit is matched later by settle, which runs on its own at the settle date.");
+    summary: concat("Instruct the payout to the ", words(beneficiary));
+    payout { amount: concat("fields.", amount); beneficiaryField: beneficiary_ref; beneficiaryPartyField: beneficiary_account_field; capture: payoutId; currencyField: currency; sourceAccountField: payer_account_field; speed: standard; }
+    moves: []; steps: [];
+  }
+  action settle {
+    summary: "Match the bank's debit against what the instruction promised";
+    due { field: settle_by; }
+    reconcile {
+      amount: concat("fields.", amount); capture: settlementEvidenceId; counterpartyRef: payoutId;
+      currencyField: currency; direction: debit; evidence: statement_line;
+      exception { amountField: unmatchedAmount; childInstrumentId: concat(instrument, "_break"); maxOpen: 1; reasonField: breakReason; refField: concat(camel(instrument), "Id"); }
+      match { law: tolerance; dial: settlement_tolerance; minorUnits: matched_within; }
+      within { field: settle_by; }
+    }
+    moves: []; steps: [];
+  }
+  instruments {
+    instrument {
+      let(parent_name): instrument;
+      id: concat(parent_name, "_break");
+      id_prefix: concat(prefix(parent_name), "bk");
+      fields {
+        unmatchedAmount { type: money<C>; description: "Difference between the instructed amount and the evidence, in minor units"; }
+        currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
+        breakReason { type: text; description: "Why the expectation went unmatched"; minLength: 1; maxLength: 180; }
+        [parent_name]Id { type: ref<parent_name>; description: "Payout whose expectation broke"; pattern: concat("^", prefix(parent_name), "_(sandbox|live)_[a-z0-9]{8,64}$"); }
+      }
+      lifecycle { states created carried; initial created; on carry: created -> carried; }
+      required: [breakReason, currency, unmatchedAmount, concat(camel(parent_name), "Id")];
+      title: concat(sentence(parent_name), " Break");
+      agent_description: concat("Reach for this child row when a ", words(parent_name), " expectation reached its window with no matching bank debit. The break carries the unmatched amount and the reason so the difference is owned by someone rather than silently dropped.");
+      summary: "Unmatched settlement expectation carried as its own row";
+      description: "One break raised when a payout expectation reached its window with no matching debit; it is carried, never silently dropped";
+      action create { summary: "Raise a break against an instructed payout"; agent_description: "Raise a break against an instructed payout, recording the unmatched amount and why the expectation went unmatched. No money moves. The payout must still be instructed, and only one open break exists per payout."; requires refs { field: concat(camel(parent_name), "Id"); statuses: [instructed]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
+      action carry { summary: "Carry the break to whoever owns it"; agent_description: "Hand the break to whoever owns resolving it. No money moves. The payout must still be instructed. This is the only exit from a raised break, so a break is never closed by dropping it."; requires refs { field: concat(camel(parent_name), "Id"); statuses: [instructed]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
+    }
+  }
+}

package/std/settlements/recurring_collection.hsx

@@ -0,0 +1,27 @@
+module std.settlements.recurring_collection
+
+export instrument recurring_collection(marker: optional<text>) {
+  agent_description: concat("Reach for ", words(instrument), " to track a bounded run of scheduled collections, one call per recorded installment. It carries no amount and no account, and every action only advances its own state. A settlement that debits an account on a schedule is a different shape.");
+  fields {}
+  lifecycle {
+    states active ended;
+    initial active;
+    on collect: active -> active;
+    on end: active -> ended;
+  }
+  action create {
+    agent_description: "Open the collection so installments can be recorded against it. This is the first call and the collection starts active. It moves no money.";
+    summary: "Create a bounded recurring collection";
+    steps: [];
+  }
+  action collect {
+    agent_description: "Record one due installment as collected. The collection must still be active, and it stays active afterwards so the next installment can follow. It moves no money.";
+    summary: "Collect one due installment";
+    steps: [];
+  }
+  action end {
+    agent_description: "Close the collection so no further installment can be recorded. Only an active collection can end, and ended is final. It moves no money.";
+    summary: "End future collections";
+    steps: [];
+  }
+}

package/std/settlements/rotating_pool.hsx

@@ -0,0 +1,252 @@
+module std.settlements.rotating_pool
+
+export instrument rotating_pool<C>(members: optional<list<party>>, contribution: money<C>, count: integer, every: optional<text>, first_due: date, payout_order: optional<list<party>>, default_policy: optional<text>, guarantee_policy: optional<text>, guarantor: optional<party>, exit_policy: optional<text>, memo: optional<text>, membership: optional<block>) {
+  when_not(membership) {
+  let(member_fields): suffix_each(members, "AccountId");
+  let(guarantor_field): concat(camel(guarantor), "AccountId");
+  let(contribution_field): camel(contribution);
+  let(first_due_field): camel(first_due);
+  let(parent_ref_field): concat(camel(instrument), "Id");
+  let(reference_filter): "x-hyperscale-reference-filter";
+  fields {
+    for member in members { [member]AccountId { type: account<C>; description: concat("The ", words(member), " account"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter]: { column: role; values: [customer_balance]; }; } }
+    [guarantor_field] { type: account<C>; description: concat("The ", words(guarantor), " account"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter]: { column: role; values: [customer_balance]; }; }
+    [contribution_field] { type: money<C>; description: "Exact contribution in {C} minor units"; }
+    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
+    [first_due_field] { type: date; description: "Stored first contribution due date"; }
+    one { type: integer; description: "Exact fixed member-row count"; const: 1; }
+  }
+  lifecycle {
+    states forming cancelled;
+    for cycle in count {
+      let(active_state): concat("active_cycle_", cycle);
+      let(ready_state): concat("cycle_", cycle, "_ready");
+      let(states_key): "states";
+      [states_key]: [active_state, ready_state];
+    }
+    states completed;
+    initial forming;
+    on cancel: forming -> cancelled;
+    on activate: forming -> active_cycle_1;
+    for cycle in count {
+      let(active_state): concat("active_cycle_", cycle);
+      let(ready_state): concat("cycle_", cycle, "_ready");
+      on ready_cycle_[cycle]: active_state -> ready_state;
+      let(next_state): if_eq(cycle, count, "completed", concat("active_cycle_", add(cycle, 1)));
+      on advance_cycle_[cycle]: ready_state -> next_state;
+    }
+  }
+  parties { payer: guarantor_field; }
+  required: concat_lists(member_fields, [guarantor_field, "currency", contribution_field, first_due_field, "one"]);
+  title: sentence(instrument);
+  id_prefix: prefix(instrument);
+  agent_description: "Reach for rotating pool when a fixed group pays the same contribution every cycle and one member takes the whole pot each cycle, in a declared order. The roster freezes at creation, one contribution row per member, and the pot rotates until every member has been paid. Scheduled is the one payer, one payee shape on a calendar.";
+  summary: concat(count, "-member rotating pool");
+  description: "Fixed rotating contribution and payout order";
+  action create { agent_description: "Create the pool with its frozen roster, cycle count, contribution amount, and payout order. No money moves. Each member's contribution row is created separately, and the pool cannot activate until every row exists."; summary: "Create the fixed roster before activation"; moves: []; steps: []; }
+  action cancel { agent_description: "Cancel the pool before it activates. Only a forming pool cancels, no money has moved yet, and there is nothing to refund. Once the pool activates this exit is gone."; summary: "Cancel before activation without moving money"; moves: []; steps: []; }
+  action activate {
+    agent_description: "Start cycle one. Refused unless every member on the roster has exactly one contribution row waiting at the first cycle, so a pool can never run a member short. No money moves.";
+    summary: "Activate only after every fixed member row exists once";
+    for member in members { requires aggregate { instrumentId: concat(instrument, "_", member, "_contribution"); over: children; refField: parent_ref_field; statuses: [cycle_1_due]; check: { kind: count_equals_field; field: one; }; } }
+    moves: [];
+    steps: [];
+  }
+  for cycle in count {
+    action ready_cycle_[cycle] {
+      agent_description: concat("Lock cycle ", cycle, " once every member row is funded or covered by the guarantor. Refused while any row is still due or defaulted. No money moves here. Locking the cycle is what lets its payouts run.");
+      summary: concat("Lock cycle ", cycle, " only after every member row is funded or guaranteed");
+      let(funded_state): concat("cycle_", cycle, "_funded");
+      let(guaranteed_state): concat("cycle_", cycle, "_guaranteed");
+      for member in members { requires aggregate { instrumentId: concat(instrument, "_", member, "_contribution"); over: children; refField: parent_ref_field; statuses: [funded_state, guaranteed_state]; check: { kind: all_in; }; } }
+      moves: [];
+      steps: [];
+    }
+    action advance_cycle_[cycle] {
+      let(target_status): if_eq(cycle, count, "completed", concat("cycle_", add(cycle, 1), "_due"));
+      agent_description: concat("Close cycle ", cycle, " once every member row has paid into that cycle pot, moving the pool to the next cycle or to completed on the last one. Refused while any row is unpaid. No money moves here. The money moved on the member rows.");
+      summary: if_eq(cycle, count, "Complete after the final shared pot pays", concat("Advance after every cycle ", cycle, " contribution pays"));
+      for member in members { requires aggregate { instrumentId: concat(instrument, "_", member, "_contribution"); over: children; refField: parent_ref_field; statuses: [target_status]; check: { kind: all_in; }; } }
+      moves: [];
+      steps: [];
+    }
+  }
+  instruments {
+    for member in members {
+      instrument {
+        let(parent_name): instrument;
+        let(child_id): concat(parent_name, "_", member, "_contribution");
+        id: child_id;
+        generatedPrefix: true;
+        title: concat(sentence(parent_name), " ", sentence(member), " Contribution");
+        agent_description: concat("One seat in the pool. The ", words(member), " pays the same contribution every cycle and takes the whole pot on their turn. Every contribution, default, guarantee, and payout for that member happens on this row, never on the pool itself.");
+        summary: concat(words(member), " contribution row");
+        description: concat("Fixed contribution row for ", words(member));
+        fields {
+          for roster_member in payout_order { [roster_member]AccountId { type: account<C>; description: concat("The ", words(roster_member), " account"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter]: { column: role; values: [customer_balance]; }; } }
+          [guarantor_field] { type: account<C>; description: concat("The ", words(guarantor), " account"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter]: { column: role; values: [customer_balance]; }; }
+          [contribution_field] { type: money<C>; description: "Exact contribution amount shared by every cycle"; }
+          currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
+          [first_due_field] { type: date; description: "First due anchor derived from the pool"; }
+          [parent_ref_field] { type: ref<parent_name>; description: concat("The exact ", parent_name); pattern: concat("^", prefix(parent_name), "_(sandbox|live)_[a-z0-9]{8,64}$"); }
+        }
+        lifecycle {
+          for cycle in count {
+            let(states_key): "states";
+            let(due_state): concat("cycle_", cycle, "_due");
+            let(funded_state): concat("cycle_", cycle, "_funded");
+            let(defaulted_state): concat("cycle_", cycle, "_defaulted");
+            let(guaranteed_state): concat("cycle_", cycle, "_guaranteed");
+            [states_key]: [due_state, funded_state, defaulted_state, guaranteed_state];
+          }
+          states final_paid completed;
+          initial cycle_1_due;
+          for cycle in count {
+            let(due_state): concat("cycle_", cycle, "_due");
+            let(funded_state): concat("cycle_", cycle, "_funded");
+            let(defaulted_state): concat("cycle_", cycle, "_defaulted");
+            let(guaranteed_state): concat("cycle_", cycle, "_guaranteed");
+            on contribute_cycle_[cycle]: due_state -> funded_state;
+            on mark_default_cycle_[cycle]: due_state -> defaulted_state;
+            on guarantee_cycle_[cycle]: defaulted_state -> guaranteed_state;
+            let(next_state): if_eq(cycle, count, "final_paid", concat("cycle_", add(cycle, 1), "_due"));
+            on pay_cycle_[cycle]: funded_state -> next_state;
+            on pay_guaranteed_cycle_[cycle]: guaranteed_state -> next_state;
+          }
+          on close: final_paid -> completed;
+        }
+        parties { beneficiary: concat(camel(member), "AccountId"); payer: guarantor_field; }
+        action create {
+          agent_description: concat("Create the contribution row for the ", words(member), " and provision its escrow account. The pool must still be forming, and every member needs exactly one row before the pool can activate. No money moves.");
+          summary: concat("Create the fixed contribution row for ", words(member));
+          requires refs { field: parent_ref_field; statuses: [forming]; unique: true; bind: { [contribution_field]: concat("fields.", contribution_field); currency: "fields.currency"; [first_due_field]: concat("fields.", first_due_field); [guarantor_field]: concat("fields.", guarantor_field); for roster_member in members { let(roster_field): concat(camel(roster_member), "AccountId"); [roster_field]: concat("fields.", roster_field); } }; }
+          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 cycle in count {
+          let(active_state): concat("active_cycle_", cycle);
+          let(ready_state): concat("cycle_", cycle, "_ready");
+          let(due_offset): scale_duration(every, sub(cycle, 1));
+          let(contribute_name): concat("contribute_cycle_", cycle);
+          let(guarantee_name): concat("guarantee_cycle_", cycle);
+          let(pay_name): concat("pay_cycle_", cycle);
+          let(pay_guaranteed_name): concat("pay_guaranteed_cycle_", cycle);
+          let(contribute_capture): concat("contributeCycle", cycle, "ContributionTransferId");
+          let(guarantee_capture): concat("guaranteeCycle", cycle, "GuaranteeTransferId");
+          let(pay_capture): concat("payCycle", cycle, "PayoutTransferId");
+          let(pay_guaranteed_capture): concat("payGuaranteedCycle", cycle, "PayoutTransferId");
+          let(payout_member): at(payout_order, cycle);
+          let(payout_field): concat(camel(payout_member), "AccountId");
+          action contribute_cycle_[cycle] {
+            summary: concat("Fund ", words(member), "'s cycle ", cycle, " contribution");
+            let(first): if_eq(cycle, 1, true, false);
+            when(first) { due: { field: first_due_field; }; }
+            when_not(first) { due: { field: first_due_field; offset: due_offset; }; }
+            requires refs { field: parent_ref_field; statuses: [active_state]; }
+            moves: [{ key: "contribution"; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", contribution_field); }; currency: { from: instance; path: "fields.currency"; }; destinationAccountId: { from: instance; path: "refs.escrowAccountId"; }; "metadata.instrumentId": { from: const; value: child_id; }; "metadata.instrumentInstanceId": { from: instance; path: instrumentInstanceId; }; "metadata.phase": { from: const; value: contribute_name; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", camel(member), "AccountId"); }; }; capture: { [contribute_capture]: transferId; }; }];
+            steps: [];
+          }
+          action mark_default_cycle_[cycle] {
+            summary: concat("Mark the stored cycle ", cycle, " due condition");
+            let(first): if_eq(cycle, 1, true, false);
+            when(first) { due: { field: first_due_field; }; }
+            when_not(first) { due: { field: first_due_field; offset: due_offset; }; }
+            requires refs { field: parent_ref_field; statuses: [active_state]; }
+            moves: [];
+            steps: [];
+          }
+          action guarantee_cycle_[cycle] {
+            agent_description: concat("Have the guarantor fund cycle ", cycle, " for this member after the row defaulted. The row must be marked defaulted for that cycle. This moves the guarantor's money into the row escrow so the pot still pays in full.");
+            summary: concat("Fund the defaulted cycle ", cycle, " amount before payout");
+            requires refs { field: parent_ref_field; statuses: [active_state]; }
+            moves: [{ key: guarantee; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", contribution_field); }; currency: { from: instance; path: "fields.currency"; }; destinationAccountId: { from: instance; path: "refs.escrowAccountId"; }; "metadata.instrumentId": { from: const; value: child_id; }; "metadata.instrumentInstanceId": { from: instance; path: instrumentInstanceId; }; "metadata.phase": { from: const; value: guarantee_name; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", guarantor_field); }; }; capture: { [guarantee_capture]: transferId; }; }];
+            steps: [];
+          }
+          action pay_cycle_[cycle] {
+            agent_description: concat("Pay this row's funded cycle ", cycle, " contribution out of escrow to whoever holds the pot that cycle. The cycle must be locked first and the row must be funded rather than guaranteed. This moves money and does not reverse.");
+            summary: concat("Pay this member's stored contribution into cycle ", cycle, "'s shared pot recipient");
+            requires refs { field: parent_ref_field; statuses: [ready_state]; }
+            moves: [{ key: payout; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", contribution_field); }; currency: { from: instance; path: "fields.currency"; }; destinationAccountId: { from: instance; path: concat("fields.", payout_field); }; "metadata.instrumentId": { from: const; value: child_id; }; "metadata.instrumentInstanceId": { from: instance; path: instrumentInstanceId; }; "metadata.phase": { from: const; value: pay_name; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.escrowAccountId"; }; }; capture: { [pay_capture]: transferId; }; }];
+            steps: [];
+          }
+          action pay_guaranteed_cycle_[cycle] {
+            agent_description: concat("Pay this row's guarantor-funded cycle ", cycle, " contribution out of escrow to whoever holds the pot that cycle. The cycle must be locked first and the row must be guaranteed rather than funded. This moves money and does not reverse.");
+            summary: concat("Pay the funded default into cycle ", cycle, "'s stored recipient");
+            requires refs { field: parent_ref_field; statuses: [ready_state]; }
+            moves: [{ key: payout; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", contribution_field); }; currency: { from: instance; path: "fields.currency"; }; destinationAccountId: { from: instance; path: concat("fields.", payout_field); }; "metadata.instrumentId": { from: const; value: child_id; }; "metadata.instrumentInstanceId": { from: instance; path: instrumentInstanceId; }; "metadata.phase": { from: const; value: pay_guaranteed_name; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: "refs.escrowAccountId"; }; }; capture: { [pay_guaranteed_capture]: transferId; }; }];
+            steps: [];
+          }
+        }
+        action close { agent_description: "Retire this member row after its final payout. Refused while the row escrow account still holds anything, so a row can never close over stranded money. No money moves."; summary: "Complete after the final payout drains this member custody"; requires drained: { path: "refs.escrowAccountId"; }; moves: []; steps: []; }
+      }
+    }
+  }
+  }
+
+  when(membership) {
+    let(membership_instrument): get(membership, "instrument");
+    let(membership_ref_field): get(membership, "ref_field");
+    let(joined_status): get(membership, "joined_status");
+    let(active_status): get(membership, "active_status");
+    let(paid_status): get(membership, "paid_status");
+    let(custody_ref): get(membership, "custody_ref");
+    let(instrument_id_prefix): get(membership, "id_prefix");
+    let(active_parked): get(membership, "active_parked");
+    let(min_members): get(membership, "min_members");
+    let(max_members): get(membership, "max_members");
+    let(contribution_description): get(membership, "contribution_description");
+    let(currency_description): get(membership, "currency_description");
+    let(create_examples): get(membership, "create_examples");
+    let(activate_examples): get(membership, "activate_examples");
+    let(disband_examples): get(membership, "disband_examples");
+    let(close_examples): get(membership, "close_examples");
+    let(contribution_field): camel(contribution);
+    let(count_field): camel(count);
+    let(first_due_field): camel(first_due);
+
+    fields {
+      [contribution_field] { type: money<C>; description: contribution_description; }
+      currency { type: text; description: currency_description; maxLength: 3; minLength: 3; pattern: "^[A-Z]{3}$"; }
+      [count_field] { type: integer; maximum: max_members; minimum: min_members; }
+      when(memo) { [memo] { type: text; optional: true; maxLength: 180; minLength: 1; } }
+      [first_due_field] { type: date; }
+    }
+    lifecycle {
+      states forming active completed disbanded;
+      initial forming;
+      on activate: forming -> active;
+      on close: active -> completed;
+      on disband: forming -> disbanded;
+    }
+    required: [count_field, contribution_field, currency, first_due_field];
+    aggregate_invariants { childInstrumentId: membership_instrument; childRefField: membership_ref_field; childStatuses: [joined_status, active_status, paid_status]; count: true; parentField: count_field; }
+    caller_parked_states { active: active_parked; }
+    agent_description: concat("Reach for ", words(instrument), " when a fixed group pays the same contribution every cycle and one member takes the whole pot each cycle, and the product publishes its own membership rows. This shape owns the pot account and the seat count. Every contribution and payout happens on the membership row that references it, never here.");
+    id_prefix: instrument_id_prefix;
+    action create {
+      public: none;
+      agent_description: concat("Open the ", words(instrument), " and provision the pot account every contribution lands in. No money moves. The roster is still empty, so the pool stays forming until one membership row exists per seat.");
+      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; }; }];
+    }
+    action activate {
+      public: none;
+      due { field: first_due_field; }
+      examples: activate_examples;
+      requires aggregate { instrumentId: membership_instrument; over: children; refField: membership_ref_field; statuses: [joined_status]; check: { kind: count_equals_field; field: count_field; }; }
+      moves: [];
+      steps: [];
+    }
+    action disband { public: none; agent_description: concat("Close a ", words(instrument), " that never filled its roster. Only a forming pool disbands, no money has moved, and there is nothing to refund. Once the pool activates this exit is gone."); examples: disband_examples; moves: []; steps: []; }
+    action close {
+      public: none;
+      agent_description: concat("Retire the ", words(instrument), " after every membership row has been paid. Refused while any row is unpaid or while the pot account still holds anything, so a pool can never close over stranded money. No money moves.");
+      examples: close_examples;
+      requires aggregate { instrumentId: membership_instrument; over: children; refField: membership_ref_field; statuses: [paid_status]; check: { kind: all_in; }; }
+      requires drained { path: concat("refs.", custody_ref); }
+      moves: [];
+      steps: [];
+    }
+  }
+}