@hyperscale0/hsx 2.4.0 → 3.0.0

package/std/money_flows/threshold_pool.hsx

@@ -1,307 +0,0 @@
-module std.money_flows.threshold_pool
-
-// All-or-nothing capital accumulation pool collecting commitments toward a target amount before a close deadline.
-//
-// ### Purpose
-// `threshold_pool` powers all-or-nothing crowdfunding, capital calls, collective purchasing, and consortium rounds.
-// Multiple contributors pledge commitments toward a monetary `target`. Commitments sit in escrow until the pool
-// reaches the target before `close_by` (activating and settling funds to the beneficiary), or fails (triggering full refunds).
-//
-// ### Selection guidance
-// - vs `rotating_pool`: `threshold_pool` is all-or-nothing fundraising where many contributors fund a single beneficiary.
-//   `rotating_pool` is a peer savings circle where members contribute identically in each cycle and rotate who receives the pot.
-// - vs `weighted_distribution`: `threshold_pool` pools funds inward from many contributors to one beneficiary.
-//   `weighted_distribution` pays funds outward from one source pool to many weighted recipients.
-//
-// ### Parameters
-// - `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.
-// - `max_contributors`: Optional maximum count of admitted contributors.
-// - `close_by`: Stored date deadline by which the target must be met.
-// - `close_policy`: Policy determining pool close behavior (`threshold`).
-// - `overfund_policy`: Policy on commitments exceeding the target (`reject`).
-// - `cancel_policy`: Contributor withdrawal policy before close (`before_close`).
-// - `fail_policy`: Refund policy if the pool fails to hit target (`whole_commitment_refund`).
-// - `beneficiary_account`: Optional direct account reference for the beneficiary.
-// - `memo`: Optional memo text stored on the pool.
-// - `contribution_instrument`: Optional custom contribution child instrument block.
-// - `wording`: Optional custom UI wording block.
-//
-// ### Decision ports
-// None. Lifecycle transitions (`activate`, `fail`, `close`) are driven by target threshold evaluation and the `close_by` date.
-//
-// ### Example
-// ```hsx
-// program capital_pool_example "Capital pool example"
-// import { threshold_pool } from "std/money_flows"
-// party contributor: person
-// party company: business
-// settlement round = threshold_pool {
-//   contributor: contributor
-//   beneficiary: company
-//   target: targetAmount: money(SAR)
-//   commitment: commitmentAmount: money(SAR)
-//   max_contributors: 100
-//   close_by: closeBy
-//   close_policy: threshold
-//   overfund_policy: reject
-//   cancel_policy: before_close
-//   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>,
-  target: money<C>,
-  commitment: money<C>,
-  max_contributors: optional<integer>,
-  close_by: date,
-  close_policy: optional<text>,
-  overfund_policy: optional<text>,
-  cancel_policy: optional<text>,
-  fail_policy: optional<text>,
-  beneficiary_account: optional<account<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");
-    when(wording_unknown_keys) {
-      unsupported {
-        code: HSX1407;
-        message: "threshold_pool wording contains an unknown key";
-        fix: "use only the six declared threshold_pool wording keys";
-      }
-    }
-  }
-  agent_description: "Reach for threshold pool when many contributors commit toward one target and nothing is collected unless the pool reaches it by the close date. Commitments sit in escrow until the pool activates or fails. Pick weighted distribution to pay a pool out and instant transfer for a single payment.";
-  when_not(contribution_instrument) {
-  fields {
-    [beneficiary]AccountId { type: account<C>; description: concat("The ", words(beneficiary), " account"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-    close_by { type: date; description: "Stored close anchor"; }
-    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-    maxContributors { type: integer; description: concat("Exactly ", max_contributors, " admitted contributors"); const: max_contributors; }
-    target { type: money<C>; description: "Funding target in {C} minor units"; }
-  }
-  lifecycle {
-    states open active failed settled;
-    initial open;
-    on activate: open -> active;
-    on fail: open -> failed;
-    on close: active -> settled;
-  }
-  parties { beneficiary: concat(camel(beneficiary), "AccountId"); }
-  required: [concat(camel(beneficiary), "AccountId"), currency, target, close_by, maxContributors];
-  title: sentence(instrument);
-  id_prefix: prefix(instrument);
-  let(pool_summary): get(wording, "pool_summary");
-  when_not(pool_summary) { summary: concat("Threshold contribution pool for ", words(beneficiary)); }
-  when(pool_summary) { summary: pool_summary; }
-  let(pool_description): get(wording, "pool_description");
-  when_not(pool_description) { description: "All-or-nothing aggregate contribution threshold"; }
-  when(pool_description) { description: pool_description; }
-  aggregate_invariants { childField: amount; childInstrumentId: concat(instrument, "_commitment"); childRefField: concat(camel(instrument), "Id"); childStatuses: [committed]; parentField: target; }
-  aggregate_invariants { childInstrumentId: concat(instrument, "_commitment"); childRefField: concat(camel(instrument), "Id"); childStatuses: [committed]; count: true; parentField: maxContributors; }
-  action create {
-    agent_description: "Open the pool before any commitment exists. The caller supplies the target, the currency, the beneficiary account, the close anchor, and the pinned contributor count. No money moves and the pool opens for commitments.";
-    let(create_summary): get(wording, "create_summary");
-    when_not(create_summary) { summary: "Open the contribution pool"; }
-    when(create_summary) { summary: create_summary; }
-    moves: [];
-    steps: [];
-  }
-  action activate {
-    summary: "Activate when commitments meet the target";
-    due { field: close_by; }
-    requires aggregate { instrumentId: concat(instrument, "_commitment"); over: children; refField: concat(camel(instrument), "Id"); statuses: [committed]; check: { kind: sum_at_least; amountField: amount; targetField: target; }; }
-    moves: [];
-    steps: [];
-  }
-  action fail {
-    summary: "Fail when commitments remain below target";
-    due { field: close_by; }
-    requires aggregate { instrumentId: concat(instrument, "_commitment"); over: children; refField: concat(camel(instrument), "Id"); statuses: [committed]; check: { kind: sum_below; amountField: amount; targetField: target; }; }
-    moves: [];
-    steps: [];
-  }
-  action close {
-    agent_description: "Settle the pool once every admitted commitment is collected or was cancelled before activation. The pool must be active. No money moves here, collect already paid the beneficiary.";
-    summary: "Settle after every admitted row is collected or was cancelled before activation";
-    requires aggregate { instrumentId: concat(instrument, "_commitment"); over: children; refField: concat(camel(instrument), "Id"); statuses: [cancelled, collected]; check: { kind: all_in; }; }
-    moves: [];
-    steps: [];
-  }
-  instruments {
-    instrument {
-      let(parent_name): instrument;
-      id: concat(parent_name, "_commitment");
-      generatedPrefix: true;
-      fields {
-        amount { type: money<C>; description: "One whole commitment amount"; }
-        [beneficiary]AccountId { type: account<C>; description: concat("The ", words(beneficiary), " account"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-        [parent_name]Id { type: ref<parent_name>; description: concat("The exact ", parent_name); pattern: concat("^", prefix(parent_name), "_(sandbox|live)_[a-z0-9]{8,64}$"); }
-        [contributor]AccountId { type: account<C>; description: concat("The ", words(contributor), " account"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-        currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-      }
-      lifecycle {
-        states committed cancelled collected refunded;
-        initial committed;
-        on cancel: committed -> cancelled;
-        on collect: committed -> collected;
-        on refund: committed -> refunded;
-      }
-      parties { beneficiary: concat(camel(beneficiary), "AccountId"); payer: concat(camel(contributor), "AccountId"); }
-      required: [concat(camel(beneficiary), "AccountId"), concat(camel(contributor), "AccountId"), amount, currency, concat(camel(parent_name), "Id")];
-      title: concat(sentence(parent_name), " Commitment");
-      agent_description: concat("Reach for this child row to record one whole commitment into a ", words(parent_name), ". Each contributor commits once, the money sits in the product escrow, and whether it is collected or refunded depends on the pool reaching its target.");
-      summary: concat("Whole commitment to ", parent_name);
-      description: concat("One whole commitment linked to ", parent_name);
-      action create {
-        agent_description: "Commit one whole amount into the pool escrow. The pool must still be open, the currency and beneficiary account must match it, and the committed total plus this amount must stay within the target. The money leaves the contributor now.";
-        let(commitment_create_summary): get(wording, "commitment_create_summary");
-        when_not(commitment_create_summary) { summary: "Store one whole commitment without exceeding the pool target"; }
-        when(commitment_create_summary) { summary: commitment_create_summary; }
-        requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; bind: { [beneficiary]AccountId: concat("fields.", camel(beneficiary), "AccountId"); currency: "fields.currency"; }; }
-        requires exposure { amountField: amount; anchorField: concat(camel(parent_name), "Id"); capField: target; capOnAnchor: true; childInstrumentId: concat(parent_name, "_commitment"); statuses: [committed]; }
-        moves: [{ amount: amount; from: payer; to: refs.escrowAccountId; key: commit; }];
-        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 cancel {
-        agent_description: "Pull one commitment back out of escrow to the contributor. The pool must still be open, so this is unavailable once the pool activates or fails. The money returns and the commitment is closed.";
-        let(commitment_cancel_summary): get(wording, "commitment_cancel_summary");
-        when_not(commitment_cancel_summary) { summary: "Cancel one commitment while the pool is open"; }
-        when(commitment_cancel_summary) { summary: commitment_cancel_summary; }
-        requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.[beneficiary]AccountId": concat("fields.", camel(beneficiary), "AccountId"); "fields.currency": "fields.currency"; }; }
-        moves: [{ amount: amount; from: refs.escrowAccountId; to: payer; key: cancel; }];
-        steps: [];
-      }
-      action collect {
-        agent_description: "Release one commitment out of escrow to the beneficiary. The pool must be active, which happens only once commitments meet the target. The money moves for good.";
-        summary: "Collect one successful commitment whole";
-        requires refs { field: concat(camel(parent_name), "Id"); statuses: [active]; match: { "fields.[beneficiary]AccountId": concat("fields.", camel(beneficiary), "AccountId"); "fields.currency": "fields.currency"; }; }
-        moves: [{ amount: amount; from: refs.escrowAccountId; to: beneficiary; key: collect; }];
-        steps: [];
-      }
-      action refund {
-        agent_description: "Return one commitment out of escrow to the contributor after the pool failed to reach its target. The pool must be in failed. The money returns and the commitment is closed.";
-        let(commitment_refund_summary): get(wording, "commitment_refund_summary");
-        when_not(commitment_refund_summary) { summary: "Refund one failed-pool commitment whole"; }
-        when(commitment_refund_summary) { summary: commitment_refund_summary; }
-        requires refs { field: concat(camel(parent_name), "Id"); statuses: [failed]; match: { "fields.[beneficiary]AccountId": concat("fields.", camel(beneficiary), "AccountId"); "fields.currency": "fields.currency"; }; }
-        moves: [{ amount: amount; from: refs.escrowAccountId; to: payer; key: refund; }];
-        steps: [];
-      }
-    }
-  }
-  }
-
-  when(contribution_instrument) {
-    let(contribution_id): get(contribution_instrument, "instrument");
-    let(contribution_ref_field): get(contribution_instrument, "ref_field");
-    let(contribution_amount_field): get(contribution_instrument, "amount_field");
-    let(committed_status): get(contribution_instrument, "committed_status");
-    let(collected_status): get(contribution_instrument, "collected_status");
-    let(instrument_id_prefix): get(contribution_instrument, "id_prefix");
-    let(active_parked): get(contribution_instrument, "active_parked");
-    let(custody_ref): get(contribution_instrument, "custody_ref");
-    let(beneficiary_account_description): get(contribution_instrument, "beneficiary_account_description");
-    let(target_description): get(contribution_instrument, "target_description");
-    let(currency_description): get(contribution_instrument, "currency_description");
-    let(create_examples): get(contribution_instrument, "create_examples");
-    let(activate_examples): get(contribution_instrument, "activate_examples");
-    let(fail_examples): get(contribution_instrument, "fail_examples");
-    let(close_examples): get(contribution_instrument, "close_examples");
-    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]; }; }
-      [close_field] { type: date; }
-      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;
-      initial open;
-      on activate: open -> active;
-      on close: active -> settled;
-      on fail: open -> failed;
-    }
-    parties { beneficiary: beneficiary_account_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.";
-      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; }; }];
-    }
-    action activate {
-      public: none;
-      due { field: close_field; }
-      examples: activate_examples;
-      requires aggregate { instrumentId: contribution_id; over: children; refField: contribution_ref_field; statuses: [committed_status]; check: { kind: sum_at_least; amountField: contribution_amount_field; targetField: target_field; }; }
-      moves: [];
-      steps: [];
-    }
-    action fail {
-      public: none;
-      due { field: close_field; }
-      examples: fail_examples;
-      requires aggregate { instrumentId: contribution_id; over: children; refField: contribution_ref_field; statuses: [committed_status]; check: { kind: sum_below; amountField: contribution_amount_field; targetField: target_field; }; }
-      moves: [];
-      steps: [];
-    }
-    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.";
-      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: [];
-    }
-  }
-}

