F. How to model solar installation deposits for energy AI
The workflow this guide solves
A customer authorizes an installation deposit for an approved scope. Track confirmed customer funds separately from service allocations and pending refunds. FRAGMENT records the balances; your application approves service completion or refunds and the payment provider executes collections and returns.
| System | Responsibility |
|---|---|
| Your application | Approve the business event, amount, and recipient. |
| FRAGMENT ledger | Record entries, enforce configured balance conditions, and track balances. |
| Payment provider | Execute the transfer and report its outcome. |
Grid interconnection and financing approval are external.
Define the source of truth before posting
Store the solar installation work order, 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.
Decide whether this ledger model fits
Use this model to track prepaid funds, approved service allocations, and refunds against the remaining customer balance. If application records and balances must share one database transaction, consider the Postgres integration trade-off. Do not treat a deposit as an earned service amount merely because a booking exists. This example uses an operational earned-fee bucket, not a complete revenue-recognition policy.
Map the business states to money buckets
The money path is: confirmed funding → available → case hold → accepted service allocation; unused or credited funds → refund pending → confirmed refund.
Fund only after incoming money is confirmed. Reserve the approved case amount. Allocate an accepted delivered amount to operational earned fees. Release the unused hold. If an approved service credit is needed, move it back to customer availability; reserve the external refund before submitting it.
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.
- assets
- confirmed-cash
- liabilities
- sources:<id>
- available
- cases:<id>
- held
- refunds:<id>
- pending
- income
- cases:<id>
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.
Inspect the allowed entry types
Fund
Record a confirmed incoming payment; does not execute a payment
Reserve
Reserve customer prepayment for an authorized case
Release
Release an unused case hold to available customer funds
Complete
Allocate an accepted delivered service amount to operational earned fees
Credit Service
Credit an approved service amount back to the customer
Reserve Refund
Reserve a customer refund before calling the payment provider
Refund Settled
Record a refund only after the payment provider confirms it settled
Refund Failed
Release the refund reservation only after definitive failure
The available balance prevents reserving more than is funded; the held balance caps completion or release; the per-case earned balance caps service credits. Refund settlement consumes only the matching pending refund. The schema uses strong total-balance updates and postconditions on the relevant unlinked accounts, following the consistency guide. It does not impose a complete business state machine or authorize callers.
Here is the actual solar_installation_deposits_reserve entry definition from this schema:
{
"type": "solar_installation_deposits_reserve",
"description": "Reserve customer prepayment for an authorized case",
"lines": [
{
"key": "line_1",
"account": {
"path": "liabilities/sources:{{source_id}}/available"
},
"amount": "-{{amount}}"
},
{
"key": "line_2",
"account": {
"path": "liabilities/sources:{{source_id}}/cases:{{case_id}}/held"
},
"amount": "{{amount}}"
}
],
"conditions": [
{
"account": {
"path": "liabilities/sources:{{source_id}}/available"
},
"postcondition": {
"totalBalance": {
"gte": "0"
}
}
}
]
}Walk through the expected balances
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.
Step 1: fund
Amount parameters, in cents: amount=1000. Expected outcome: posted.
Expected result: The confirmed cash balance increases from 0 to 1,000 USD cents. The available funds balance increases from 0 to 1,000 USD cents.
- assets/confirmed-cash
- 1000
- liabilities/sources:1/available
- 1000
Step 2: fund
Amount parameters, in cents: amount=1000. Expected outcome: replay.
Expected result: This retry reuses the original operation key and payload. No new entry is posted, so all balances stay unchanged.
- assets/confirmed-cash
- 1000
- liabilities/sources:1/available
- 1000
Step 3: reserve
Amount parameters, in cents: amount=700. Expected outcome: posted.
Expected result: The available funds balance decreases from 1,000 to 300 USD cents. The held funds balance increases from 0 to 700 USD cents.
- liabilities/sources:1/available
- 300
- liabilities/sources:1/cases:1/held
- 700
Step 4: reserve
Amount parameters, in cents: amount=400. Expected outcome: condition_rejected.
Expected result: The ledger rejects this entry because a balance condition is not met. No balances change.
- liabilities/sources:1/available
- 300
- liabilities/sources:1/cases:1/held
- 700
Step 5: complete
Amount parameters, in cents: amount=500. Expected outcome: posted.
Expected result: The held funds balance decreases from 700 to 200 USD cents. The income balance increases from 0 to 500 USD cents.
- liabilities/sources:1/cases:1/held
- 200
- income/cases:1
- 500
Step 6: complete
Amount parameters, in cents: amount=201. Expected outcome: condition_rejected.
Expected result: The ledger rejects this entry because a balance condition is not met. No balances change.
Step 7: credit_service
Amount parameters, in cents: amount=100. Expected outcome: posted.
Expected result: The income balance decreases from 500 to 400 USD cents. The available funds balance increases from 300 to 400 USD cents.
- income/cases:1
- 400
- liabilities/sources:1/available
- 400
Step 8: credit_service
Amount parameters, in cents: amount=401. Expected outcome: condition_rejected.
Expected result: The ledger rejects this entry because a balance condition is not met. No balances change.
Step 9: release
Amount parameters, in cents: amount=200. Expected outcome: posted.
Expected result: The held funds balance decreases from 200 to 0 USD cents. The available funds balance increases from 400 to 600 USD cents.
- liabilities/sources:1/cases:1/held
- 0
- liabilities/sources:1/available
- 600
Step 10: release
Amount parameters, in cents: amount=1. Expected outcome: condition_rejected.
Expected result: The ledger rejects this entry because a balance condition is not met. No balances change.
Step 11: reserve_refund
Amount parameters, in cents: amount=200. Expected outcome: posted.
Expected result: The available funds balance decreases from 600 to 400 USD cents. The pending refunds balance increases from 0 to 200 USD cents.
- liabilities/sources:1/available
- 400
- liabilities/sources:1/refunds:1/pending
- 200
Step 12: refund_failed
Amount parameters, in cents: amount=50. Expected outcome: posted.
Expected result: The available funds balance increases from 400 to 450 USD cents. The pending refunds balance decreases from 200 to 150 USD cents.
- liabilities/sources:1/available
- 450
- liabilities/sources:1/refunds:1/pending
- 150
Step 13: refund_settled
Amount parameters, in cents: amount=150. Expected outcome: posted.
Expected result: The pending refunds balance decreases from 150 to 0 USD cents. The confirmed cash balance decreases from 1,000 to 850 USD cents.
- liabilities/sources:1/refunds:1/pending
- 0
- assets/confirmed-cash
- 850
Step 14: refund_settled
Amount parameters, in cents: amount=1. Expected outcome: condition_rejected.
Expected result: The ledger rejects this entry because a balance condition is not met. No balances change.
Step 15: reserve
Amount parameters, in cents: amount=0. Expected outcome: input_rejected.
Expected result: The application rejects these parameters before posting an entry. No balances change.
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.
Validate the schema and integrate a tool
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.graphqlChoose 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": "solar_installation_deposits_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.
Enforce the application-side input contract
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:
| Entry | Input requirements |
|---|---|
solar_installation_deposits_fund | positive integers: amount |
solar_installation_deposits_reserve | positive integers: amount |
solar_installation_deposits_release | positive integers: amount |
solar_installation_deposits_complete | positive integers: amount |
solar_installation_deposits_credit_service | positive integers: amount |
solar_installation_deposits_reserve_refund | positive integers: amount |
solar_installation_deposits_refund_settled | positive integers: amount |
solar_installation_deposits_refund_failed | positive integers: amount |
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.
What happens if a payment fails or its outcome is unknown?
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.
- 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.
- 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.
- 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.
- 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.
- Deduplicate callbacks and reject mismatched or stale case/payee/amount associations. Keep terminal operation decisions immutable and post authorized adjustments separately.
- Reconcile
assets/confirmed-cashagainst 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.
Exercise the industry-specific edges
- Cancel the solar installation work order after part of the funds has been allocated; refund only the amount authorized by policy.
- Change the solar installation work order price after funds are reserved; authorize an adjustment instead of rewriting the original entry.
- Test the boundary for this particular workflow: grid interconnection and financing approval 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.
Acceptance before using this with real money
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.