@hyperscale0/hsx 1.0.222 → 1.0.235

package/examples/lending.hsx

@@ -1,57 +1,83 @@
-// A lending composition with limit approvals, wallet commitments and cash distribution transitions.
-program community_business_lending "Community business lending"
+// Qassim bakery funding raises 30,000 SAR for ovens from investors who commit at least 1,000 SAR each.
+// An unclosed round refunds its wallets at expiry; funded loans distribute repayments or record investor losses.
+program community_business_lending "Qassim bakery funding"
 use lending
 use financing
 use wallet
 
-object business "Business funding" {
+// Set price to 30,000 SAR. The bakery owns the record; investors act as actor.
+// Company fee: 5% of collected profit, with 15% VAT on that fee, at distribution.
+// Principal and wallet loads have fee 0% and tax 0%; no service is sold there.
+object business "Bakery oven funding" {
   fields { businessName: text, purpose: text, price: money }
-  columns: [businessName, purpose, price]
+  columns: [businessName, purpose, price, fundingClosesAt]
   attach allowance = financing.limits {
-    expose create as create_allowance
     borrower: owner, per_borrower: 100000 SAR
+    expose create as request_bakery_limit
     expose approve as approve_borrower
   }
   attach budget = financing.portfolio_limit {
-    expose create as create_budget
     limit: 2000000 SAR
+    expose create as create_funding_budget
     expose approve as approve_budget
   }
+  // Twelve future monthly dates, 6% annual profit on the declining balance.
+  // Close the fully subscribed round before separately disbursing the loan.
   attach loan = financing.installments {
-    expose create as create_loan
-    borrower: owner, capital: operator
+    borrower: owner, capital: operator, share: 0%
     months: 12, pricing: amortizing, profit_rate: 6%, disburse_to: borrower
+    payoff_rebate: 100%, refund_within: 30d, write_off_after: 90d
     limits: allowance, portfolio: budget
+    expose create as quote_bakery_loan
     expose sign as sign_loan
     expose disburse as release_loan
+    expose cancel as decline_loan_quote
+    expose void as cancel_unfunded_loan
     expose payoff as repay_early
+    expose complete as close_repaid_loan
   }
   attach investor_balance = wallet.balance {
+    holder: actor, spend_limit: 7500 SAR, topup_fee: 0%
     expose create as create_investor_balance
-    holder: actor
     expose activate as open_wallet
     expose topup as add_funds
+    expose withdraw as withdraw_available_funds
+    expose close as close_empty_wallet
   }
   attach funding = lending.round {
-    borrower: owner, plan: loan
-    expose create as open_funding
-    expose close as close_funding
+    borrower: owner, plan: loan, minimum_ticket: 1000 SAR, investor_cap: 25%
+    rename { closesAt: fundingClosesAt }
+    expose create as open_funding_round
+    expose close as close_fully_funded_round
   }
   attach investment = lending.commitment {
     round: funding, wallet: investor_balance, investor: actor
-    expose create as invest
-    expose withdraw as withdraw_investment
+    expose create as commit_investment
+    expose withdraw as withdraw_before_close
   }
+  // For each recorded cash settlement, prepare once and create one share per
+  // funded commitment. The fee applies to profit, never returned principal.
   attach returns = lending.distribution {
-    expose create as create_returns
-    round: funding, receipt: loan.settlement
-    expose prepare_cash as prepare_returns
-    expose distribute_cash as distribute_returns
+    round: funding, receipt: loan.settlement, mode: cash, fee: 5%, tax: 15%
+    expose create as record_cash_settlement
+    expose prepare_cash as calculate_investor_returns
+    expose distribute_cash as pay_investor_wallets
+  }
+  // Loss distribution moves claims only. It does not debit another cash fee.
+  attach losses = lending.distribution {
+    round: funding, receipt: loan.settlement, mode: loss, fee: 0%, tax: 0%
+    expose create as record_loss_settlement
+    expose prepare_loss as calculate_investor_losses
+    expose distribute_loss as allocate_investor_losses
   }
 }
 
-expose business.loan.payment.create as create_payment
+expose business.loan.payment.create as record_repayment
 expose business.loan.payment.pay as pay_instalment
-expose business.loan.payment.refund as refund_payment
+expose business.loan.payment.refund as refund_mistaken_repayment
 expose business.loan.payoff_quote.create as request_payoff_quote
+expose business.loan.write_off_request.create as request_overdue_write_off
+expose business.loan.write_off_request.apply as approve_overdue_write_off
+expose business.loan.write_off_request.cancel as cancel_write_off_request
 expose business.returns.share.create as create_return_share
+expose business.losses.share.create as create_loss_share

package/examples/library.hsx

@@ -1,15 +1,71 @@
-// A minimal financed car sale connects escrow to a three-instalment plan and lending limits.
-program cars "Financed car sales"
+// Riyadh used van finance funds a 34,500 SAR van over three monthly instalments.
+// The dealer is paid after delivery and acceptance; a verified return unwinds financing before the buyer gets a refund.
+program cars "Riyadh used van finance"
 use escrow
 use financing
-object car "Cars" {
- fields { make: text, model: text, year: integer }
- attach sale = escrow.hold { expose create as create_sale, payer: actor, payee: owner, expose fund as sell }
- attach limits = financing.limits { expose create as create_limits, borrower: actor, per_borrower: 60000 SAR }
- attach ceiling = financing.portfolio_limit { expose create as create_ceiling, limit: 1500000 SAR }
- attach plan = financing.installments {
-  borrower: actor, capital: operator, share: 25%
-  months: 3, pricing: flat_total, profit_rate: 2.5%, funds: sale, limits: limits, portfolio: ceiling
-  expose create as finance
- }
+party dealer: business
+
+// Bind dealer to the vehicle seller. Set price to its gross 34,500 SAR invoice;
+// vehicle VAT stays on that invoice. The platform fee is 2% plus 15% VAT
+// on the fee: 690 SAR and 103.50 SAR. The dealer receives 33,706.50 SAR.
+object car "Financed van purchase" {
+  fields { make: text, model: text, year: integer, vin: text, price: money }
+  columns: [make, model, year, vin, price]
+  attach sale = escrow.hold {
+    payer: actor, payee: dealer
+    fee: { seller: 2%, tax: 15% }
+    deliver_within: 7d, accept_within: 3d
+    expose create as agree_van_purchase
+    expose fund as pay_cash_instead
+    expose deliver as confirm_van_delivery
+    expose accept as accept_van
+    expose dispute as dispute_van_condition
+    expose verify_return as verify_returned_van
+    expose refund as refund_buyer_after_unwind
+    expose refund_undelivered as refund_undelivered_cash_purchase
+    expose settle_release as resolve_for_dealer
+    expose settle_return as resolve_for_buyer
+    expose settle_refund as finish_buyer_refund
+    expose cancel as cancel_unfunded_purchase
+  }
+  // Limits are shared across purchases. Approve each once before disbursement.
+  attach limits = financing.limits {
+    borrower: actor, per_borrower: 60000 SAR
+    expose create as request_borrower_limit
+    expose approve as approve_borrower_limit
+  }
+  attach ceiling = financing.portfolio_limit {
+    limit: 1500000 SAR
+    expose create as create_lending_budget
+    expose approve as approve_lending_budget
+  }
+  // At 34,500 SAR, 2.5% flat profit is 862.50 SAR for the whole term.
+  // Financing fee: 0%, tax: 0% on principal; no separate financing service fee.
+  // Supply three future monthly dates and a unique settlementIdentity.
+  attach plan = financing.installments {
+    borrower: actor, capital: operator, share: 0%
+    months: 3, pricing: flat_total, profit_rate: 2.5%
+    funds: sale, limits: limits, portfolio: ceiling
+    returned_goods: refund_all, refund_within: 30d, write_off_after: 90d
+    expose create as finance
+    expose sign as sign_finance_agreement
+    expose disburse as fund_van_escrow
+    expose cancel as decline_finance_quote
+    expose void as cancel_signed_finance
+    expose payoff as repay_early
+    expose complete as close_repaid_finance
+    // Refund paid instalments before unwinding an active plan. Then refund
+    // the escrow remainder. A live plan blocks the escrow's direct refund.
+    expose unwind as unwind_returned_van_finance
+    expose unwind_undelivered as unwind_missing_van_finance
+    expose unwind_paid as unwind_repaid_van_finance
+  }
 }
+
+expose car.plan.payment.create as record_repayment
+expose car.plan.payment.pay as pay_instalment
+expose car.plan.payment.refund as refund_mistaken_repayment
+expose car.plan.payoff_quote.create as request_payoff_quote
+expose car.plan.write_off_request.create as request_overdue_write_off
+expose car.plan.write_off_request.apply as approve_overdue_write_off
+expose car.plan.write_off_request.cancel as cancel_write_off_request

package/examples/marketplace.hsx

@@ -1,34 +1,49 @@
-// Freelancers publish offers and clients place orders with funds held until work is accepted.
-program freelance_marketplace "Freelance marketplace"
+// Riyadh design market sells a 2,000 SAR restaurant menu project with delivery in seven days.
+// The company keeps 10% plus 15% VAT on its fee; the designer receives 1,770 SAR after client acceptance.
+program freelance_marketplace "Riyadh design market"
 use marketplace
 use escrow
+party designer: business
 
-object project "Project" {
+// Bind designer to the design studio. The client owns the project record.
+// Set price to 2,000 SAR and use the same field for offer, order and escrow.
+// Any VAT on the designer's work belongs on its own invoice.
+object project "Menu design project" {
   fields { brief: text, deliverable: text, price: money }
   columns: [brief, deliverable, price]
   attach offer = marketplace.listing {
-    rename { price: price }
-    expose create as create_offer
-    seller: owner
+    seller: designer
+    rename { title: deliverable, price: price }
+    expose create as draft_offer
     expose publish as publish_offer
     expose withdraw as withdraw_offer
+    expose sell as close_sold_offer
   }
   attach order = marketplace.order {
+    listing: offer, buyer: owner, fulfiller: designer
     rename { price: price }
-    expose create as create_order
-    listing: offer, buyer: actor, fulfiller: owner
+    expose create as request_design
     expose commit as place_order
     expose fulfill as finish_order
+    expose cancel as cancel_order
   }
+  // Finishing the order does not release money. Run the payment actions too.
   attach payment = escrow.hold {
+    payer: owner, payee: designer
+    fee: { seller: 10%, tax: 15% }
+    deliver_within: 7d, accept_within: 3d
+    dispute: { refund_after: return_verified }
     expose create as create_payment
-    payer: actor, payee: owner
     expose fund as fund_project
     expose deliver as submit_work
     expose accept as accept_work
     expose dispute as dispute_work
-    expose verify_return as verify_return
+    expose verify_return as verify_rejected_work
     expose refund as refund_client
-    expose cancel as cancel_payment
+    expose refund_undelivered as refund_missed_delivery
+    expose settle_release as resolve_for_designer
+    expose settle_return as resolve_for_client
+    expose settle_refund as finish_client_refund
+    expose cancel as cancel_unpaid_project
   }
 }

package/examples/money.hsx

@@ -1,19 +1,54 @@
-// A tutoring studio collects a fixed fee for each lesson and can cancel unpaid bookings.
-program tutoring_studio "Tutoring studio"
+// Riyadh tutoring studio charges 172.50 SAR for a private Arabic lesson.
+// A paid booking can be refunded before the lesson or if the tutor cannot teach.
+program tutoring_studio "Riyadh tutoring studio"
 use money
 
-object lesson "Lesson" {
-  fields {
-    student: text
-    tutor: text
-    startsAt: date
+// The customer is the object's owner. Fee: 0% on top of the lesson price.
+// The studio invoices 150 SAR plus 15% VAT, 22.50 SAR, outside this transfer.
+// money.transfer sends the gross price to the studio without splitting VAT.
+instrument lesson_booking(payment: ref<money.transfer>, student: party) {
+  summary: "Confirm a paid lesson, record teaching or refund the student."
+  fields { payment: ref<payment>, startsAt: date }
+  lifecycle { states: [booked, taught, refunded], initial: booked }
+  action create {
+    actor: { party: student }
+    requires self.payment in [paid]
+    requires unique "paid_lesson" on [self.payment]
+    requires self.startsAt > self.now
   }
+  action teach {
+    from: booked, to: taught, actor: { party: programOperator }
+    due: { at: self.startsAt }
+    subject { lessonNotes: text }
+  }
+  action cancel {
+    from: booked, to: refunded, actor: { party: student }
+    deadline: { at: self.startsAt }
+    moves self.payment.amount from programOperator to student
+  }
+  action tutor_unavailable {
+    from: booked, to: refunded, actor: { party: programOperator }
+    subject { cancellationReason: text }
+    moves self.payment.amount from programOperator to student
+  }
+}
+
+object lesson "Arabic lesson" {
+  fields { student: text, tutor: text, startsAt: date }
   columns: [student, tutor, startsAt]
   attach payment = money.transfer {
+    payer: owner, payee: operator, amount: 172.50 SAR
+    economics pay { purpose: earning, sourceParty: owner }
     expose create as create_payment
-    payer: actor, payee: operator, amount: 150 SAR
-    economics pay { purpose: earning, sourceParty: actor }
     expose pay as pay_for_lesson
-    expose cancel as cancel_payment
+    expose cancel as cancel_unpaid_lesson
+  }
+  attach booking = lesson_booking {
+    payment: payment, student: owner
+    rename { startsAt: startsAt }
+    expose create as confirm_paid_lesson
+    expose teach as record_lesson_taught
+    expose cancel as cancel_and_refund_lesson
+    expose tutor_unavailable as refund_cancelled_lesson
   }
 }

package/examples/rental-deposit.hsx

@@ -1,16 +1,19 @@
-// A business rents equipment with a 1,000 riyal deposit and a single 50 riyal late fee.
-// On-time return refunds 1,000 riyals; late return pays the operator 50 riyals and refunds 950 riyals.
-program equipment_rental "Equipment rental"
+// Dammam equipment hire holds a 1,000 SAR deposit for a business renter.
+// Return the deposit in full, or deduct a single 50 SAR late charge plus 7.50 SAR VAT.
+program equipment_rental "Dammam equipment hire"
 party renter: business
 
-// The renter is one declared business, so this instrument takes no parameters.
+// Bind renter to the business hiring the equipment. The deposit has fee 0%
+// and tax 0% because it stays refundable principal. The late service has 15% VAT.
 instrument deposit {
-  summary: "Hold a rental deposit, then return it less any fixed late fee."
+  summary: "Hold security until return, with one disclosed late charge."
   fields {
     renter: account of renter
     held: account of self
     amount: money = 1000 SAR
     lateFee: money = 50 SAR
+    lateTax: money = rate(self.lateFee, 15%)
+    startsAt: date
     dueAt: date
     refund: money?
   }
@@ -18,10 +21,12 @@ instrument deposit {
   action create {
     actor: { party: renter }
     requires self.dueAt > self.now
+    requires self.startsAt > self.now
+    requires self.dueAt > self.startsAt
   }
   action fund {
     from: pending, to: funded, actor: { party: renter }
-    deadline: { at: self.dueAt }
+    deadline: { at: self.startsAt }
     moves self.amount from self.renter to self.held
   }
   action return_on_time {
@@ -34,24 +39,30 @@ instrument deposit {
     from: funded, to: returned, actor: { party: programOperator }
     due: { at: self.dueAt }
     subject { returnReference: text }
-    calculate: [{ target: refund, op: subtract, base: { field: self.held.balance }, subtract: [{ field: self.lateFee }] }]
+    calculate: [{ target: refund, op: subtract, base: { field: self.held.balance }, subtract: [{ field: self.lateFee }, { field: self.lateTax }] }]
     moves self.lateFee from self.held to programOperator
+    moves self.lateTax from self.held to programTax
     moves self.refund from self.held to self.renter
   }
+  action refund_before_pickup {
+    from: funded, to: cancelled, actor: { party: renter }
+    deadline: { at: self.startsAt }
+    moves self.held.balance from self.held to self.renter
+  }
   action cancel { from: pending, to: cancelled, actor: { party: renter } }
 }
 
-object rental "Equipment rental" {
-  fields { equipment: text }
-  columns: [equipment, dueAt]
+object rental "Equipment deposit" {
+  fields { equipment: text, serialNumber: text, renterName: text }
+  columns: [equipment, serialNumber, renterName, startsAt, dueAt]
   attach security = deposit {
-    // dueAt is a column, so it stays shared object metadata.
-    rename { dueAt: dueAt }
+    rename { startsAt: startsAt, dueAt: dueAt }
     expose create as agree_rental
     expose fund as pay_deposit
     expose return_on_time as return_equipment
     expose return_late as return_equipment_late
-    expose cancel as cancel_rental
+    expose refund_before_pickup as cancel_before_pickup
+    expose cancel as cancel_unpaid_rental
   }
 }
 
@@ -59,4 +70,5 @@ hide deposit.create
 hide deposit.fund
 hide deposit.return_on_time
 hide deposit.return_late
+hide deposit.refund_before_pickup
 hide deposit.cancel

package/examples/repair-approval.hsx

@@ -1,44 +1,88 @@
-// A repair shop records inspection and approval evidence before it can complete a job.
-program repair_shop "Repair approvals"
+// Jeddah phone repair quotes 350 SAR plus 52.50 SAR VAT for a screen replacement.
+// The customer approves and funds the repair; acceptance pays the shop, while a failed repair returns all 402.50 SAR.
+program repair_shop "Jeddah phone repair"
 
-instrument assessment {
-  summary: "Inspect the repair, collect approval, then record completion."
-  fields { inspectedAt: date?, approvedAt: date? }
-  lifecycle { states: [submitted, inspected, approved, completed, rejected], initial: submitted }
-  action create {}
+// Fee: 0% beyond the repair price. The shop keeps 350 SAR and posts 15% VAT.
+instrument assessment(customer: party) {
+  summary: "Inspect, approve, hold payment and settle a screen repair."
+  fields {
+    held: account of self
+    price: money = 350 SAR
+    vat: money = rate(self.price, 15%)
+    total: money = sum(self.price, self.vat)
+    quoteExpiresAt: date
+    repairDueAt: date
+    inspectedAt: date?
+    approvedAt: date?
+  }
+  lifecycle { states: [submitted, inspected, approved, ready_for_collection, disputed, completed, refunded, rejected, expired], initial: submitted }
+  action create {
+    actor: { party: customer }
+    requires self.quoteExpiresAt > self.now
+    requires self.repairDueAt > self.quoteExpiresAt
+  }
   action inspect {
     from: submitted, to: inspected, actor: { party: programOperator }
+    deadline: { at: self.quoteExpiresAt }
     subject { inspectionNotes: text }
     set: { inspectedAt: { field: self.now } }
   }
   action approve {
-    from: inspected, to: approved, actor: { party: programOperator }
+    from: inspected, to: approved, actor: { party: customer }
+    deadline: { at: self.quoteExpiresAt }
     subject { approvalReference: text }
     set: { approvedAt: { field: self.now } }
+    moves self.total from customer to self.held
   }
-  action reject {
-    from: inspected, to: rejected, actor: { party: programOperator }
-  }
+  action reject { from: [submitted, inspected], to: rejected, actor: { party: customer } }
+  action expire { from: [submitted, inspected], to: expired, actor: clock, due: { at: self.quoteExpiresAt } }
   action complete {
-    from: approved, to: completed, actor: { party: programOperator }
+    from: approved, to: ready_for_collection, actor: { party: programOperator }
+    deadline: { at: self.repairDueAt }
     subject { completionNotes: text }
   }
+  action accept {
+    from: ready_for_collection, to: completed, actor: { party: customer }
+    moves self.price from self.held to programOperator
+    moves self.vat from self.held to programTax
+  }
+  action dispute {
+    from: ready_for_collection, to: disputed, actor: { party: customer }
+    subject { faultDescription: text }
+  }
+  action refund {
+    from: [approved, ready_for_collection, disputed], to: refunded, actor: { party: programOperator }
+    subject { refundReason: text }
+    moves self.held.balance from self.held to customer
+  }
+  action refund_overdue {
+    from: approved, to: refunded, actor: { party: customer }
+    due: { at: self.repairDueAt }
+    moves self.held.balance from self.held to customer
+  }
+  action accept_resolution {
+    from: disputed, to: completed, actor: { party: customer }
+    subject { resolutionReference: text }
+    moves self.price from self.held to programOperator
+    moves self.vat from self.held to programTax
+  }
 }
 
-object repair "Repair" {
-  fields { item: text, problem: text }
-  columns: [item, problem]
+object repair "Screen repair" {
+  fields { item: text, serialNumber: text, problem: text }
+  columns: [item, serialNumber, problem, quoteExpiresAt, repairDueAt]
   attach review = assessment {
-    expose create as create_review
+    customer: owner
+    rename { quoteExpiresAt: quoteExpiresAt, repairDueAt: repairDueAt }
+    expose create as request_repair
     expose inspect as inspect_repair
-    expose approve as approve_repair
-    expose reject as reject_repair
-    expose complete as complete_repair
+    expose approve as approve_and_pay
+    expose reject as decline_quote
+    expose complete as mark_ready_for_collection
+    expose accept as accept_repair
+    expose dispute as report_failed_repair
+    expose refund as refund_repair
+    expose refund_overdue as refund_missed_deadline
+    expose accept_resolution as accept_repair_resolution
   }
 }
-
-hide assessment.create
-hide assessment.inspect
-hide assessment.approve
-hide assessment.reject
-hide assessment.complete

package/examples/reporting.hsx

@@ -1,28 +1,54 @@
-// An equipment lender keeps an ageing report over its financed purchases and recorded repayments.
-program equipment_loan_reports "Equipment loan reports"
+// Tabuk workshop equipment finance lends 46,000 SAR and reports monthly repayments and arrears.
+// Ageing bands at 30, 60 and 90 days distinguish overdue balances from loans written off after 90 days.
+program equipment_loan_reports "Tabuk workshop equipment finance"
 use reporting
 use financing
 
-object purchase "Equipment loan" {
-  fields { businessName: text, equipment: text, price: money }
-  columns: [businessName, equipment, price]
+// Set price to 46,000 SAR, the workshop's 40,000 SAR equipment invoice plus
+// 15% VAT charged by its supplier outside this loan. Profit is 6% annually on
+// the declining balance. Loan fee: 0%, tax: 0% on principal repayments.
+// Reports have no customer fee or tax; they are the lender's internal records.
+object purchase "Workshop equipment loan" {
+  fields { businessName: text, equipment: text, invoiceReference: text, price: money }
+  columns: [businessName, equipment, invoiceReference, price]
   attach allowance = financing.limits {
-    expose create as create_allowance
     borrower: owner, per_borrower: 200000 SAR
+    expose create as request_workshop_limit
     expose approve as approve_business
   }
   attach budget = financing.portfolio_limit {
-    expose create as create_budget
     limit: 5000000 SAR
+    expose create as create_lending_budget
     expose approve as approve_budget
   }
+  // Create twelve future monthly dates and approve both limits before funding.
   attach loan = financing.installments {
-    expose create as create_loan
-    borrower: owner, capital: operator
+    borrower: owner, capital: operator, share: 0%
     months: 12, pricing: amortizing, profit_rate: 6%, disburse_to: borrower
+    payoff_rebate: 100%, refund_within: 30d, write_off_after: 90d
     limits: allowance, portfolio: budget
+    expose create as quote_equipment_loan
     expose sign as sign_purchase_loan
     expose disburse as fund_purchase
+    expose cancel as decline_loan_quote
+    expose void as cancel_unfunded_loan
+    expose payoff as repay_early
+    expose complete as close_repaid_loan
+  }
+  // Report requests use reporting routes. This attachment declares their
+  // datasets and retention; it neither collects money nor sends a reminder.
+  attach reports = reporting.portfolio {
+    on: loan, default_days: 90, retention_years: 10
+    aging_first_days: 30, aging_second_days: 60, aging_third_days: 90
+    expose create as enable_portfolio_reports
   }
-  attach reports = reporting.portfolio { expose create as create_reports, on: loan }
 }
+
+expose purchase.loan.payment.create as record_repayment
+expose purchase.loan.payment.pay as pay_instalment
+expose purchase.loan.payment.refund as refund_mistaken_repayment
+expose purchase.loan.payoff_quote.create as request_payoff_quote
+// Write-off is a capital decision, not an automatic consequence of a report.
+expose purchase.loan.write_off_request.create as request_overdue_write_off
+expose purchase.loan.write_off_request.apply as approve_overdue_write_off
+expose purchase.loan.write_off_request.cancel as cancel_write_off_request

package/examples/savings.hsx

@@ -1,21 +1,31 @@
-// Six members contribute to a shared pot and receive it in their agreed calendar order.
-program neighbourhood_savings "Savings circle"
+// Al Khobar shopkeepers circle collects 500 SAR from each of six members every month.
+// Each member receives one 3,000 SAR pot in order; missed contributions remain payable and an unfunded pot waits.
+program neighbourhood_savings "Al Khobar shopkeepers circle"
 use savings
 
-object group "Savings group" {
+// Fee: 0%. Tax: 0% because this circle only returns members' principal and
+// charges no service. The organiser keeps none of the 18,000 SAR contributed.
+object group "Shopkeepers savings circle" {
   fields { groupName: text, purpose: text }
   columns: [groupName, purpose]
   attach circle = savings.circle {
-    expose create as create_circle
     contribution: 500 SAR, members: 6, starts: 2027-01-01
-    expose disband as disband_circle
-    expose close as close_circle
+    // At creation supply circleDates: the first of January through June 2027.
+    expose create as agree_circle_calendar
+    expose disband as cancel_unstarted_circle
+    expose close as close_completed_circle
   }
   attach membership = savings.membership {
-    expose create as create_membership
     circle: circle, member: actor
-    expose activate as confirm_membership
-    expose withdraw as leave_circle
+    // Assign a distinct seat from 1 to 6 to each member at creation.
+    expose create as join_circle
+    expose activate as confirm_membership_schedule
+    expose withdraw as leave_cancelled_circle
   }
-  // Contributions and each member's payout follow the declared calendar.
 }
+
+// Create periods 1 through 6 for EVERY member before activating membership.
+// The clock activates the circle when all six have joined. Then confirm each
+// membership. Contributions and payouts run on that calendar, including after
+// a member has received their pot. A missed collection is not a promised retry.
+expose group.membership.contribution.create as schedule_member_contribution