I. How to model home repair marketplace for home services AI

A homeowner accepts a contractor job sold through a platform. Reserve confirmed customer funds, then split the approved service amount between the provider payable and platform income. FRAGMENT tracks balances and payout reservations; your application authorizes the allocation and the payment provider executes transfers.

Worker classification and repair disputes are external.

Store the home repair job, its approval, and supporting evidence in your application. Bind the record to its source, tenant, and recipient. Preserve the approved amount, record version, and payment status. Give each intended financial effect an immutable operation key and payload fingerprint. A ledger entry records an authorized financial movement. It does not execute an external payment or atomically commit your application database. Use opaque account identifiers and bind them server-side. Fixture identifiers are examples; a balance condition does not authorize a caller.

Use this model to allocate funded customer balances between a provider payable and platform income, with reserved payouts and refunds. If application records and balances must share one database transaction, consider the Postgres integration trade-off. A provider who has already been paid cannot be refunded through an unfunded payable reversal. Paid-out clawbacks, chargebacks, processing fees and tax require separately reviewed extensions.

The money path is: confirmed customer funds → available → case hold → provider payable plus platform fee → payout pending → confirmed payout; approved customer credits and refunds follow their own reserved path.

Fund the customer balance from confirmed money. Reserve the accepted case amount. On authoritative service acceptance, split it between the provider payable and platform fee. An approved unpaid credit reverses explicitly identified provider and fee portions. Reserve a provider payout or customer refund before requesting its external effect.

The schema declares the following leaf accounts. :<id> denotes an instance of a template account; exact posting paths and parameter names are in the downloaded JSON.

All amounts in this example are USD cents encoded as integer strings. The figures below are illustrative test values, not proposed prices, compensation amounts or commercial terms. Token usage, service quantities and exchange rates are outside this example.

Start with a fresh empty test ledger. Read the steps in order. The replay step deliberately repeats the funding operation key and payload; it must leave balances unchanged. Every rejected operation must also leave all balances unchanged.

The account paths above match the scenario file. A snapshot lists the balances checked at that point; it does not assert that all other balances are zero. The included schema scene contains the accepted entries; the separate fixture file contains replay and rejection cases too.

Some fixtures divide a reserved outgoing amount into a definitively failed portion and a settled portion. Your application must represent those as separately identified external sub-operations with exact amounts. This is an illustrative recovery sequence, not a claim that a given payment API supports partial failure on one request.

Download schema.json and the application contract. Use the shared tool guide for installation and current official references. From the directory containing your reviewed schema:

fragment verify-schema --path schema.json --json
fragment gen-graphql --path=schema.json --output=queries.graphql

Choose the official SDK for your application's language and generate the schema-specific client as documented. For MCP, connect the intended workspace and confirm the target project before editing, simulation or deployment. Tool names can vary across server versions; enumerate the connected server instead of assuming a universal tool list.

After the confirmed funding step, this is an example variable object for the first business allocation:

{
  "ik": "replace-with-stable-business-operation-key",
  "entry": {
    "ledger": {
      "ik": "replace-with-confirmed-test-ledger"
    },
    "type": "home_repair_marketplace_reserve",
    "typeVersion": 1,
    "parameters": {
      "source_id": "1",
      "case_id": "1",
      "amount": "700"
    }
  }
}

Use it with the documented AddLedgerEntry mutation. Replace the test-ledger and operation-key placeholders with confirmed values; the other identifiers and amounts must match your authorized test case. The complete accepted request sequence is provided as review data, not as an automatic execution script. Handle returned error results as well as transport failures.

The schema's balancing and nonnegative postconditions do not reject every invalid signed input. Validate these rules before posting, using the downloaded contract as the exact reference:

Authorize the exact source, case and recipient; check the current approval version; and reject a command that conflicts with a terminal domain outcome. A new approval revision is a new business decision. A duplicate delivery of the same revision is a retry, with the same operation identity.

Keep funds reserved while the payment outcome is unknown. Release only the amount confirmed as definitively failed; record settlement only after provider confirmation. For a timed-out ledger request, retry the same operation key and payload to avoid posting twice.

1. Persist an authorized command and an outbox record before requesting an effect. Keep its ledger key, payload fingerprint, case version and provider operation identity durable.
2. Reserve the relevant available amount before requesting an outgoing payment. If the ledger request times out, recover using the same operation key and payload; do not invent a second operation because the first response was lost.
3. Submit the provider action according to that provider's idempotency and retry rules. Keep its identifier bound to the exact pending reservation. This guide supplies no provider-specific retention guarantee.
4. If the provider outcome is unknown, leave the amount reserved and reconcile it. An elapsed timer is not proof of failure. A definitive failed sub-operation can release its own amount; a confirmed settlement can consume its own amount.
5. Deduplicate callbacks and reject mismatched or stale case/payee/amount associations. Keep terminal operation decisions immutable and post authorized adjustments separately.
6. Reconcile assets/confirmed-cash against the actual external records. These schemas use a manually modeled cash account. A linked-account reconciliation integration is an additional implementation step, with separate unlinked buckets for conditional authorization.

• Change the agreed fee for the home repair job after allocation; authorize an explicit adjustment to the affected balances.
• Cancel the home repair job while a provider payout is pending; resolve that payout before assuming the funds can be refunded.
• Test the boundary for this particular workflow: worker classification and repair disputes are external. The application should route the decision to the appropriate domain system rather than treating the ledger balance as authority.
• Submit two competing commands that individually fit the current balance but together exceed it. In a live test ledger, verify that accepted total allocation stays within the available amount and that rejected commands have no effect.
• Crash after reservation but before your application stores the response. Recover the recorded operation instead of crediting or debiting the case twice.

The originating schema passed the local FRAGMENT parser and the earlier offline model fixtures. This written guide does not establish live API, concurrency, callback recovery or provider correctness. Before release, have a domain reviewer accept the stated boundaries, run the full fixture sequence in a fresh test ledger, compare actual balances with the expected snapshots, and test real retry/reorder/unknown-outcome recovery using controlled test operations.

Also verify that one tenant cannot choose another tenant's source or case, that nonpositive or inconsistent amounts are rejected by the application, and that every posted movement has durable approval and payment evidence. Record the exact schema version and result traces. Publication and agent-discovery evaluation are separate from this integration acceptance.

1. A 
   Plumbing booking deposits
2. B 
   Hvac service card payments
3. C 
   Cleaning subscription prepayments
4. D 
   Appliance parts reimbursements

1. A 
   Quickstart: schema, SDK and API setup
2. B 
   Posting entries: parameter strings and idempotency
3. C 
   Consistency: strong balance conditions and linked-account restrictions
4. D 
   Payment reconciliation
5. E 
   CLI reference
6. F 
   MCP reference
7. G 
   SDK reference
8. H 
   Schema
9. I 
   Expected results
10. J 
    Request variables
11. K 
    Application contract