Download the PHP package evolvex/laravel-invariant-sentinel without Composer

Laravel Invariant Sentinel

Continuous runtime verification of business invariants for Laravel 12 / 13.

Sentinel answers a different question from static analysis and request monitoring:

The request succeeded — but is the resulting business state actually valid?

A completed withdrawal may have a successful provider execution while its wallet debit is missing. Sentinel detects the broken runtime business state, records evidence, opens a deduplicated incident, retries within eventual-consistency windows, and automatically resolves the incident when the invariant becomes healthy again.

Requirements

• PHP 8.2+
• Laravel / Illuminate 12 or 13
• A durable database for Sentinel state
• A shared lock-capable cache (Redis recommended for multi-node production)
• A real queue driver for production

Install

Register invariants explicitly in config/sentinel.php:

or at application boot:

A production invariant

A check returns semantic status and evidence:

Status semantics

Sentinel deliberately does not model evaluations as boolean values.

This distinction prevents transient replication lag, delayed jobs, or unavailable external facts from becoming false critical incidents.

Durable trigger path

Triggers do not execute heavy checks in the HTTP path. They create/coalesce a record in sentinel_pending_checks and dispatch a drain job after commit. Multiple events for the same invariant + tenant + subject collapse into one pending check.

For production, run a worker for the Sentinel queue:

The durable table is the source of pending work; the queue message is merely a wake-up mechanism. If queue dispatch fails, Sentinel reports the error but leaves the durable pending row intact. A periodic sentinel:drain is therefore recommended as recovery protection.

Anti-entropy sweeps

Events can be lost, code paths can forget to dispatch them, and deployments can interrupt work. Critical correctness must have a second discovery path.

Recommended scheduler (or set sentinel.scheduler.enabled=true and use SweepTrigger definitions):

For very large datasets, implement ViolationFindingInvariant and return only subjects selected by a set-based violation query instead of hydrating every model.

Fact store

Cross-system facts can be recorded idempotently:

Checks can then use $context->facts without making live provider requests during a sweep.

Incident lifecycle

Sentinel stores three separate concepts:

• State: current health for invariant + tenant + subject.
• Observation: append-only evaluation history.
• Incident: one violation episode with open/acknowledged/resolving/resolved lifecycle.

Flapping is controlled by IncidentPolicy (openAfterFailures, resolveAfterPasses). Incident fingerprints exclude changing actual values, so actual=0 becoming actual=2 does not create a new incident for the same broken rule.

CLI

Safe remediation

Automatic repair is disabled by default. A remediable invariant implements RemediableInvariant and supplies a Remediation that first produces a deterministic RemediationPlan. The CLI is dry-run by default and requires both configuration enablement and explicit --execute plus confirmation.

Sentinel should never blindly convert missing debit into Wallet::debit(). Ambiguous remote operations must be reconciled before any irreversible repair.

Dashboard

Enable the optional read-only dashboard:

Then visit /sentinel. The default middleware is web, auth, and can:viewSentinel; define the viewSentinel gate in the host application before enabling the dashboard.

Multi-tenancy

Replace the default global tenant resolver:

Tenant identity is included in state, pending-work and evaluation lock keys to prevent cross-tenant coalescing.

Context propagation

The default context adapter captures known Laravel Context keys when available:

• correlation_id
• trace_id
• request_id
• actor_id
• tenant_id

You may bind ContextResolver to integrate a dedicated context propagation package.

Security and evidence

Evidence is recursively redacted according to sentinel.evidence.redact. Do not store secrets or raw card data as evidence. Dashboard authentication and authorization must be configured by the host application.

Database constraints still win

Sentinel is not a replacement for:

• UNIQUE
• foreign keys
• CHECK
• NOT NULL
• transactions
• row locks
• idempotency keys

If a rule can be guaranteed transactionally by the database, enforce it there. Sentinel is for cross-table, aggregate, eventual, legacy and cross-system correctness that cannot be represented safely as a local database constraint.

Testing

For real evaluation tests, either use the facade directly or the included InvariantTest harness:

Facade form:

Run package tests:

Production checklist

Run:

For multi-node production use a shared lock-capable cache (typically Redis), a durable queue, periodic sentinel:sweep, periodic sentinel:drain, evidence retention/pruning, and explicit authentication around the dashboard.

Architecture

License

MIT.