SIGNALS Docs
Exit Reader View
100%
Theme

Finance operations

The read-only finance operations dashboard, payment and billing-run reconciliation commands, billing-run recovery runbook, pricing commands, and multi-currency audit and rebuild commands.

Overview

This page collects the operator runbooks for finance: the read-only finance dashboard, reconciliation and recovery commands, pricing evidence commands, and multi-currency audits. The user-facing screens are described in Invoicing & Payments, Payments, Billing runs, Pricing & Discounts and Multi-Currency & Tax. In Signals Cloud, run commands inside a selected tenant context.

Finance operations dashboard

Open Admin → System → Integrity → Finance (admin.settings.integrity, /admin/settings/integrity?tab=finance). The payments.operations route (/payments/operations) redirects to this tab. The tenant-wide integrity reader requires settings.manage and all-warehouse access; restricted users are refused before finance source queries. Cloud also requires a selected, fully bound tenant.

Eight cards show counts for unapplied cash, recorded settlement exceptions, missing historical base-currency data, net-tax return readiness blockers, posting conflicts, stale billing claims/runs, failed billing/credit effects and invoice projection drift. Counts are records, never cross-currency money totals. Each card names its limited coverage; a missing or failing reader produces unavailable values rather than zero. A zero count covers only what that card checks.

The page calls the existing read-only finance integrity audit and net-tax readiness checks, and reads durable issue-effect errors. It does not activate monitoring, emit operational alerts, dispatch retries, repair projections or change provider facts. Pure tax filing/jurisdiction status, live FX availability, other effect/claim families and complete replay coverage remain explicitly unavailable.

A full scan can be slow on a large installation.

Operational reconciliation

signals:reconcile-portal-payments compares paid Checkout Sessions and succeeded PaymentIntents without writing by default. --record retains verified receipt facts and aliases without allocating invoice cash. Use --repair only when the preview warrants allocation through the installed payment recorder. Repeating repair does not create a second payment. A locally locked account, settlement or invoice is reported as skipped_locked and can be revisited in a new selection after the lock is released.

Use --max-pages=1 to 100 per provider object type, with optional --created-after and --created-before bounds. --json emits version 1, allowlisted receipt rows, status counts and pagination with unit=provider_objects, the page limit, actual pages, truncated and next_cursor. It excludes provider metadata, customer contact details and exception text. Pass the returned opaque cursor with the same date bounds and mode to continue; each object stream resumes separately. A cursor cannot be moved to another tenant, command or selection. A completed selection has a null cursor; an interrupted run should restart the idempotent selection.

The five installed reconciliation commands use these source units:

Command Source bound and resume JSON contract Exit status
signals:reconcile-portal-payments --max-pages=1..100, optional --cursor version=1, rows, counts, pagination 0 for a completed comparison; 1 for validation, listing or row failures
signals:billing-runs:reconcile-attempts --limit=1..500, optional --cursor; stable attempt IDs and age cutoff version=1, rows, errors, pagination, exit_code 0 for inspection/repair with no failed attempts; 1 for refused or failed work; 2 for invalid options
signals:finance:integrity optional --limit=1..500 and --cursor inspect invoice roots only; omit both for the complete audit existing schema_version=22, findings, coverage; bounded runs add pagination 1 for critical findings or incomplete coverage; --allow-incomplete permits incomplete coverage only
signals:billing-runs:audit-counters exactly one named run, --limit=1; no cursor version=1, cached/grouped counts, mismatches, pagination 0 for matching counters; 1 for missing/mismatched run; 2 for invalid audit modes/bounds
signals:audit-invoice-source-links optional --limit=1..500 and --cursor inspect invoice-line IDs; omit both for all eligible lines version=1, scanned, anomalies, total, pagination 0 after inspection; 1 with anomalies and --fail-on-anomaly; 2 for invalid options

The three audits are read-only and refuse --record and --repair. Bounded invoice integrity reports explicitly omit other finance families, invoices outside that page and historical policy checks; they remain incomplete even when the page contains no findings. Audit samples and counts describe only the inspected page. Combine pages before interpreting a bounded selection, and never treat an empty page as a complete finance release pass. The counter audit's one named run is already a terminal unit. JSON option refusals use a versioned error envelope; the shell exit status remains authoritative. Choose at most one of default/explicit --dry-run, --record and --repair.

