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

package/src/version.ts

@@ -1,17 +1,5 @@
-/**
- * The two versions HSX carries, and the difference between them.
- *
- * `HSX_VERSION` is the npm package's semver: it moves when this compiler's
- * code changes, including changes that only affect diagnostics or docs.
- *
- * `HSX_IR_VERSION` is the format number stamped into every compiled document
- * as its `hsx` field. It moves only when the emitted IR shape changes in a
- * way a consumer must notice, so a runtime can refuse a document it does not
- * understand by reading one integer. A package release almost never bumps it.
- */
+/** Package version reported by the command line. */
+export const HSX_VERSION = "1.0.0-rc.1";
 
-/** Stamped into every compiled HSX-JSON document as `hsx`. */
-export const HSX_IR_VERSION = 1;
-
-/** Kept equal to the package.json version by `test/spec.spec.ts`. */
-export const HSX_VERSION = "1.0.0-beta.1";
+/** Canonical UDL contract version emitted by this compiler. */
+export const HSX_TARGET_UDL_VERSION = 1;

package/std/SEMANTICS.md

@@ -0,0 +1,130 @@
+# Settlement semantics frozen before legacy teardown
+
+This note records the behavior that the former archetype branches emitted on
+2026-09-01. The 48 canonical documents under
+`test/fixtures/general-path-oracle/` are the byte-level authority. This note is
+the human porting index.
+
+## Direct and held payments
+
+- `instant_transfer` stores the amount, currency, payer, and payee. Create pays
+  through one or more ordered pieces and ends in `paid`. A payer fee is an
+  `on_top` move. A payee fee is carved from the base amount. Exact, basis-point,
+  and tiered rules produce fee fields and `feeRules`. The finest common
+  refinement of all fee cuts produces piece fields and one partition. Floor
+  rounding sends the remainder to the named non-fee recipient. A derived
+  amount adds a floor percentage field, `derivedAmounts`, a platform party, and
+  its own transfer piece.
+- `held_payment` reserves every refined piece before release. It posts release
+  pieces, voids cancellation pieces, and keeps payer service fees outside the
+  held principal. Release and cancellation fee sides share the finest common
+  partition, so each stored piece has one release recipient and one cancel
+  recipient. States track each funding, release, cancellation, and abandonment
+  step. Abandonment refunds every still-held piece. A deadline release and a
+  caller decision release carry the named date or port clause. Retention is the
+  same form with one held piece, a release deadline, and cancellation back to
+  the contractor. Whole-amount mode funds the principal and on-top fee in one
+  action, then releases or cancels the principal whole. A condition and date
+  can coexist, with separate early and scheduled release actions.
+- `captured_payment` stores authorization total, reserve and reversal dates,
+  and both party accounts. It moves through `created`, `authorized`, optional
+  `partially_captured`, `settled`, `voided`, `expired`, `corrected`, or
+  `reversed`. Authorize reserves custody. Capture and capture-more consume the
+  authorized balance according to the declared mode. Settle posts the captured
+  amount. Void and expiry release the reserve. Correction and external reversal
+  use their declared ports and windows. Derived fees use the same floor,
+  partition, bearer, and position rules as direct payment.
+- `premium_forward` holds premium pieces, then forwards the net pieces after a
+  bind decision. It can abandon unbound custody. Policy reference, renewal due,
+  endorsement evidence, and lapse actions appear only when declared. Its fee
+  partition and floor remainder rules match `held_payment`.
+
+## Decisions and credit
+
+- `conditional_disbursement` emits a submitted parent with cap, currency,
+  source, destination, and the decision port. Denial terminates the parent. An
+  approved-amount child stores a runtime-bounded amount and a parent reference.
+  The child captures the port input, moves through `created`, `approved`, and
+  `paid`, and refuses reopening. Recovery is a separate transfer.
+- `advance` has two forms. A carved advance references a held settlement and
+  its recourse settlement, disburses once, and settles from the referenced
+  release without minting new value. A scheduled advance stores advance,
+  fee, repayable total, first due date, and one repayment field per fixed
+  installment. It partitions repayments to the repayable total and advances
+  before collecting each due installment.
+- `credit_facility` stores lender, borrower, draw destination, limit, currency,
+  and expiry. The facility can freeze and close. Each draw is a generated child
+  with amount, facility reference, and obligation reference. Draw admission
+  checks the facility state and aggregate limit. Resolution waits for the
+  referenced obligation state.
+
+## Schedules and usage
+
+- A finite `scheduled` transfer stores total, first due date, and one money
+  field per installment. Floor division creates equal pieces and gives the
+  final field the remainder. States and actions unroll in order. Each action
+  carries its due rule and cumulative duration offset.
+- Scheduled obligation mode emits a parent plus one generated payment child per
+  installment. The parent stores principal, delinquency dates, party accounts,
+  partitions, and aggregate invariants. It supports draft approval, optional
+  advance, fixed collection and delinquency actions, write-off, and completion.
+  Each child binds parent fields, repays once, and can refund once.
+- `recurring_collection` with a finite count uses the scheduled construction.
+  Open recurrence stores one amount and anchor, opens one period at a time,
+  collects that period, and permits cancellation. It never unrolls an unbounded
+  runtime loop.
+- `metered` stores one money field for each declared meter and a period end.
+  Every charge moves directly from payer to payee. The instrument never accrues
+  custody. Closing the period only changes state.
+
+## Collections and distributions
+
+- `pooled_split` stores the pool total, due date, and one share amount and
+  account per recipient. Positive shares total exactly 10,000 basis points.
+  Floor division assigns each share, and the named remainder recipient absorbs
+  minor-unit residue. Funding and distribution actions unroll in roster order.
+- `weighted_distribution` emits an open parent and an entitlement child. The
+  parent stores source, total, record date, and maximum recipient count. A port
+  freezes the entitlement snapshot. Child rows store recipient, weight, source,
+  currency, and parent reference. Largest-remainder distribution pays children
+  once. Aggregate clauses cap and total the child set. Withholding is refused
+  and correction creates a new distribution. Its `flat` form emits a single
+  claim instead. The caller supplies typed pool, weight, and group references,
+  their state gates, copy and match maps, and the pool amount path.
+- `threshold_pool` emits a pool parent and commitment child. The parent stores
+  target, close date, maximum contributors, beneficiary, and currency. It moves
+  through open, active, failed, or settled based on aggregate commitment gates.
+  Each commitment can cancel before collection, collect into the round, or
+  refund after failure. Its referenced-contribution form accepts a published
+  contribution instrument, beneficiary account, and memo and emits no child.
+- `security_deposit` reserves the full amount. A claim port posts either the
+  whole hold or a decided amount bounded by the hold. The explicit remainder
+  returns to the payer. A return port voids the whole hold. The deadline form
+  adds machine expiry and unfunded cancellation. Claim and return targets can
+  name either party.
+
+## Composition and unwind
+
+- `swap` stores both side amounts, accounts, fees, currency, and optional
+  clawback date. Funding is atomic across both sides. Release, settlement,
+  cancellation, dispute, abandonment, and clawback preserve the two-sided
+  conservation group. Side fees keep their declared bearer and position.
+  `distinctParties` prevents self-dealing. Unwind refunds each side and applies
+  the declared penalty tiers without changing the principal partition. Fixed
+  side names, state order, action bindings, parked-state reasons, and ID prefix
+  are general compile-time parameters.
+- `settlement_batch` emits a batch plus capture, credit-adjustment, and
+  debit-adjustment children. The batch stores close time, settlement and payout
+  accounts, beneficiary reference, and currency. Close freezes intake.
+  Calculate signs capture, fee, and reversal entries. Approve rejects a negative
+  position when configured. Instruct, acknowledge, and reconcile use the
+  declared payout port. Child references and statuses define every aggregate
+  and signed-sum input.
+- `rotating_pool` emits one parent plus one contribution child per fixed member.
+  The parent unrolls active and ready states for every cycle and checks that each
+  member row exists exactly once. Every child unrolls due, funded, defaulted,
+  guaranteed, paid, and completed states for every cycle. Due offsets scale the
+  fixed recurrence. A funded or guaranteed contribution pays the roster's fixed
+  beneficiary for that cycle. The final close requires the escrow account to be
+  drained. Its referenced-membership form delegates those member cycles to a
+  published membership instrument and emits only the parent.

