Recomputing scores.

Use the recompute command when time-window signals need a fresh value, after changing score definitions, or after rebuilding the summaries table.

Recompute every score

php artisan customer-health:recompute

The command finds distinct subject identities present in raw events or milestones. It resolves each Eloquent model and computes every registered score.

Each successful computation appends score history and updates its current summary. An unchanged state still creates history and dispatches HealthScoreComputed, but it does not dispatch another HealthStateChanged.

Recompute one score

Pass the registered score name:

php artisan customer-health:recompute --score=customer_health

The value must match HealthScore::name(). A missing score returns a command failure before any subjects are processed.

Recompute one subject

Use the stored morph type and ID separated by the first colon:

php artisan customer-health:recompute \
  --subject='team:42'

If the application does not use a morph alias, pass the model class:

php artisan customer-health:recompute \
  --subject='App\Models\Team:42'

Combine --subject and --score to compute one definition for one customer. The subject must already appear in a product event or milestone.

Change the chunk size

The default is 500 known identities per database query:

php artisan customer-health:recompute --chunk=100

--chunk must be a positive integer. A smaller chunk lowers peak memory at the cost of more queries.

Handle partial failures

The command reports a failed subject and continues with the remaining chunks. Its exit code is non-zero when any subject fails.

Common subject failures include:

• the stored morph type no longer resolves to an Eloquent model;
• the model no longer implements Trackable;
• a signal throws or returns a value outside 0 through 100; or
• a storage or score lock operation fails.

Monitor the command's exit code and output. A successful count does not include failed subjects.

Schedule recomputation

Register the cadence in routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('customer-health:recompute')
    ->hourly()
    ->withoutOverlapping();

Choose a cadence based on the shortest activity window and how quickly state changes need to appear. The package does not schedule the command itself.

In a database-per-tenant application, run the command inside each tenant context. The known-subject query reads the configured package connection.

Watch retention windows

When retention_days is shorter than any registered WindowedSignal, the command prints a warning. The score still computes, but pruned events no longer contribute to that signal.

Built-in windowed signals are RecentActivity, FeatureActivity, and DistinctActors.

Rebuild summaries

If current summaries are missing, truncate or repair the summaries table and run recomputation. Each computation upserts the current summary from the new result.

The command recalculates signals from current application and package data. It does not copy the latest historical score into the summary.

What to read next

• Health scores for signal windows and state transitions.
• Retention and erasure to align pruning with score windows.
• Console commands for every option and exit behavior.