Billing-run operator recovery

The scheduler attempts pending dispatch every minute, reconciles stale claims every fifteen minutes, and retries pending issue effects every minute. In Signals Cloud, run the commands inside a selected tenant context; the command refuses an unbound or config-only tenant. Inspect one attempt and its run/item/invoice evidence before using a write option.

The attempt's dispatch_status is separate from the run state:

Attempt dispatch state Operator interpretation
pending The locked issue claim exists, but no worker has claimed queue dispatch. Preview or retry pending dispatch.
claimed A dispatcher is or was working. An original claim may be retried; first check for an unacknowledged durable batch.
dispatched A framework batch was acknowledged. Inspect its immutable marker and item claims before reconciliation or cancellation.
cancelled An original attempt with no durable batch was safely cancelled and its claim items settled Failed. This is not a Cancelled run or a reversal of posted invoices.

Attempts without the immutable invoice-version snapshot cannot be dispatched or used to claim a draft. Inspect their batch and invoice evidence, then use the guarded cancellation or reconciliation path; do not invent a version for an already-claimed item.

If a worker retries after its claimed invoice is already issued, it settles the item only when that attempt's complete posting and downstream-intent receipts are present. An invoice issued outside the run, or one with missing receipts, stays claimed for operator investigation; the retry must not manufacture receipts for it.

Situation Preview first Apply only when the evidence is clear
Attempt claimed but no acknowledged batch php artisan signals:billing-runs:dispatch-pending --attempt=<uuid> Add --apply to retry dispatch/adopt its durable batch.
Dispatched attempt with stale Pending/Ready claims php artisan signals:billing-runs:reconcile-attempts --attempt=<uuid> Add --apply to settle only receipt-backed posted or authoritatively unissued items. Read the unresolved count; it is not an all-clear.
Original attempt without a durable batch cannot safely dispatch php artisan signals:billing-runs:reconcile-attempts --attempt=<uuid> --cancel-stalled-attempt --older-than-minutes=60 --reason=<code> Add --apply only after confirming the command's preview and absence of posting/effect receipts. The run becomes Failed.
Verified dispatched batch is stalled php artisan signals:billing-runs:reconcile-attempts --attempt=<uuid> --cancel-stalled-batch --older-than-minutes=60 --reason=<code> Add --apply to cancel the batch and reconcile safe claims. Check the resulting run state and unresolved count.
Posted invoice is settled but PDF, communication or dashboard work is pending php artisan signals:billing-runs:dispatch-issue-effects --receipt=<id> Add --apply to retry the recorded effect; do not reissue the invoice.

A saved framework batch is not proof every queue job was delivered. If an original unacknowledged batch has the matching immutable marker but its jobs are absent or delivery cannot be confirmed, preview and apply dispatch-pending to adopt that batch; it must not create another one. Adoption retains the batch's original creation time for the cancellation age check. After inspecting the queue, invoice states and effect receipts, preview reconcile-attempts --cancel-stalled-batch --older-than-minutes=60 --reason=queue-delivery-unconfirmed and apply only if cancellation is warranted. It fences late jobs, but may leave a posted or ambiguous claim unresolved for investigation. Do not infer missing jobs solely from a batch counter or an empty queue listing: a worker may already have taken a job.

<code> is a short, non-sensitive reason such as stalled-worker-review; never put customer data in it. Cancellation requires one attempt UUID and a minimum age of 60 minutes. Missing/mismatched batch identity, incomplete attempt scope, ambiguous posted invoices or incomplete effect receipts fail closed or remain unresolved: investigate the authoritative invoice and receipts rather than manually clearing a claim. The normal reconciler starts at 15 minutes; it cannot prove every ambiguous external effect safe to repeat.

Framework batch retention

Run php artisan signals:billing-runs:prune-batches manually in the selected tenant context (or the self-hosted application). It deletes only framework job_batches metadata with a non-null finished_at strictly older than 24 hours and a null cancelled_at. The cutoff and cancellation exclusion have no command overrides. Finished-and-cancelled batches, unfinished batches, and batches at or after the cutoff survive. This command has no scheduled run.

