@hyperscale0/hsx 2.4.1 → 3.0.0

package/std/money_flows/security_deposit.hsx

@@ -1,248 +0,0 @@
-module std.money_flows.security_deposit
-
-// Collateral deposit reserved against a payer's account in favor of a holder, returned in full or claimed against damages.
-//
-// ### Purpose
-// `security_deposit` reserves collateral funds for vehicle rentals, property leasing, equipment hire, and security bonds.
-// Funds remain held until the rental or lease concludes. The holder can either return the deposit in full
-// or assess damages, claim a decided partial amount, and return the exact unspent remainder.
-//
-// ### Selection guidance
-// - vs `held_payment`: `security_deposit` holds collateral where the standard outcome is returning 100% of the funds
-//   to the payer, and claims are partial damage assessments. `held_payment` holds payment consideration where the
-//   standard outcome is releasing 100% of the funds to the payee upon delivery.
-// - vs `cancellable_booking`: `cancellable_booking` holds booking fees and applies time-based cancellation penalties.
-//   `security_deposit` holds damage collateral and supports arbitrary damage claims with remainder refund.
-//
-// ### Parameters
-// - `payer`: The customer providing the deposit collateral.
-// - `holder`: The merchant or owner holding the deposit rights.
-// - `amount`: Total reserved deposit amount in minor units of currency `C`.
-// - `claim`: Optional condition port triggering a damage claim.
-// - `return`: Optional condition port triggering full return of the deposit.
-// - `claim_amount`: Optional block defining partial claim logic (`field`, `bound`, `remainder`).
-// - `deadline`: Optional stored date anchor for automatic deposit release or expiry.
-// - `claim_to`: Optional alternate destination for claimed funds.
-// - `return_to`: Optional alternate destination for returned funds.
-// - `memo`: Optional memo text stored on the deposit record.
-// - `claim_input`: Optional custom input schema for the claim action.
-// - `claim_capture`: Optional capture mappings for claim evidence.
-// - `fund_failure_point`: Optional configuration for deposit funding failure.
-// - `id_prefix_override`: Optional custom prefix for generated instrument IDs.
-//
-// ### Decision ports
-// - `claim`: Port permitting the holder to submit a damage claim.
-// - `return`: Port permitting the holder to return the deposit to the payer.
-//
-// ### Example
-// ```hsx
-// program deposit_example "Deposit example"
-// import { security_deposit } from "std/money_flows"
-// party renter: person
-// party owner: business
-// settlement security_deposit = security_deposit {
-//   payer: renter
-//   holder: owner
-//   amount: depositAmount: money(SAR)
-//   claim: port assess_damage
-//   claim_amount: decided {
-//     field: damageAmount
-//     bound: depositAmount
-//     remainder: return
-//   }
-//   return: port return_deposit
-// }
-// port assess_damage {
-//   allowed: [owner]
-//   shape: { damageAmount: money(SAR), evidence: text }
-// }
-// port return_deposit { allowed: [owner] }
-// ```
-export instrument security_deposit<C>(payer: party, holder: party, amount: money<C>, claim: optional<condition>, return: optional<condition>, claim_amount: optional<block>, deadline: optional<date>, claim_to: optional<party>, return_to: optional<party>, memo: optional<text>, claim_input: optional<block>, claim_capture: optional<block>, fund_failure_point: optional<text>, id_prefix_override: optional<text>) {
-  let(claim_name): claim;
-  let(return_name): return;
-  let(payer_account_field): camel(concat(payer, "_account_id"));
-  let(holder_account_field): camel(concat(holder, "_account_id"));
-  let(claim_field): get(claim_amount, "field");
-  let(claim_bound): get(claim_amount, "bound");
-  let(claim_remainder): get(claim_amount, "remainder");
-  let(deadline_field): concat(deadline);
-  let(memo_field): concat(memo);
-  agent_description: "Reach for security deposit when money is reserved against the {payer} in the {holder}'s favor and later claimed or returned. The funds stay reserved and move only on the claim. Pick captured payment when the holder takes the money in slices, and instant transfer when nothing is held.";
-  summary: "Refundable deposit from {payer} held for {holder}";
-  title: sentence(instrument);
-  when(id_prefix_override) { id_prefix: id_prefix_override; }
-  when_not(deadline) {
-    when_not(claim_amount) {
-      description: concat("Deposit: the ", amount, " is reserved against the ", payer, "'s account in the ", holder, "'s favor, then claimed or returned in full");
-    }
-    when(claim_amount) {
-      description: concat("Deposit: the ", amount, " is reserved against the ", payer, "'s account in the ", holder, "'s favor, then ", claim_field, " is claimed and the exact remainder returned, or the deposit is returned in full");
-    }
-  }
-  fields {
-    when_not(deadline) {
-      amount { type: money<C>; description: "The deposit amount in {C} minor units, reserved in full and fully accounted on claim or return"; }
-    }
-    when(deadline) {
-      let(reference_filter_key): "x-hyperscale-reference-filter";
-      amount { type: money<C>; description: "Positive minor-unit integer amount serialized as a string (at most 18 digits)"; }
-      [deadline_field] { type: date; }
-      [holder_account_field] { type: account<C>; description: "Hyperscale account ID"; [reference_filter_key]: { column: role; values: [customer_balance]; }; }
-      [payer_account_field] { type: account<C>; description: "Hyperscale account ID"; [reference_filter_key]: { column: role; values: [customer_balance]; }; }
-      when(memo) { [memo_field] { type: text; max_length: 180; min_length: 1; optional: true; } }
-    }
-  }
-  lifecycle {
-    when_not(deadline) {
-      states created held claimed returned;
-      initial created;
-      on place_deposit: created -> held;
-      on [claim_name]: held -> claimed;
-      on [return_name]: held -> returned;
-    }
-    when(deadline) {
-      states created held claimed returned expired canceled;
-      initial created;
-      on cancel: created -> canceled;
-      on claim: held -> claimed;
-      on expire: held -> expired;
-      on fund: created -> held;
-      on return: held -> returned;
-    }
-  }
-  parties {
-    payer: payer;
-    beneficiary: holder;
-  }
-  when_not(deadline) {
-    action create {
-      agent_description: "Open the deposit row before anything is reserved. The caller supplies the {amount}, the currency, and the {payer} and {holder} accounts. Nothing is reserved yet, call place deposit next.";
-      summary: concat("Create a ", words(instrument));
-      moves: [];
-      steps: [];
-    }
-    action place_deposit {
-    agent_description: "Reserve the {amount} against the {payer}'s account in the {holder}'s favor. The deposit must be created. The money is held, not paid: the claim posts it to the {holder} and the return releases it back.";
-    let(metadata_instrument): "metadata.instrumentId";
-    let(metadata_instance): "metadata.instrumentInstanceId";
-    let(metadata_phase): "metadata.phase";
-    summary: "Reserve the {amount} against the {payer}'s account";
-    moves: [{ key: reservation; operation: internal_transfer.reserve; bind: { amount: { from: instance; path: concat("fields.", amount); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", holder_account_field); }; [metadata_instrument]: { from: const; value: instrument; }; [metadata_instance]: { from: instance; path: instrumentInstanceId; }; [metadata_phase]: { from: const; value: place_deposit; }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { placeDepositReservationTransferId: transferId; }; }];
-    sandbox_failure_point: funding;
-    steps: [];
-    }
-    action [claim_name] {
-    agent_description: "Claim the held deposit for the {holder}. The deposit must be in held. The reservation settles here, whole or up to the decided amount with the exact remainder released back to the {payer}. There is no return afterwards.";
-    summary: "Claim the deposit for the {holder} through {claim}";
-    when(claim_allowed) { port { allowed_parties: claim_allowed; }; }
-    when_not(claim_amount) {
-      moves: [{ key: post; operation: internal_transfer.post; bind: { transferId: { from: instance; path: refs.placeDepositReservationTransferId; }; }; }];
-    }
-    when(claim_amount) {
-      let(decided_clause): "decided amount";
-      input {
-        type: object;
-        additional_properties: false;
-        properties {
-          for input_name in keys(claim_fields) {
-            [input_name]: get(claim_fields, input_name);
-          }
-        }
-        required: keys(claim_fields);
-      }
-      [decided_clause]: { field: claim_field; bound_field: claim_bound; remainder_action: return_name; };
-      moves: [{ key: post; operation: internal_transfer.post; bind: { amount: { from: input; path: claim_field; }; currency: { from: instance; path: fields.currency; }; postMode: { from: const; value: partial_only; }; transferId: { from: instance; path: refs.placeDepositReservationTransferId; }; }; }, { key: remainder; operation: internal_transfer.void; bind: { reason: { from: const; value: "Return the unclaimed deposit remainder"; }; transferId: { from: instance; path: refs.placeDepositReservationTransferId; }; }; }];
-    }
-    steps: [];
-    }
-    action [return_name] {
-      agent_description: "Return the held deposit to the {payer}. The deposit must be in held and unclaimed. This releases the reservation whole and the {holder} receives nothing.";
-      summary: "Return the deposit to the {payer} through {return}";
-      when(return_fields) {
-        input {
-          type: object;
-          additional_properties: false;
-          properties {
-            for input_name in keys(return_fields) {
-              [input_name]: get(return_fields, input_name);
-            }
-          }
-          required: keys(return_fields);
-        }
-        capture_input: {
-          for item in keys(return_fields) { [item]: item; }
-        };
-      }
-      port { allowed_parties: return_allowed; };
-      moves: [{ key: void; operation: internal_transfer.void; bind: { reason: { from: const; value: "Deposit returned in full"; }; transferId: { from: instance; path: refs.placeDepositReservationTransferId; }; }; }];
-      steps: [];
-    }
-  }
-  when(deadline) {
-    required: [payer_account_field, holder_account_field, amount, currency, deadline_field];
-    caller_parked_states: { created: "funding or canceling an unfunded hold is the payer's decision"; };
-    distinct_parties: true;
-    dials: [{ field: deadline_field; key: holding_window; kind: window; maxOffset: "P90D"; summary: "Maximum time before the machine returns an unclaimed hold."; title: "Holding window"; }];
-    action create {
-      agent_description: "Open the hold by recording the {payer}, the {holder}, the {amount}, and the deadline. No money moves here, so a created hold costs the {payer} nothing until fund runs. The deadline is when the machine returns anything still unclaimed.";
-      deadline: { field: deadline_field; };
-      summary: concat("Create a ", words(instrument));
-      moves: [];
-      steps: [];
-    }
-    action fund {
-      agent_description: "Reserve the whole {amount} out of the {payer}'s balance for the {holder}. This moves money and the {payer} can no longer spend it. Only a created hold funds. The reservation carries no expiry of its own, so the hold's deadline governs when it comes back.";
-      deadline: { field: deadline_field; };
-      moves: [{ key: reservation; operation: internal_transfer.reserve; bind: { amount: { from: instance; path: concat("fields.", amount); }; currency: { from: instance; path: fields.currency; }; destinationAccountId: { from: instance; path: concat("fields.", holder_account_field); }; productId: { from: instance; path: productId; }; sourceAccountId: { from: instance; path: concat("fields.", payer_account_field); }; }; capture: { holdTransferId: transferId; }; }];
-      when(fund_failure_point) { sandbox_failure_point: fund_failure_point; }
-      when_not(fund_failure_point) { sandbox_failure_point: funding; }
-      steps: [];
-      summary: "Fund the security deposit";
-    }
-    action claim {
-      when_not(claim_amount) {
-        agent_description: "Post the whole reservation to the {holder}. This moves money and does not reverse. Only a funded hold claims.";
-        moves: [{ key: "claim"; operation: internal_transfer.post; bind: { transferId: { from: instance; path: refs.holdTransferId; }; }; }];
-      }
-      deadline: { field: deadline_field; };
-      when(claim_capture) { capture_input: claim_capture; }
-      when(claim_amount) {
-        agent_description: "Post the {holder}'s decided amount out of the reservation and void the remainder back to the {payer} in one linked group. This moves money and does not reverse. Only a funded hold claims, and the claimed amount cannot exceed the held {amount}.";
-        decided_amount: { field: claim_field; bound_field: claim_bound; remainder_action: claim_remainder; };
-        sandbox_failure_point: "release";
-        moves: [{ key: "claim"; operation: internal_transfer.post; bind: { amount: { from: input; path: claim_field; }; currency: { from: instance; path: fields.currency; }; postMode: { from: const; value: partial_only; }; transferId: { from: instance; path: refs.holdTransferId; }; }; }, { key: remainder; operation: internal_transfer.void; bind: { reason: { from: const; value: "Return unclaimed deposit remainder"; }; transferId: { from: instance; path: refs.holdTransferId; }; }; }];
-      }
-      when(claim_input) { input: claim_input; }
-      when(claim_allowed) { port { allowed_parties: claim_allowed; }; }
-      when_not(claim_allowed) {
-        when(claim_to) { port { allowed_parties: [claim_to]; }; }
-      }
-      steps: [];
-      summary: "Claim the security deposit";
-    }
-    action return {
-      agent_description: "Void the whole reservation so the {payer} gets every unit back. Use this when the {holder} decides to keep nothing. This moves money and does not reverse. Only a funded hold returns.";
-      deadline: { field: deadline_field; };
-      when(return_allowed) { port { allowed_parties: return_allowed; }; }
-      when_not(return_allowed) {
-        when(return_to) { port { allowed_parties: [return_to]; }; }
-      }
-      moves: [{ key: "return"; operation: internal_transfer.void; bind: { reason: { from: const; value: "Deposit returned in full"; }; transferId: { from: instance; path: refs.holdTransferId; }; }; }];
-      steps: [];
-      summary: "Return the security deposit";
-    }
-    action expire {
-      due: { field: deadline_field; };
-      moves: [{ key: expire; operation: internal_transfer.void; bind: { reason: { from: const; value: "Deposit hold expired"; }; transferId: { from: instance; path: refs.holdTransferId; }; }; }];
-      steps: [];
-      summary: "Expire the security deposit";
-    }
-    action cancel {
-      agent_description: "Close a hold before anyone funds it. No money has moved, so this is a lifecycle transition only. Only a created hold cancels. A funded hold refuses, because its money is already reserved. Claim it or return it instead.";
-      moves: [];
-      steps: [];
-      summary: "Cancel the security deposit";
-    }
-  }
-}

package/std/money_flows/settlement_batch.hsx

@@ -1,173 +0,0 @@
-module std.money_flows.settlement_batch
-
-// Periodic aggregation of capture lineage, fee entries, and adjustments into a single net calculated payout.
-//
-// ### Purpose
-// `settlement_batch` settles merchant balances, marketplace vendor earnings, and partner clearing accounts.
-// Individual payment captures, platform fees, and reversal adjustments accumulate into an open batch over a period.
-// On `close_trigger`, the batch freezes. The platform calculates the signed net payable from gross captures plus credit
-// adjustments minus debit adjustments. If positive, an outbound bank payout is instructed and acknowledged.
-//
-// ### Selection guidance
-// - vs `reconciled_payout`: `settlement_batch` aggregates multiple transactions and adjustments over a billing cycle
-//   to compute a single net payable. `reconciled_payout` manages bank instruction dispatch and statement line reconciliation
-//   for an individual payout amount.
-// - vs `weighted_distribution`: `settlement_batch` consolidates many inbound transactions into one net outbound payout.
-//   `weighted_distribution` splits one funding pool into many recipient payouts.
-//
-// ### Parameters
-// - `settlement_account`: The source clearing account holding captured funds and paying the batch.
-// - `source_capture_refs`: Binding name for gross capture references included in the batch.
-// - `fee_entries`: Binding name for fee deductions applied to the batch.
-// - `external_reversal_offsets`: Binding name for reversal adjustments applied to the batch.
-// - `close_trigger`: Date when the batch closes and ceases accepting new transaction entries.
-// - `payout_destination`: The merchant or partner account receiving the net payout.
-// - `negative_position`: Policy when calculated net payable is zero or negative (`reject`).
-// - `payout_acknowledgement`: Condition port confirming bank receipt of the payout.
-// - `payout_beneficiary_ref`: Beneficiary identifier for external bank dispatch.
-//
-// ### Decision ports
-// - `payout_acknowledgement`: Port recording external bank or partner receipt confirmation.
-//
-// ### Example
-// ```hsx
-// program settlement_batch_example "Settlement batch example"
-// import { settlement_batch } from "std/money_flows"
-// party settlement_account: business
-// party payout_destination: business
-// settlement batch = settlement_batch {
-//   settlement_account: settlement_account
-//   source_capture_refs: captureReference
-//   fee_entries: feeReference
-//   external_reversal_offsets: reversalReference
-//   close_trigger: closeAt
-//   payout_destination: payout_destination
-//   negative_position: reject
-//   payout_acknowledgement: port acknowledge_payout
-//   payout_beneficiary_ref: payoutBeneficiaryId
-// }
-// port acknowledge_payout {
-//   allowed: [payout_destination]
-//   shape: { acknowledgementReference: text }
-// }
-// ```
-export instrument settlement_batch<C>(
-  settlement_account: party,
-  source_capture_refs: text,
-  fee_entries: text,
-  external_reversal_offsets: text,
-  close_trigger: date,
-  payout_destination: party,
-  negative_position: text,
-  payout_acknowledgement: condition,
-  payout_beneficiary_ref: text,
-) {
-  fields {
-    close_trigger { type: date; description: "Date the open batch freezes against later entries"; }
-    currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-    payout_beneficiary_ref { type: text; description: "Beneficiary ID for the payout instruction"; pattern: "^ben_(sandbox|live)_[a-z0-9]{8,64}$"; }
-    [payout_destination]AccountId { type: account<C>; description: concat("The ", words(payout_destination), " account"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-    [settlement_account]AccountId { type: account<C>; description: concat("The ", words(settlement_account), " account"); "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; }; }
-  }
-  lifecycle {
-    states open closed calculated approved instructed acknowledged reconciled;
-    initial open;
-    on close: open -> closed;
-    on calculate: closed -> calculated;
-    on approve: calculated -> approved;
-    on instruct: approved -> instructed;
-    on [payout_acknowledgement]: instructed -> acknowledged;
-    on reconcile: instructed|acknowledged -> reconciled;
-  }
-  parties { beneficiary: concat(camel(payout_destination), "AccountId"); payer: concat(camel(settlement_account), "AccountId"); }
-  required: [concat(camel(payout_destination), "AccountId"), concat(camel(settlement_account), "AccountId"), close_trigger, currency, payout_beneficiary_ref];
-  title: sentence(instrument);
-  id_prefix: prefix(instrument);
-  agent_description: "Reach for settlement batch when many charges over a period roll up into one payout. Capture entries and adjustments accrue against an open batch, the batch freezes on its close date, calculate proves one signed net payable, and instruct sends a single external payout. Weighted distribution goes the other way, one amount out to many recipients.";
-  summary: concat("Payout batch from ", words(settlement_account), " to ", words(payout_destination));
-  description: "Immutable batch of capture lineage and signed adjustments that creates one payout";
-  action create { agent_description: "Open a batch that capture entries and adjustments can accrue into. No money moves. The batch keeps taking entries until its close date freezes it."; summary: concat("Open a ", words(instrument)); moves: []; steps: []; }
-  action close { summary: "Freeze the batch and stop all new entries"; due { field: close_trigger; } moves: []; steps: []; }
-  action calculate {
-    agent_description: "Prove and freeze the one net payable from gross captures plus credit adjustments minus debit adjustments. The batch must be closed first. A zero or negative net is refused, so a batch in deficit never reaches a payout. No money moves.";
-    summary: "Prove and freeze the one signed net payable amount";
-    computes signed_sum {
-      amountRef: netPayable; onNegative: refuse; onZero: refuse;
-      sources: [
-        { amountField: amount; instrumentId: concat(instrument, "_capture_entry"); refField: concat(camel(instrument), "Id"); sign: add; statuses: [accrued]; subtotalRef: grossCaptureAmount; },
-        { amountField: amount; instrumentId: concat(instrument, "_credit_adjustment"); refField: concat(camel(instrument), "Id"); sign: add; statuses: [applied]; subtotalRef: creditAdjustmentAmount; },
-        { amountField: amount; instrumentId: concat(instrument, "_debit_adjustment"); refField: concat(camel(instrument), "Id"); sign: subtract; statuses: [applied]; subtotalRef: debitAdjustmentAmount; },
-      ];
-    }
-    moves: []; steps: [];
-  }
-  action approve { agent_description: "Sign off on the frozen net payable. The batch must already be calculated. Nothing is recomputed and no money moves. This is the gate instruct waits on."; summary: "Approve the frozen payable without recomputing it"; moves: []; steps: []; }
-  action instruct {
-    agent_description: "Create one external payout for the frozen net payable, drawn on the settlement account and sent to the stored beneficiary. The batch must be approved. This moves money off the platform and is idempotent, so a retry never pays twice.";
-    summary: "Create one idempotent payout from the frozen net payable";
-    payout { amount: "refs.netPayable"; beneficiaryField: payout_beneficiary_ref; beneficiaryPartyField: concat(camel(payout_destination), "AccountId"); capture: payoutId; currencyField: currency; sourceAccountField: concat(camel(settlement_account), "AccountId"); speed: standard; }
-    moves: []; steps: [];
-  }
-  action [payout_acknowledgement] {
-    agent_description: "Record the beneficiary confirmation that the payout landed, with the reference kept in the receipt. The batch must already be instructed. Only the payout destination may call it. No money moves.";
-    summary: "Record the tenant's payout acknowledgement in the receipt";
-    port { allowedParties: [beneficiary]; }
-    input { type: object; properties: { acknowledgementReference: { type: string; description: "Required decision reference retained in the operation receipt"; minLength: 1; maxLength: 180; }; }; required: [acknowledgementReference]; additionalProperties: false; }
-    capture_input { acknowledgementReference: acknowledgementReference; }
-    moves: []; steps: [];
-  }
-  action reconcile {
-    summary: "Match durable evidence that the payout settled";
-    due { field: close_trigger; offset: "P30D"; }
-    reconcile {
-      amount: "refs.netPayable"; capture: settlementEvidenceId; counterpartyRef: payoutId;
-      currencyField: currency; direction: debit; evidence: statement_line;
-      exception { amountField: amount; childInstrumentId: concat(instrument, "_debit_adjustment"); maxOpen: 1; reasonField: adjustmentReference; refField: concat(camel(instrument), "Id"); }
-      match { law: exact; }
-      within { offset: "P30D"; }
-    }
-    moves: []; steps: [];
-  }
-  instruments {
-    instrument {
-      let(parent_name): instrument;
-      id: concat(parent_name, "_capture_entry");
-      id_prefix: concat(prefix(parent_name), "ce");
-      fields {
-        amount { type: money<C>; description: "Gross captured amount in minor units"; }
-        [source_capture_refs] { type: text; description: "Immutable source capture reference"; minLength: 1; maxLength: 180; }
-        currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-        [parent_name]Id { type: ref<parent_name>; description: "Open batch this capture entry accrues into"; pattern: concat("^", prefix(parent_name), "_(sandbox|live)_[a-z0-9]{8,64}$"); }
-      }
-      lifecycle { states created accrued; initial created; on accrue: created -> accrued; }
-      required: [amount, currency, concat(camel(parent_name), "Id"), source_capture_refs];
-      agent_description: "One gross capture that belongs to an open batch. Record one per source capture so the net payable keeps its lineage back to the original charge.";
-      title: concat(sentence(parent_name), " Capture Entry"); summary: "Gross capture lineage entry"; description: "One gross capture entry linked to an open payout batch";
-      action create { agent_description: "Record one capture with its source reference against an open batch. The batch must be open and share the currency. No money moves, and the entry counts toward the net payable only once it accrues."; summary: "Create a capture lineage entry on an open batch"; requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
-      action accrue { agent_description: "Count this capture toward the batch gross total. The entry must be created and its batch still open, because a closed batch admits nothing new. No money moves."; summary: "Accrue the capture entry into the open batch"; requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
-    }
-    for adjustment_kind in [credit, debit] {
-      instrument {
-        let(parent_name): instrument;
-        id: concat(parent_name, "_", adjustment_kind, "_adjustment");
-        id_prefix: concat(prefix(parent_name), if_eq(adjustment_kind, "credit", "ca", "da"));
-        fields {
-          adjustmentReference { type: text; description: "Immutable explicit adjustment reference"; minLength: 1; maxLength: 180; }
-          amount { type: money<C>; description: concat(title(adjustment_kind), " adjustment amount in minor units"); }
-          [source_capture_refs] { type: text; description: "Original capture reference that this adjustment corrects"; minLength: 1; maxLength: 180; }
-          currency { type: text; description: "ISO 4217 currency code"; minLength: 3; maxLength: 3; pattern: "^[A-Z]{3}$"; }
-          [external_reversal_offsets] { type: text; description: "Optional externally decided reversal reference"; minLength: 1; maxLength: 180; optional: true; }
-          [fee_entries] { type: text; description: "Optional fee entry reference"; minLength: 1; maxLength: 180; optional: true; }
-          [parent_name]Id { type: ref<parent_name>; description: "Open batch this adjustment applies to"; pattern: concat("^", prefix(parent_name), "_(sandbox|live)_[a-z0-9]{8,64}$"); }
-        }
-        lifecycle { states created applied; initial created; on adjust: created -> applied; on correct: created -> applied; }
-        required: [amount, currency, adjustmentReference, concat(camel(parent_name), "Id"), source_capture_refs];
-        agent_description: concat("One ", adjustment_kind, " adjustment against an open batch, carrying the capture reference it corrects. Credit adjustments add to the net payable and debit adjustments subtract from it, so a late correction lands on the current open batch instead of reopening a closed one.");
-        title: concat(sentence(parent_name), " ", title(adjustment_kind), " Adjustment"); summary: concat(title(adjustment_kind), " adjustment with capture lineage"); description: concat("One ", adjustment_kind, " adjustment linked to an open payout batch; closed batches stay unchanged");
-        action create { agent_description: concat("Record a ", adjustment_kind, " adjustment on an open batch, naming the capture reference it corrects. The batch must be open and share the currency. No money moves, and the adjustment counts only once it is applied."); summary: concat("Create a ", adjustment_kind, " adjustment on an open batch"); requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
-        action adjust { agent_description: concat("Apply the ", adjustment_kind, " adjustment so calculate counts it. The adjustment must be created and its batch still open. No money moves. The effect shows up in the batch net payable."); summary: concat("Apply the ", adjustment_kind, " adjustment to the open batch"); requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
-        action correct { agent_description: "Apply this adjustment as a correction on the open batch it names. Use it when the batch carrying the original entry has already closed, because a closed batch never changes. The adjustment must be created and no money moves."; summary: "Record a later correction on this open batch instead of changing the closed source batch"; requires refs { field: concat(camel(parent_name), "Id"); statuses: [open]; match: { "fields.currency": "fields.currency"; }; } moves: []; steps: []; }
-      }
-    }
-  }
-}