package/std/settlements/advance.hsx

@@ -0,0 +1,177 @@
+module std.settlements.advance
+
+export instrument advance<C>(
+  funder: party,
+  to: party,
+  amount: money<C>,
+  fee: optional<percent>,
+  count: optional<integer>,
+  every: optional<text>,
+  first_due: optional<date>,
+  against: optional<ref>,
+) {
+  let(amount_path): concat("fields.", amount);
+  let(currency_path): "fields.currency";
+  let(funder_field): camel(concat(funder, "_account_id"));
+  let(to_field): camel(concat(to, "_account_id"));
+
+  agent_description: "Reach for advance when the {funder} pays the {to} up front and is repaid afterwards, either out of a carved hold release or over scheduled repayments. Pick deposit for a refundable reservation and instant transfer when nobody repays the payer.";
+  title: sentence(instrument);
+  id_prefix: prefix(instrument);
+  parties {
+    payer: funder;
+    beneficiary: to;
+  }
+
+  when(against) {
+    let(hold_name): owner(against);
+    summary: "Advance to the {to} repaid by carving the {hold_name} release";
+    description: "Advance: the {funder} disburses {amount} to the {to} and is repaid out of the {hold_name} release, which pays the {funder} in the {to}'s place";
+    fields {
+      amount {
+        type: money<C>;
+        description: "The advanced amount in {C} minor units, disbursed to the {to} up front";
+      }
+      carve_hold_id {
+        type: ref<hold_name>;
+        description: "The {hold_name} bound to this advance";
+        pattern: concat("^", prefix(hold_name), "_(sandbox|live)_[a-z0-9]{8,64}$");
+      }
+      carve_recourse_1_id {
+        type: ref<recourse>;
+        description: "The recourse bound to this advance";
+        pattern: "^reco_(sandbox|live)_[a-z0-9]{8,64}$";
+      }
+    }
+    required: [to_field, funder_field, amount, carveHoldId, carveRecourse1Id, currency];
+    lifecycle {
+      states created advanced repaid;
+      initial created;
+      on disburse: created -> advanced;
+      on settle: advanced -> repaid;
+    }
+    action create {
+      agent_description: "Open the advance row before any money moves. The caller supplies the {amount}, both party accounts, and the ids of the {hold_name} and the recourse that back repayment. Nothing is disbursed here.";
+      summary: concat("Create a ", words(instrument));
+      steps: [];
+      moves: [];
+    }
+    action disburse {
+      agent_description: "Pay the {amount} from the {funder} to the {to}. The advance must be created, the bound {hold_name} funded, and the recourse active, both matching this amount and currency. The transfer posts straight out and does not unwind.";
+      summary: "Disburse the {amount} to the {to}";
+      requires refs: [{
+        field: carveHoldId;
+        match: {
+          [currency_path]: currency_path;
+          [amount_path]: amount_path;
+        };
+        statuses: [funded];
+      }, {
+        field: carveRecourse1Id;
+        match: {
+          [currency_path]: currency_path;
+          [amount_path]: amount_path;
+        };
+        statuses: [active];
+      }];
+      moves: [{ amount: amount; from: payer; to: beneficiary; key: transfer; operation: create; }];
+      steps: [];
+    }
+    action settle {
+      agent_description: "Close the advance once the {hold_name} has released to the {funder} in the {to}'s place. The advance must already be disbursed. No money moves here, the release did the repaying.";
+      summary: concat("Close the advance once the ", hold_name, " has released to the ", funder);
+      steps: [];
+      moves: [];
+    }
+  }
+
+  when_not(against) {
+    let(repayment_fields): names("repayment", count, "Amount");
+    let(first_target): if_eq(count, 1, "repaid", "repaying_1");
+    let(states_key): "states";
+    let(first_due_field): camel(first_due);
+    summary: concat("Advance to ", to, " repaid over ", count, " anchors");
+    description: concat("Advance: the ", funder, " disburses ", amount, " to the ", to, ", repaid over ", count, " scheduled repayments plus the funder's discount");
+    fields {
+      amount {
+        type: money<C>;
+        description: "The advanced amount in {C} minor units, disbursed to the {to} up front";
+      }
+      fee_amount {
+        type: money<C>;
+        description: concat(fee, " of ", amount, ", the funder's discount repaid on top of the advance");
+      }
+      repayable_amount {
+        type: money<C>;
+        description: concat(amount, " + feeAmount: the total the repayment fields below partition exactly");
+      }
+      [first_due_field] {
+        type: date;
+        description: concat("Due date of the first repayment; repayment k falls ", every, " after its predecessor");
+      }
+      repayment_1_amount {
+        type: money<C>;
+        description: concat("Repayment 1 of ", count, " (carries the integer-division remainder): about 33.34% of repayableAmount, collected on its own stored-date anchor");
+      }
+      for repayment in sub(count, 1) {
+        let(index): add(repayment, 1);
+        repayment[index]Amount {
+          type: money<C>;
+          description: concat("Repayment ", index, " of ", count, ": about 33.33% of repayableAmount, collected on its own stored-date anchor");
+        }
+      }
+    }
+    lifecycle {
+      states created advanced;
+      [states_key]: [first_target];
+      initial created;
+      on disburse: created -> advanced;
+      on collect_repayment_1: advanced -> [first_target];
+      for repayment in sub(count, 1) {
+        let(index): add(repayment, 1);
+        let(previous): concat("repaying_", repayment);
+        let(target): if_eq(index, count, "repaid", concat("repaying_", index));
+        [states_key]: [target];
+        on collect_repayment_[index]: [previous] -> [target];
+      }
+    }
+    partitions: [{
+      piece_fields: repayment_fields;
+      total_field: repayableAmount;
+    }, {
+      piece_fields: [amount, feeAmount];
+      total_field: repayableAmount;
+    }];
+    action create {
+      agent_description: "Open the advance row before any money moves. The caller supplies the {amount}, the fee amount, the repayable total, and the first repayment date. The repayment fields must partition the repayable total exactly. Nothing is disbursed here.";
+      summary: concat("Create a ", words(instrument));
+      steps: [];
+      moves: [];
+    }
+    action disburse {
+      agent_description: "Pay the {amount} from the {funder} to the {to} and start the repayment schedule. The advance must be created. The transfer posts straight out and does not unwind. Each repayment is collected on its own stored date anchor.";
+      summary: "Disburse the {amount} to the {to}";
+      moves: [{ amount: amount; from: payer; to: beneficiary; key: transfer; operation: create; }];
+      steps: [];
+    }
+    action collect_repayment_1 {
+      summary: concat("Collect repayment 1 of ", count);
+      due: { field: first_due_field; };
+      moves: [{ amount: repayment1Amount; from: beneficiary; to: payer; key: transfer; operation: create; }];
+      steps: [];
+    }
+    for repayment in sub(count, 1) {
+      let(index): add(repayment, 1);
+      let(repayment_field): concat("repayment", index, "Amount");
+      action collect_repayment_[index] {
+        summary: concat("Collect repayment ", index, " of ", count);
+        due: {
+          field: first_due_field;
+          offset: scale_duration(every, sub(index, 1));
+        };
+        moves: [{ amount: repayment_field; from: beneficiary; to: payer; key: transfer; operation: create; }];
+        steps: [];
+      }
+    }
+  }
+}