Finance runs, items, issue attempts and issue-effect receipts are retained, including their original batch IDs after metadata expires. Invoices, payments, postings and event sources are untouched. Use the attempt/item/receipt links and the recovery commands below when the framework batch is absent; absence does not establish successful issuance or authorize a financial retry.

The framework queue:prune-batches command has broader optional pruning and can delete finished-and-cancelled batches even with its default options. Use the Signals command for this retention policy; do not schedule the framework command for these records.

Bounded reconciliation modes

reconcile-attempts is read-only by default. --record reports attempt facts that are already retained and does not settle items or cancel a batch. --repair explicitly invokes the installed receipt-backed reconciliation; --apply selects the same repair mode. Never combine mode flags. Repair keeps the existing transaction locks through settlement; a held run, attempt or item is reported as skipped_locked without settling it.

Use --limit=1..500 and the returned --cursor to resume the same age, attempt, cancellation and mode selection. The cursor keeps the original cutoff and upper attempt ID; already visited attempts do not repeat. After a skipped lock is released, start a new selection to revisit that attempt. --json emits version 1 with attempt rows, errors, pagination and the command exit code; it includes no invoice/customer payloads. See Operational reconciliation for the complete command and exit-status map.

The console controls for the same recovery paths are described in Billing runs → Recovery controls in the console.

Before choosing a recovery action

Record the attempt UUID, active run, immutable scope/item and invoice-version snapshot, dispatch status, batch ID/marker, item states and posting/effect receipts. Attempt, queue-batch and run states answer different questions; a cancelled batch does not reverse invoices.

Preview the command for that one attempt without --apply. Dispatch/reconciliation inspection defaults to 50 attempts and accepts --limit from 1 to 500; age filters must be integer minutes. Normal reconciliation starts at 15 minutes, while cancellation requires at least 60 minutes, exactly one attempt and one non-sensitive reason code. Use either cancellation flag, never both.

If a durable matching batch exists, recover its acknowledgement rather than creating a replacement. If posting or effect evidence is ambiguous, preserve the claim and investigate the source; do not invent a receipt, invoice version or item status. Read both the per-attempt status and unresolved count after apply. The ordinary reconcile command can exit successfully while unresolved items remain, so a zero exit status is not proof the run is terminal. A cancelled batch with unresolved claims is explicitly reported as an unsuccessful cancellation outcome.

Treat completion as an all-item result: any remaining non-terminal item keeps Issuing; no issued item means Failed, including an all-excluded run; issued plus failed means Completed with failures; issued with only issued/excluded terminal items means Completed. Completion does not prove every PDF, communication or other downstream effect finished. Inspect those recorded effect receipts and use the effect dispatcher rather than issuing invoices again. Never edit immutable attempt identity/scope evidence or delete its record to force recovery.

Pricing commands

Saved draft-book simulation

Run php artisan signals:price-book:simulate-drafts /absolute/path/scenarios.json --actor=123 to compare two draft books locally. The actor must be active and hold rates.view; a cloud invocation also needs an active, bound, matching tenant database. The command prints one JSON report or one coded JSON error and does not log in the actor, publish drafts, activate rates or change rental prices.

There is no aggregate price-book draft model. Each labelled book is a saved set of actual CatalogueItemPriceRevision IDs, covering the same rate-parent identities. Each revision must be an intact draft and refer to an intact published RateSpecificationRevision. Selection uses the installed warehouse, category, transaction, currency and business-date policy; calculation uses the same rate-and-tier matrix as Catalogue Prices.

{
  "schema_version": 1,
  "books": {
    "left": {"id": "draft-a", "rate_revision_ids": [101, 201]},
    "right": {"id": "draft-b", "rate_revision_ids": [102, 202]}
  },
  "scenarios": [{
    "id": "warehouse-day",
    "catalogue_item_id": 10,
    "warehouse_id": null,
    "rate_band_id": null,
    "rate_band_tier_id": null,
    "transaction_type": "rental",
    "start": "2026-07-01T09:00:00Z",
    "duration_hours": 24,
    "quantity": "1.5",
    "currency": "GBP"
  }]
}

