SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Account data repair

Operator runbook for the account health gate, account repair commands, historical partial-merge repair, relationship evidence review and accounts rollback controls.

Overview

This is a reference page for Accounts. It is the operator runbook for checking and repairing account data. Run the read-only health report first and preview every repair before applying it.

Health gate and Account Operations dashboard

Run the release health gate with:

php artisan signals:accounts:health --json --fail-on=critical

It reports identity, relationship, merge, alias, credit, privacy, retention and search-index findings without including account values. Treat critical findings as blocking before you upgrade or deploy. Approved relationship and contact-point held records are counted separately from unexplained pending conflicts.

The v1 alert contract is the versioned JSON alerts array plus the process exit status, consumed by an operator-managed scheduler or monitoring system. Each alert contains only code, count and severity; the report also supplies its UTC generated_at, aggregate status and summary. No account identifiers, names or record narratives belong in the report. There is no installed automatic health schedule or notification/delivery channel, and no delivery or deduplication guarantee is claimed. Configure monitoring separately for the intended tenant and invocation frequency.

--fail-on=critical (the default) exits 1 for critical findings and 0 for warning-only or healthy reports. --fail-on=warning exits 1 for either warning or critical findings; --fail-on=never always exits 0, so use it only for report collection. An invalid threshold exits 2 after the audit has emitted its report. Treat a non-zero status as a monitoring signal under the chosen threshold; inspect the structured alerts rather than parsing display text. This contract does not send email, webhooks or operator notifications.

The Account Operations dashboard requires both accounts.view and accounts.operations.view. It shows a snapshot with its check time; explicit Refresh performs a new read-only audit. An alias anomaly leaves credit evidence explicitly Unverified rather than inventing zero findings. The dashboard is an operator view, not a background scheduler.

Repair commands

Repairs require an active authenticated User with accounts.repair and visibility of every target through the usual warehouse scope. For a scheduled or unauthenticated CLI invocation, supply --actor=<User ID> for an explicit principal with the same permission and visibility; the scheduler has no bypass. An inactive, archived or unknown principal is refused before repair counts are read. The permission is separate from viewing operations and is included in the Admin role; grant it deliberately to another operator only when needed.

Supported operations are canonical-contact-values, contact-primaries, expired-reservations, history-projection, and search-index. Supply explicit positive integer --account IDs, the current --expected-manifest-version, --batch from 1–100 and exactly one of --dry-run or --repair. IDs are sorted and deduplicated. A missing or merged-away target is refused, rather than silently redirecting the repair. Live repairs also require a nonempty --reason and confirmation, or an explicit --force.

Dry-run preserves source, projection and effect rows. Its immutable receipt records unchanged before/after counts and each account's would_change count; changed stays zero. Review that preview, then start the live run without resuming its preview receipt. Live repair is atomic per account. If an account fails, that account rolls back, later accounts are untouched, the command exits 1 and its failed receipt checkpoints the last successful account. Resume that receipt after correcting the defect; raw exception details and contact values are not copied into evidence. Repeating a repaired target records zero changes.

The canonical-contact repair derives email/phone/address normalized values and integrity keys with the same normalizer as ordinary contact writes. It leaves raw contact values and verification metadata unchanged. Colliding rows are left byte-for-byte unchanged and recorded for review rather than choosing a winner. Its receipt includes examined/changed/skipped/collided counts for each account; collided is a subset of skipped. --batch bounds accounts, with contact reads chunked at 250 rows; one account is atomic. --export-collisions prints only table, reason, hash and row IDs from the authorized receipt, never raw contact values. It does not resolve historical collision review or execute automatically.

--resume=<receipt UUID> must retain the operation, live/preview mode, manifest version/digest and exact account list. Canonical-contact resumes also retain the batch size and backfill version. A mismatch is refused with account_repair_resume_mismatch. Every resumed batch creates a new immutable receipt linked by resumed_from_id; resume the latest receipt for the next batch. Concurrent or repeated resumes of the same parent return its one existing child, and a completed checkpoint is a no-op. Model and database guards refuse receipt updates or deletes. The reservation repair releases expired active reservations and active reservations whose rental is missing or terminal; it never deletes credit decisions.

For example, an explicitly authorized scheduler can preview php artisan signals:accounts:repair expired-reservations --actor=42 --account=123 --expected-manifest-version=<current schema version> --batch=50 --dry-run. Use the current schema version shown by the installed reference manifest. Apply the reviewed targets with --repair --reason="Release verified expired reservations" --force, retaining the same explicit principal and version. Preview and repair are separate runs.

Canonical-contact backfill colliding rows are skipped byte-for-byte; exports and receipts identify the complete colliding rowship by table, reason, hash and row IDs. Each account result gives examined, changed, skipped and collided counts (collided is a subset of skipped). Resume binds the post-batch source snapshot and refuses intervening account or contact edits before creating a new receipt; an existing committed child is replayed. Interruption rolls back the current account; a killed process before the outer receipt commit has no committed batch, so restart redoes only rolled-back work.

Repair retained historical partial merges

signals:accounts:merge:repair <source> <canonical> --actor=<authorized User ID> prints a read-only preview by default; --record explicitly saves an immutable plan for an existing merged alias and its recorded surviving canonical target. It requires current account-view, repair, merge, contact-PII edit and credit-view permissions and visibility of both accounts. An absent or mismatched retained alias/merge receipt, inactive or protected target, lifecycle/privacy hold, staff identity or current manifest gap refuses admission. It does not reconstruct a deleted account or permit erasure.