package/std/settlements/cancellable_booking.hsx

@@ -0,0 +1,87 @@
+module std.settlements.cancellable_booking
+
+export instrument cancellable_booking<C>(
+  guest: party,
+  host: party,
+  amount: money<C>,
+  starts_at: date,
+  late_penalty_bps: integer,
+  late_within: text,
+  early_penalty_bps: integer,
+  offer_life: text,
+) {
+  let(guest_account_field): camel(concat(guest, "_account_id"));
+  let(host_account_field): camel(concat(host, "_account_id"));
+  let(reference_filter_key): "x-hyperscale-reference-filter";
+  let(owner_id_key): "owner.id";
+  let(owner_type_key): "owner.type";
+  fields {
+    amount { type: money<C>; description: concat("Booking price in minor units, held away from both the ", words(guest), " and the ", words(host), " until the booking ends"); }
+    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
+    starts_at { type: date; description: "When the booking starts; the cancellation penalty is priced against the time left before it"; }
+    [guest_account_field] { type: account<C>; description: concat("The ", words(guest), " account the booking is taken from and the refund returns to"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter_key]: { column: role; values: [customer_balance]; }; }
+    [host_account_field] { type: account<C>; description: concat("The ", words(host), " account the booking and any penalty end up in"); pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$"; [reference_filter_key]: { column: role; values: [customer_balance]; }; }
+  }
+  lifecycle {
+    states created held cancellation_quoted canceled settled completed;
+    initial created;
+    on take: created -> held;
+    on complete: held | cancellation_quoted -> completed;
+    on cancel: held -> cancellation_quoted;
+    on confirm: cancellation_quoted -> canceled;
+    on retain: canceled -> settled;
+  }
+  parties { beneficiary: host_account_field; payer: guest_account_field; }
+  required: [amount, currency, guest_account_field, host_account_field, starts_at];
+  title: sentence(instrument);
+  agent_description: concat("Reach for cancellable booking when the ", words(guest), " pays up front and can back out at a price they see before they agree to it. The money sits in a holding account, the penalty is priced against the time left before the start, and the quote is frozen until it expires. Pick held payment when there is no cancellation price to quote.");
+  id_prefix: prefix(instrument);
+  summary: concat("Booking the ", words(guest), " can cancel at a price they see before they agree to it");
+  description: "A booking whose cancellation is quoted rather than argued: the penalty is priced against the time left before the start, frozen with the terms it was read from, and paid only if the guest confirms while the offer is still alive";
+  action create {
+    agent_description: concat("Open the booking and provision the holding account the price sits in. No money moves. The price, the currency, the start moment, and both party accounts are fixed here. Call take next to collect from the ", words(guest), ".");
+    summary: concat("Open a ", words(instrument), " and its holding account");
+    moves: [];
+    steps: [{ operation: "account.escrow.provision"; bind: { currency: { from: instance; path: fields.currency; }; [owner_id_key]: { from: instance; path: productId; }; [owner_type_key]: { from: const; value: product; }; productId: { from: instance; path: productId; }; role: { from: const; value: product_escrow; }; }; capture: { bookingHoldingAccountId: accountId; }; }];
+  }
+  action take {
+    agent_description: concat("Move the whole booking price out of the ", words(guest), " account into the holding account. This moves money. Only a created booking takes. Neither party can spend the money until the booking completes or a cancellation is confirmed.");
+    summary: concat("Take the booking price from the ", words(guest), " into the holding account");
+    moves: [{ key: booking; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", amount); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: refs.bookingHoldingAccountId; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", guest_account_field); }; }; capture: { bookingTransferId: transferId; }; }];
+    steps: [];
+  }
+  action complete {
+    summary: concat("Release the whole booking to the ", words(host), " once the stay has started, even with a cancellation quote parked un-acted");
+    due { field: starts_at; }
+    moves: [{ key: release; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", amount); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", host_account_field); }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.bookingHoldingAccountId; }; }; capture: { releaseTransferId: transferId; }; }];
+    steps: [];
+  }
+  action cancel {
+    agent_description: "Price the cancellation and freeze that price. No money moves. The penalty is computed from the time left before the start, and the quote expires on its own, after which a new cancel prices it again. Call confirm to spend the quote.";
+    summary: "Price the cancellation and hold that price open";
+    quote {
+      anchorField: starts_at;
+      baseField: amount;
+      chargeRef: cancellationPenaltyAmount;
+      charges: [{ bps: late_penalty_bps; withinOffset: late_within; }, { bps: early_penalty_bps; }];
+      expires { offset: offer_life; }
+      fixes: [amount, guest_account_field];
+      netDestinationField: guest_account_field;
+      netRef: cancellationRefundAmount;
+    }
+    moves: []; steps: [];
+  }
+  action confirm {
+    agent_description: concat("Spend the frozen quote and return the net refund to the ", words(guest), ". This moves money and does not reverse. It requires an un-expired quote from cancel, and the penalty the refund left behind is paid to the ", words(host), " by retain.");
+    summary: concat("Spend the quoted cancellation and return the net to the ", words(guest));
+    commit: cancel;
+    moves: [{ key: refund; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.cancellationRefundAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", guest_account_field); }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.bookingHoldingAccountId; }; }; capture: { cancellationTransferId: transferId; }; }];
+    steps: [];
+  }
+  action retain {
+    agent_description: concat("Pay the quoted cancellation penalty out of the holding account to the ", words(host), ". This moves money and does not reverse. The booking must already be canceled, so the penalty figure is the one the quote fixed.");
+    summary: concat("Pay the quoted penalty that the refund left behind to the ", words(host));
+    moves: [{ key: penalty; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.cancellationPenaltyAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", host_account_field); }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: refs.bookingHoldingAccountId; }; }; capture: { penaltyTransferId: transferId; }; }];
+    steps: [];
+  }
+}

package/std/settlements/captured_payment.hsx

@@ -0,0 +1,144 @@
+module std.settlements.captured_payment
+
+export instrument captured_payment<C>(payer: party, payee: party, amount: money<C>, reserve_until: date, correction: condition, external_reversal: condition, capture_mode: text, correction_mode: text, negative_position: text, timeout: text, derived_amount: optional<block>) {
+  let(correction_name): correction;
+  let(reversal_name): external_reversal;
+  let(reversal_window): external_reversal_within;
+  let(instrument_words): words(instrument);
+  when(derived_amount) {
+    let(derived_field): get(derived_amount, "field");
+    let(derived_source): get(derived_amount, "source");
+    let(derived_rule): get(derived_amount, "rule");
+    let(derived_bearer): get(derived_amount, "bearer");
+  }
+  agent_description: "Reach for captured payment when the {payee} reserves against the {payer} first and then takes the money in slices before {reserve_until}. Pick instant transfer when the whole amount moves at once, and deposit when the reservation is claimed or returned whole.";
+  summary: "Capture reservation from {payer} to {payee}";
+  title: sentence(instrument);
+  description: "Payer reservation captured by the payee in slices within a fixed window";
+  fields {
+    when(derived_amount) {
+      let(fee_collection_key): "x-hyperscale-fee-collection-port";
+      let(reference_filter_key): "x-hyperscale-reference-filter";
+      platformAccountId {
+        type: account<C>;
+        description: "The product fee collection account";
+        pattern: "^acct_(sandbox|live)_[a-z0-9]{8,64}$";
+        [fee_collection_key]: true;
+        [reference_filter_key]: { column: role; values: [customer_balance, product_revenue]; };
+      }
+    }
+    amount { type: money<C>; description: "Maximum captured amount in {C} minor units"; }
+    reserve_until { type: date; description: "Reservation expiry that releases any uncaptured remainder"; }
+    reversalUntil { type: date; description: "Machine-owned external reversal cutoff anchored when settlement completes"; optional: true; }
+    when(derived_amount) {
+      [derived_field] { type: money<C>; description: "Machine-computed {derived_rule} of {derived_source}; callers never supply it"; pattern: "^[1-9][0-9]{0,17}$"; optional: true; }
+    }
+  }
+  lifecycle {
+    states created authorized partially_captured settled voided expired corrected reversed;
+    initial created;
+    on authorize: created -> authorized;
+    on capture: authorized -> partially_captured;
+    on capture_more: partially_captured -> partially_captured;
+    on settle: authorized | partially_captured -> settled;
+    on void: authorized -> voided;
+    on expire: authorized -> expired;
+    on settle_on_expiry: partially_captured -> settled;
+    on [correction_name]: settled -> corrected;
+    on [reversal_name]: settled -> reversed;
+  }
+  parties {
+    payer: payer;
+    beneficiary: payee;
+  }
+  when(derived_amount) {
+    computes derived: { field: derived_field; source_field: derived_source; rounding: floor; rule: { kind: percentage_of; bps: derived_rule; }; };
+  }
+  action create {
+    let(metadata_instrument): "metadata.instrumentId";
+    let(metadata_instance): "metadata.instrumentInstanceId";
+    let(metadata_phase): "metadata.phase";
+    agent_description: "Open the payment row before anything is reserved. The caller supplies the {amount}, the currency, and both party accounts. This reserves nothing, call authorize next.";
+    summary: "Create a {instrument_words}";
+    when(derived_amount) {
+      moves: [{ key: "derived_amount"; operation: internal_transfer.create; bind: { amount: { from: instance; path: concat("fields.", derived_field); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: fields.platformAccountId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: create; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", camel(derived_bearer), "AccountId"); }; }; capture: { createDerivedAmountTransferId: transferId; }; }];
+    }
+    steps: [];
+  }
+  action authorize {
+    agent_description: "Reserve the {amount} against the {payer} in the {payee}'s favor until {reserve_until}. The payment must be created. The money is held, not paid: capture and settle post it, void and expiry release it.";
+    summary: "Reserve the {amount} until {reserve_until}";
+    moves: [{ key: reservation; amount: amount; from: payer; to: beneficiary; operation: reserve; }];
+    steps: [];
+  }
+  action capture {
+    agent_description: "Post the first capture slice out of the live reservation. The payment must be authorized and the caller passes captureAmount in minor units. The slice settles for good and void can no longer release the reservation. Call before {reserve_until}.";
+    summary: "Post one strict partial capture slice";
+    deadline { field: reserve_until; };
+    input { type: object; additional_properties: false; properties: { captureAmount: { description: "Positive partial capture amount in minor units"; pattern: "^[1-9][0-9]{0,17}$"; type: string; }; }; required: [captureAmount]; }
+    moves: [{ key: post; operation: internal_transfer.post; bind: { amount: { from: input; path: captureAmount; }; currency: { from: instance; path: fields.currency; }; postMode: { from: const; value: partial_only; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; capture: { capturedAmount: postedAmount; }; }];
+    steps: [];
+  }
+  action capture_more {
+    agent_description: "Post another capture slice out of a partly captured reservation. Call this only after capture took the first slice. Each slice settles for good, and the uncaptured remainder still releases at {reserve_until}.";
+    summary: "Post another strict partial capture slice";
+    deadline { field: reserve_until; };
+    input { type: object; additional_properties: false; properties: { captureAmount: { description: "Positive partial capture amount in minor units"; pattern: "^[1-9][0-9]{0,17}$"; type: string; }; }; required: [captureAmount]; }
+    moves: [{ key: post; operation: internal_transfer.post; bind: { amount: { from: input; path: captureAmount; }; currency: { from: instance; path: fields.currency; }; postMode: { from: const; value: partial_only; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; capture: { capturedAmount: postedAmount; }; }];
+    steps: [];
+  }
+  action settle {
+    agent_description: "Post the whole reserved remainder and finish the payment. The payment must be authorized or partly captured. The money settles and the external reversal window opens on reversalUntil.";
+    summary: "Post the full reserved remainder and settle";
+    deadline { field: reserve_until; };
+    sets(at) { field: reversalUntil; offset: reversal_window; };
+    moves: [{ key: post; operation: internal_transfer.post; bind: { transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; capture: { capturedAmount: postedAmount; }; }];
+    steps: [];
+  }
+  action void {
+    agent_description: "Release the reservation whole and cancel the payment. Only an authorized reservation with nothing captured can void. Once any slice is captured, settle it or let it expire instead.";
+    summary: "Release an entirely uncaptured reservation";
+    moves: [{ key: void; operation: internal_transfer.void; bind: { reason: { from: const; value: "Reservation voided before any capture"; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; }];
+    steps: [];
+  }
+  action expire {
+    summary: "Release an uncaptured reservation at expiry";
+    due { field: reserve_until; };
+    moves: [{ key: void; operation: internal_transfer.void; bind: { reason: { from: const; value: "Uncaptured reservation expired"; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; }];
+    steps: [];
+  }
+  action settle_on_expiry {
+    summary: "Release the uncaptured remainder and settle captured slices";
+    due { field: reserve_until; };
+    sets(at) { field: reversalUntil; offset: reversal_window; };
+    moves: [{ key: void; operation: internal_transfer.void; bind: { reason: { from: const; value: "Uncaptured remainder released at expiry"; }; transferId: { from: instance; path: refs.authorizeReservationTransferId; }; }; }];
+    steps: [];
+  }
+  action [correction_name] {
+    let(metadata_clawback): "metadata.clawbackOfTransferId";
+    let(metadata_instrument): "metadata.instrumentId";
+    let(metadata_instance): "metadata.instrumentInstanceId";
+    let(metadata_phase): "metadata.phase";
+    let(correction_capture): camel(concat(correction_name, "_transfer_transfer_id"));
+    agent_description: "Return the whole captured amount to the {payer} after the payment settled. Only a settled payment corrects, and only the party the product authorized may call it. The money moves back and there is no undo.";
+    summary: "Return the full captured amount on payee correction";
+    port { allowed_parties: [if_eq(at(correction_allowed, 1), payee, "beneficiary", "payer")]; };
+    moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.capturedAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payer, "AccountId"); }; [metadata_clawback]: { from: instance; path: refs.authorizeReservationTransferId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: correction_name; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payee, "AccountId"); }; }; capture: { [correction_capture]: transferId; }; }];
+    steps: [];
+  }
+  action [reversal_name] {
+    let(metadata_clawback): "metadata.clawbackOfTransferId";
+    let(metadata_instrument): "metadata.instrumentId";
+    let(metadata_instance): "metadata.instrumentInstanceId";
+    let(metadata_phase): "metadata.phase";
+    let(reversal_capture): camel(concat(reversal_name, "_transfer_transfer_id"));
+    agent_description: "Return the whole captured amount to the {payer} on an external reversal. The payment must be settled and the call must land before reversalUntil. The caller passes externalReference, which stays in the receipt. There is no undo.";
+    summary: "Return the full captured amount on an external reversal";
+    capture(input) { externalReference: externalReference; };
+    deadline { field: reversalUntil; };
+    input { type: object; additional_properties: false; properties: { externalReference: { description: "Required decision reference retained in the operation receipt"; max_length: 180; min_length: 1; type: string; }; }; required: [externalReference]; }
+    port { allowed_parties: [if_eq(at(external_reversal_allowed, 1), payee, "beneficiary", "payer")]; };
+    moves: [{ key: transfer; operation: internal_transfer.create; bind: { amount: { from: instance; path: refs.capturedAmount; }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", payer, "AccountId"); }; [metadata_clawback]: { from: instance; path: refs.authorizeReservationTransferId; }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: reversal_name; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payee, "AccountId"); }; }; capture: { [reversal_capture]: transferId; }; }];
+    steps: [];
+  }
+}