Use a local JSON file of at most 64 KiB, with 1–20 uniquely labelled scenarios and at most 100 distinct draft revision IDs per book. Quantities are decimal strings and start dates include an explicit offset. Both sets must cover each scenario's item; incomplete or mismatched sets refuse the entire report. An item with no eligible draft candidate stays unresolved, with no published fallback. Missing or different captured currency precision makes the comparison unavailable.

delta_minor and delta mean right draft minus left draft in their common captured currency units. The report includes the actual model, parent, logical identity, revision and content hash for each draft. Current published resolution and its cache remain unchanged; draft selection is uncached. Permission checks use the existing Gates with a disposable permission-cache context restored after each invocation.

The scope is rate and the currently installed tier only. Specification drafts, rule drafts, discounts, bundles, surcharges, tax and FX scenarios are unsupported; unknown input keys refuse instead of being ignored. This is an operator-owned file, not a new shared scenario repository or an activation command.

Rule revision backfill

Rules without published revisions can be inspected or assigned revisions with:

php artisan signals:pricing-rules:backfill-revisions --dry-run --fail-on-invalid
php artisan signals:pricing-rules:backfill-revisions --apply --reason="Backfill rule revisions." --fixed-currency=GBP

The apply mode is resumable by source ID. It never guesses a fixed-rule currency: the operator must supply an installed, explicitly approved currency, otherwise the rule is reported or held for review.

Verifying and repairing pricing manifests

Verify or repair manifests with:

php artisan signals:pricing-manifests:verify --fail-on-invalid
php artisan signals:pricing-manifests:verify --repair --reason="Restore accepted projection from immutable evidence."

Verification leaves accepted commercial amounts and immutable evidence unchanged. Explicit repair restores supported projection drift only after locking the rental and checking its current published manifest. Missing or corrupt evidence, inconsistent original money units (rental_money_context_mismatch) and invalid issued-invoice references refuse repair. Captured costs remain historical provenance; later cost edits are not projection drift and are never reverted.

Use --json for the version-1 report. It includes per-manifest reconstructability with a status and refusal code, repaired_manifests for completed repairs, and next_after_id for resuming verification or repair with --after-id. --rental requires a positive integer; malformed input returns INVALID (exit status 2) instead of scanning other rentals.

With --fail-on-invalid, diagnosed incoming drift still returns exit status 1 after successful repair. A concurrent acceptance can supersede a manifest after discovery; repair then skips it with manifest_not_current, preserves the newer acceptance, and also returns 1 with this flag. Inspect the report before retrying. Repair requires a non-empty --reason, but does not persist that maintenance reason or operator identity; the original acceptance metadata is retained.

Multi-currency audits

Historical base currency identity

NULL identities are resolved by signals:base-currency-identity:backfill. Already recorded identities are skipped. Sources are checked in order: the row's own replayable events; recorded base money units; the accepted rental pricing manifest or a credit note's invoice; an open rental cost’s resolved parent rental (source parent_rental); then unchanged contemporaneous settings. Settled costs use their own historical sources and must agree with a recorded parent identity. Every source found must agree. Events after issue, send or lock naming different bases are ambiguous.

Settings prove identity only when the persisted company.base_currency row names a valid ISO currency, its update precedes the document's creation by at least one second in UTC, and no later settings.updated audit touches that setting. Audit history alone is a hint because logs can be pruned. A missing setting is unresolved. Today's base is used only for open rows without historical data: draft or voided-before-issue documents, unsent purchase orders (including cancellation before send) and unlocked enquiries or quotes that have never reached an order/lock boundary and have no issued invoice or posted cost. Previously settled rentals remain historical even if their locks were later released.

Resolved identities from events can be stamped directly because replay writes the same code. Other sources on event-sourced documents are persisted in identity-recorded events. Asset stamps also create an audit entry. Unresolved or conflicting evidence leaves NULL in place and writes the reason to base_currency_identity_findings; readers refuse that missing identity. Payment evidence is append-only, so it is reported with its invoice candidate and never updated. Prior billing-run bases are reported with status assumption and reason migration_assumption and can only confirm or contradict other evidence on settled rows. Open rows retain billing-run context as informational evidence.