The preview lists current references, CRM duplicate decisions, complete alias-aware exposure and blocking owner-adapter holds. Contact normalization/integrity must match current source values. Supported CRM adapters move distinct contact points, relationships, custom fields, memberships and warehouse links. Canonical values win duplicates, while duplicate and self-relationship rows remain on the source alias as retained evidence. Related accounts must remain visible, active and free of merge holds. Unsupported operational or serialized references block apply; this tool does not rewrite financial ownership, immutable legal facts or unfinished producer evidence.

Review and explicitly record the preview, then use the same explicit pair with --repair=<preview receipt UUID> --expected-preview-hash=<reviewed hash> --reason="Reviewed historical repair" and confirmation, or --force. Apply rechecks current versions, references, manifest, permissions and holds under account locks. CRM changes, canonical version/effect intent, alias-aware history rebuild and the child repair receipt commit together; any error rolls them back. Exposure must remain complete and unchanged. An exact retry returns the existing child without another version increment; a different reason or principal refuses replay. CLI output and repair receipts omit raw contact/custom-field values, and failures return a generic coded refusal. Run only against explicitly approved targets; no production run is scheduled by this command.

Relationship review

Open an account's Relationships tab to see Pending relationship reviews involving that account. Viewing requires accounts.view. Each review shows both endpoint names and preserved IDs, the retained relationship type, primary intent and primary-company contact. Missing endpoints retain their IDs with an unavailable label. Expand Retained relationship evidence to inspect the complete read-only payload, including evidence whose source relationship has been removed. Reviews and active relationships paginate independently. Operators with accounts.edit can select Dismiss review, enter a reason and explicitly confirm the dismissal. The screen records the same immutable disposition receipt as the API and retains the evidence without restoring a relationship. Reviews belonging only to other accounts are neither listed nor accepted by this screen.

Unattached relationship reviews

Open Admin → System → Relationship reviews (/admin/settings/relationship-reviews) for pending evidence with neither account endpoint still present. Admin access and accounts.view are required; dismissal additionally requires accounts.edit. A review with either existing endpoint belongs on that account's Relationships tab. Archived accounts still count as existing; absence is checked across accounts, independently of warehouse visibility. A retained primary-company contact alone does not attach a review to an account page.

The queue shows the same preserved endpoint IDs, relationship type, primary intent, primary-company contact and expandable full evidence as the account screen. Missing IDs are marked unavailable, absent values are marked Not recorded, and an empty queue shows No unattached relationship reviews found. Reviews paginate in ID order, 12 per page. Reading the queue does not change evidence.

Select Dismiss review, enter a non-blank reason of at most 1,000 characters and explicitly confirm. The queue rechecks admin access, account permissions, pending status and the absence of both endpoints on submission. If an endpoint now exists, or another operator has dismissed the review, submission is refused without another receipt. A successful dismissal keeps the complete payload, records the same immutable receipt as the account screen and API, and returns to the first page. It never recreates a relationship.

Global API

Use the global API list to inspect pending reviews across accounts, including evidence without a surviving account endpoint:

GET /api/v1/account-relationship-reviews (api.v1.account-relationship-reviews.index) lists pending relationship evidence in ID order with cursor pagination. It requires accounts.view and the accounts:read token ability. The default page size is 25; per_page accepts 1–100. Success responses place the evidence rows in data and cursor metadata in root meta. Shared ID and timestamp filters are accepted, including filter[updated_at][gte] for incremental reads. The pending-only restriction remains: this list does not become a history of dismissed reviews.

POST /api/v1/account-relationship-reviews/{review}/dismiss (api.v1.account-relationship-reviews.dismiss) requires accounts.edit, the accounts:write token ability, confirmed: true, and a non-blank operator reason of at most 1,000 characters. Only pending evidence can be dismissed. The command records an immutable disposition receipt and changes the review status to dismissed; the response identifies data.disposition as dismissed and includes data.receipt_id. The health report counts completed dismissals under relationships_under_review.relationships.dismissed.

Dismissal retains the original retained review payload. It does not restore the original relationship, change its endpoints, or authorise a new relationship. A non-pending review record is refused rather than dismissed again.

Rollback controls

Accounts rollback is a forward-fix process. Never deploy an older build that cannot read account versions, aliases, holds, receipts, privacy evidence, or credit decisions. Never restore erased or anonymised PII from a log, search/vector index, cache, export, backup, or merge preview. Repair the case state and retained legal references instead.

  • MergeAccount checks accounts.merge.accept_new (default true) and refuses new merges with account.merge.paused when it is false. The key is not registered in AccountSettings, so the settings screen and settings API cannot change it; to stop new merges without a code change, withdraw the accounts.merge permission from the roles that hold it. A retry of an already completed command still resolves through its immutable receipt, and existing aliases remain readable. Use the time-limited compensation plan only for references declared reversible; escalate irreversible conflicts for manual remediation.
  • Set accounts.credit.accept_new_exposure to false to reject positive exposure increases in every rollout mode. A valid, audited credit override is the only exception. Existing-obligation billing, non-increasing corrections, and returns remain available.
  • Run signals:accounts:repair expired-reservations in dry-run mode, review its counts, then apply it to explicit account IDs before reverting a commitment caller. This releases expired or orphaned reservations idempotently and preserves decision history.
  • Keep collision held records, reference/privacy manifests, aliases, merge receipts, privacy receipts, holds, and delivery evidence. They are the starting evidence for a corrected rollout, not disposable migration data.