package/std/money_flows/weighted_distribution.hsx

@@ -1,237 +0,0 @@
-module std.money_flows.weighted_distribution
-
-// Frozen largest-remainder distribution splitting one pool across dynamic recipients by recorded weights.
-//
-// ### Purpose
-// `weighted_distribution` distributes dividend pools, creator royalties, liquidation proceeds, and investment returns.
-// Child entitlement rows are recorded for each recipient with their respective weight. Once all recipients are recorded,
-// an evidence-backed snapshot freezes the entitlement set. Each recipient is then paid their exact largest-remainder
-// share such that all payouts sum exactly to `amount` without rounding leaks.
-//
-// ### Selection guidance
-// - vs `pooled_split`: `weighted_distribution` handles dynamic recipient rosters recorded as child rows and frozen
-//   via snapshot. `pooled_split` hardcodes a fixed set of recipients and static percentages at definition time.
-// - vs `settlement_batch`: `weighted_distribution` splits one funding pool out to many recipients.
-//   `settlement_batch` aggregates many inbound charges and adjustments into a single net payout.
-//
-// ### Parameters
-// - `source`: The funding party providing the distribution pool.
-// - `recipient`: The party representing entitled recipients.
-// - `amount`: Total distribution pool in minor units of currency `C`.
-// - `record_at`: Date when entitlement eligibility is established.
-// - `weight`: Binding name for individual recipient weight amounts.
-// - `max_recipients`: Exact number of entitlement rows required before snapshotting.
-// - `snapshot`: Port freezing the entitlement set against stored decision evidence.
-// - `rounding_policy`: Mathematical rounding policy (`largest_remainder`).
-// - `withholding_policy`: Tax or withholding policy (`refuse`).
-// - `correction_policy`: Error correction policy (`new_distribution`).
-// - `flat`: Optional flat distribution configuration block.
-// - `id_prefix_override`: Optional custom prefix for generated instrument IDs.
-//
-// ### Decision ports
-// - `snapshot`: Port freezing the entitlement set with an evidence reference, preventing further entries.
-//
-// ### Example
-// ```hsx
-// program weighted_distribution_example "Weighted distribution example"
-// import { weighted_distribution } from "std/money_flows"
-// party distribution_source: business
-// party recipient: business
-// settlement proceeds = weighted_distribution {
-//   source: distribution_source
-//   recipient: recipient
-//   amount: distributableAmount: money(SAR)
-//   weight: entitlementWeight: money(SAR)
-//   max_recipients: 12
-//   record_at: recordAt
-//   snapshot: port snapshot_entitlements
-//   rounding_policy: largest_remainder
-//   withholding_policy: refuse
-//   correction_policy: new_distribution
-// }
-// port snapshot_entitlements {
-//   allowed: [distribution_source]
-//   shape: { evidenceReference: text }
-// }
-// ```
-// ### Receipt-backed distributions
-// receipts selects repeated distributions from immutable allocation receipts.
-// It names round, receipt, path, mode (cash or loss), fee_bps and vat_bps.
-// The funding snapshot owns ticket weights and original wallet destinations.
-// Cash floors each ratio after fee and fee VAT; a named account receives residual.
-// Loss assigns principal by largest remainder without cash, fee or VAT.
-// Each receipt is consumed once; a new receipt may fund a new distribution record.
-// This mode does not use caller-entered weights or a once-only settled principal pool.
-//
-export instrument weighted_distribution<C>(
-  source: optional<party>,
-  recipient: optional<party>,
-  amount: optional<money<C>>,
-  record_at: optional<date>,
-  weight: optional<money<C>>,
-  max_recipients: optional<integer>,
-  snapshot: optional<condition>,
-  rounding_policy: optional<text>,
-  withholding_policy: optional<text>,
-  correction_policy: optional<text>,
-  flat: optional<block>,
-  receipts: optional<block>,
-  id_prefix_override: optional<text>,
-) {
-  when_not(receipts) {
-  when_not(flat) {
-  fields {
-    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-    amount { type: money<C>; description: "Distribution pool in {C} minor units"; }
-    [source]AccountId { type: account<C>; description: concat("The ", words(source), " account"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-    maxRecipients { type: integer; description: concat("Exactly ", max_recipients, " frozen entitlement rows"); const: max_recipients; }
-    record_at { type: date; description: "Stored record date"; }
-  }
-  lifecycle { states open snapshotted; initial open; on [snapshot]: open -> snapshotted; }
-  parties { payer: concat(camel(source), "AccountId"); }
-  required: [concat(camel(source), "AccountId"), currency, amount, record_at, maxRecipients];
-  title: sentence(instrument);
-  id_prefix: prefix(instrument);
-  agent_description: "Reach for weighted distribution when one pool splits across many recipients by declared weights. Record one entitlement per recipient, freeze the set with the snapshot port, then each entitlement pays its own largest-remainder share, so the shares add back to the pool exactly. Settlement batch goes the other way, many charges into one payout.";
-  summary: "Frozen largest-remainder distribution";
-  description: "Evidence-frozen weighted distribution";
-  aggregate_invariants { childInstrumentId: concat(instrument, "_entitlement"); childRefField: concat(camel(instrument), "Id"); childStatuses: [recorded, paid]; count: true; parentField: maxRecipients; }
-  action create { agent_description: "Open a distribution and start recording entitlements. No money moves. The pool amount, the record date, and the exact recipient count are fixed here."; summary: "Open entitlement recording"; moves: []; steps: []; }
-  action [snapshot] {
-    agent_description: "Freeze the entitlement set against a stated evidence reference. The distribution must still be open and its recorded entitlements must match the declared recipient count. Nothing can be recorded afterwards and there is no unfreeze. No money moves.";
-    summary: "Freeze the entitlement set from stored evidence";
-    port { allowedParties: [payer]; }
-    input { type: object; properties: { evidenceReference: { type: string; description: "Required decision reference retained in the operation receipt"; minLength: 1; maxLength: 180; }; }; required: [evidenceReference]; additionalProperties: false; }
-    capture_input { snapshotEvidenceReference: evidenceReference; }
-    moves: [];
-    steps: [];
-  }
-  instruments {
-    instrument {
-      let(parent_name): instrument;
-      id: concat(parent_name, "_entitlement");
-      generatedPrefix: true;
-      fields {
-        currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-        [source]AccountId { type: account<C>; description: concat("The ", words(source), " account"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-        [weight] { type: money<C>; description: "Stored non-negative entitlement weight"; }
-        [parent_name]Id { type: ref<parent_name>; description: concat("The exact ", parent_name); pattern: concat("^", prefix(parent_name), "_(sandbox|live)_[a-z0-9]{8,64}$"); }
-        [recipient]AccountId { type: account<C>; description: concat("The ", words(recipient), " account"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-      }
-      lifecycle { states recorded paid; initial recorded; on payout: recorded -> paid; }
-      parties { beneficiary: concat(camel(recipient), "AccountId"); payer: concat(camel(source), "AccountId"); }
-      required: [concat(camel(recipient), "AccountId"), concat(camel(source), "AccountId"), currency, concat(camel(parent_name), "Id"), weight];
-      title: concat(sentence(parent_name), " Entitlement");
-      agent_description: concat("One recipient weighted claim on ", parent_name, ". Record one per recipient before the snapshot. Its share is derived from its weight against the frozen set, never supplied by the caller.");
-      summary: concat("Frozen entitlement in ", parent_name);
-      description: concat("One frozen weighted entitlement in ", parent_name);
-      action create {
-        agent_description: "Record one recipient weight against an open distribution. The parent distribution must still be open, and the currency and source account are copied from it. No money moves. Do not supply a share. It is derived later from the frozen set.";
-        summary: "Record one entitlement before snapshot";
-        requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; bind: { currency: "fields.currency"; [source]AccountId: concat("fields.", camel(source), "AccountId"); }; }
-        moves: [];
-        steps: [];
-      }
-      action payout {
-        agent_description: "Pay this recipient their largest-remainder share of the pool. The parent distribution must already be snapshotted. The amount is computed from the recorded weights, not supplied by the caller, and a zero share moves nothing. This moves money and does not reverse.";
-        summary: "Pay the deterministic largest-remainder share once";
-        requires refs { field: concat(camel(parent_name), "Id"); statuses: [snapshotted]; match: { "fields.currency": "fields.currency"; "fields.[source]AccountId": concat("fields.", camel(source), "AccountId"); }; }
-        computes distribute { amountRef: payoutShare; onZero: skip_steps; pool: { from: parent; path: concat("fields.", amount); }; refField: concat(camel(parent_name), "Id"); statuses: [recorded, paid]; weightField: weight; }
-        moves: [{ amount: refs.payoutShare; from: payer; to: beneficiary; key: payout; }];
-        steps: [];
-      }
-    }
-  }
-  }
-  when(flat) {
-    let(pool): get(flat, "pool");
-    let(pool_ref): get(pool, "field");
-    let(pool_ref_field): camel(pool_ref);
-    let(pool_instrument): get(pool, "instrument");
-    let(pool_create_statuses): get(pool, "create_statuses");
-    let(pool_payout_statuses): get(pool, "payout_statuses");
-    let(pool_bind): get(pool, "bind");
-    let(pool_match): get(pool, "match");
-    let(pool_amount_path): get(pool, "amount_path");
-    let(weight_source): get(flat, "weight_source");
-    let(weight_ref): get(weight_source, "field");
-    let(weight_ref_field): camel(weight_ref);
-    let(weight_statuses): get(weight_source, "statuses");
-    let(weight_bind): get(weight_source, "bind");
-    let(weight_match): get(weight_source, "match");
-    let(unique_weight_source): get(weight_source, "unique");
-    let(group): get(flat, "group");
-    let(group_ref): get(group, "field");
-    let(source_account_field): camel(concat(source, "_account_id"));
-    let(recipient_account_field): camel(concat(recipient, "_account_id"));
-    fields {
-      [amount] { type: money<C>; description: get(flat, "amount_description"); }
-      [record_at] { type: date; }
-      [pool_ref] { type: pool_ref; description: get(pool, "description"); pattern: get(pool, "pattern"); }
-      currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-      [weight_ref] { type: weight_ref; description: get(weight_source, "description"); pattern: get(weight_source, "pattern"); }
-      [group_ref] { type: group_ref; description: get(group, "description"); pattern: get(group, "pattern"); }
-      [recipient]AccountId { type: account<C>; description: get(flat, "recipient_account_description"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-      [source]AccountId { type: account<C>; description: get(flat, "source_account_description"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-    }
-    lifecycle { states claimed paid; initial claimed; on payout: claimed -> paid; }
-    parties { beneficiary: recipient_account_field; }
-    required: get(flat, "required");
-    title: sentence(instrument);
-    id_prefix: if_eq(id_prefix_override, false, prefix(instrument), id_prefix_override);
-    agent_description: concat("One weighted claim on a distribution pool that another instrument owns. Record one claim per recipient before the pool settles. Its share is derived from its weight against the settled pool, never supplied by the caller, and the shares add back to the pool exactly.");
-    summary: "Flat largest-remainder distribution claim";
-    description: "One weighted claim on a settled distribution pool";
-    action create {
-      public: none;
-      agent_description: concat("Record one recipient weight against a pool that is still open. Both the pool and the weight source must be in an accepting state, and the same weight source cannot be claimed twice. No money moves. Do not supply a share. It is derived at payout from the settled pool.");
-      summary: "Open one weighted distribution claim";
-      requires_refs: [
-        { field: pool_ref_field; statuses: pool_create_statuses; bind: pool_bind; match: pool_match; },
-        { field: weight_ref_field; statuses: weight_statuses; bind: weight_bind; match: weight_match; unique: unique_weight_source; }
-      ];
-      moves: [];
-      steps: [];
-    }
-    action payout {
-      public: none;
-      summary: "Pay one largest-remainder share from the settled pool";
-      due { field: record_at; whenParentStatus: { instrumentId: pool_instrument; refField: pool_ref_field; statuses: pool_payout_statuses; }; }
-      requires refs { field: pool_ref_field; statuses: pool_payout_statuses; }
-      computes distribute { amountRef: payoutShare; onZero: skip_steps; pool: { from: parent; path: pool_amount_path; }; refField: pool_ref_field; statuses: [claimed, paid]; weightField: amount; }
-      moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.payoutShare; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", recipient_account_field); }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", source_account_field); }; }; capture: { payoutTransferId: transferId; }; }];
-      steps: [];
-    }
-  }
-  }
-  when(receipts) {
-    let(round_type): get(receipts, "round");
-    let(receipt_type): get(receipts, "receipt");
-    fields {
-      roundId: ref<round_type>;
-      receiptId: ref<receipt_type>;
-      currency { type: text; pattern: "^[A-Z]{3}$"; minLength: 3; maxLength: 3; }
-      feeAccountId { type: account<C>; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-      taxAccountId { type: account<C>; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-      residualAccountId { type: account<C>; "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-    }
-    parties { fee: feeAccountId; tax: taxAccountId; beneficiary: residualAccountId; }
-    lifecycle { states distributed; initial distributed; }
-    title: sentence(instrument);
-    summary: "Receipt-backed frozen-weight distribution";
-    agent_description: "Consume one allocation receipt against the round's frozen tickets. Cash distributions carve fee and VAT, floor each ticket share and pay the residual to its named owner. Loss mode records principal loss without cash.";
-    action create {
-      public: none;
-      agent_description: "Distribute one receipt once. All amounts and sources come from the consumed receipt and frozen funding snapshot.";
-      requires refs: { field: roundId; statuses: [settled]; match: { "fields.currency": fields.currency; }; };
-      receipt distribution: {
-        round_field: roundId; snapshot_ref: fundingSnapshot;
-        receipt_field: receiptId; receipt_path: get(receipts, "path"); mode: get(receipts, "mode");
-        fee_bps: get(receipts, "fee_bps"); vat_bps: get(receipts, "vat_bps");
-        fee_account_field: feeAccountId; tax_account_field: taxAccountId; residual_account_field: residualAccountId;
-        capture: distributionReceipt;
-      };
-      steps: [];
-    }
-  }
-}