Operator-confirmed identities use source operator, a required reason and system actor evidence; they never relabel an already recorded identity.

Run the base-identity backfill as a dry run with a report to identify unresolved rows and accounts with open invoices or active orders; those accounts will need a credit override or operator repair. Rows whose identity cannot be established keep NULL and remain incomplete; the current company base is not assumed for historical rows.

Auditing rate currencies

php artisan signals:audit-price-currencies lists every catalogue item price whose currency does not match its scope.

Invocation Behaviour
(no option) Read-only. Prints a table of Rate ID, item, warehouse, rate currency, and expected currency.
--fix Still writes nothing. Additionally names the rows whose retag would be unambiguous — the two currencies have the same number of minor-unit digits and an exchange rate exists.
--fix=retag Stamps the expected currency onto every violating row while keeping the stored number. This changes real prices and is only correct for rows that were mis-tagged all along.

The same guard runs ahead of a warehouse currency change and a currency deletion — see Warehouses.

Rebuilding base amounts

Base columns are frozen at write time, so adding a missing exchange rate afterwards does not retro-correct documents that were already stored. Recompute them with:

php artisan signals:rebuild-base-amounts
Option Behaviour
--table= Limit to one of assets, rentals, invoices, credit_notes, purchase_orders, rental_costs, asset_costs, asset_retirements.
--report= Write the reported rows (no usable rate, or refused, with the problem) to a JSON file.
--dry-run Write nothing. Say how many rows would change.
--strict Exit 1 when any row is reported.

The rebuild is display conversion only and never uses a rate of 1 in place of a missing rate:

  • A posted document, or a draft with a rate source, keeps its own frozen rate and base currency, so the rebuild writes what a replay of its events writes.
  • A document with no rate source uses its stored rate. A foreign stored rate of exactly 1 is the original fallback (unless its events say it was a real rate), so the row gets empty base amounts and is reported.
  • The base currency of a posted document comes from the document, else from its events (a credit note can also take its invoice's). The current company.base_currency is never used for it: a posted document with none of these is reported and keeps what it had. A posted document without recorded base-currency evidence is refused on every run, and --strict then always exits 1; the report lists these rows and there is no automatic fix. A foreign draft voided before issue with no stored rate or rate date is also reported on every run, because a void document is never priced at a live rate.
  • The paid and outstanding base amounts of an invoice with no rate source and with payments or credits follow the same rules on replay and on rebuild, so both write the same values, read in the invoice's recorded money units (a foreign balance without recorded units after a scale change is empty). Two cases are not the same: a foreign rate of exactly 1 that only the events confirm as real (the rebuild converts at it, a replay writes empty base balances), and a posted invoice whose base currency is recorded only on its events (the rebuild uses it, a replay writes empty base balances). A voided invoice owes nothing, so its base outstanding is zero (empty when it had no base money).
  • A draft with no stored rate is priced at its transaction-date rate into the base currency the invoice records, else the company base currency (a draft credit into its invoice's base currency), and that base currency is recorded, so a second run changes nothing.
  • A foreign document without recorded money units is refused, reported and left unchanged when a currency's minor-unit scale is no longer its ISO scale. A same-currency document is never refused.
  • A draft whose events recorded no rate keeps empty base amounts. When a rate exists now, the output says to re-save the draft.

Add a missing rate under Admin → Money & Pricing → Exchange Rates, then run the command again; a second run changes nothing it has already rebuilt. Long lists are truncated in the console; use --report to capture all of them.

Exit codes: 0 when the run completes (reported rows included), 1 with --strict when any row is reported, and always 1 when a row fails for an unexpected reason (for example a database error on its write). Such a row is reported with the error and left unchanged, and the run continues.

Changing company.base_currency while transactional documents exist saves successfully but leaves every stored base amount computed against the original base. The admin Company Details save toast becomes a warning naming this command, and the audit event records rebuild_required. Run the rebuild before trusting any base-labelled figure afterwards.