Verifying

Every entry point — the facade, the handle, the model trait, the middleware, the validation rule, the collection macro, verify-on-retrieve and the scans — reaches the same verifier and the same verdict:

use RoundlyConsulting\Sentinel\Enums\VerificationStatus;
use RoundlyConsulting\Sentinel\Facades\Sentinel;

$result = Sentinel::for($invoice)->verify();              // the default seal
$result = Sentinel::for($invoice, 'identity')->verify();  // a named seal
$result = Sentinel::verify($invoice, 'financial');        // the same, flat

$result->status;              // VerificationStatus::Intact, ::Tampered, …
$result->reason;              // 'mac', 'seal_deleted', 'newer_version', … (null when intact)
$result->changedAttributes;   // ['a:amount'] — names only, never values
$result->changedColumns();    // ['amount'] (and changedComputed() for c:* fields)
$result->onlyComputedChanged(); // only computed (c:*) values drifted — an explicit seal() re-seals that
$result->toArray();           // status, reason, ids, key, changed names — never values
$result->isIntact();

$invoice->isIntact();                                    // every seal
$invoice->verifySeal('identity');
Sentinel::verifyAll($invoice)->allIntact();              // VerificationReport over every seal
Sentinel::verifyMany($invoices, 'financial')->failures();
Sentinel::for($invoice)->verifyOrFail();                  // TamperedModelException when not intact

The action form takes a VerifyRequest; checkLedger: false skips the ledger comparison for that one call:

use RoundlyConsulting\Sentinel\Actions\Seals\VerifyModelAction;
use RoundlyConsulting\Sentinel\DataTransferObjects\VerifyRequest;

$result = app(VerifyModelAction::class)->execute(new VerifyRequest($invoice, 'financial', checkLedger: false));

The result

VerificationResult carries status, reason, the sealable type, id and seal, version and ledgerVersion, ring, keyId, algorithm, sealedAt, changedAttributes, context (a VerificationContext) and outdatedIsIntact. isIntact() is true for Intact, Unsealed and — with verification.outdated_is_intact, the default — Outdated; failed() is its negation, and toArray() never contains values. verifyAll() and verifyMany() return a VerificationReport with results, allIntact(), failures(), count(), counts() and throwIfTampered().

Statuses

Every failure fires TamperDetected (sync) and logs a warning to verification.log_channel — names only, never values. Verification is read-only: it takes no locks except inside a write’s pre-write check.

Status precedence

Evaluated in order; the first match wins. Statuses 6–11 are decided before any MAC is computed, and rows 15–18 run when verification.check_ledger is on (one indexed query):

Changed attributes

With an HMAC key and field tags on (the default), each seal stores keyed 128-bit tags per field. On a failed MAC the changed attributes are the fields whose recomputed tag differs, plus fields present on one side only. Tags are diagnostics: tampering with them only misleads the list — the seal still fails. Asymmetric seals store no tags, so changedAttributes is null.

Verify-on-retrieve

A seal declared with ->verifyOnRetrieve(Reaction::Throw) verifies every retrieved model: Throw reports the finding (TamperDetected and a log line) and throws TamperedModelException; Report reports and lets the model load. Without an explicit reaction, verification.retrieve_reaction applies. The ledger check is off on retrieve unless verification.retrieve_checks_ledger is on, and a partial select() that leaves out the seal’s own columns is skipped. Sentinel::withoutVerification() suspends it, and Sentinel::model(Invoice::class)->find($id) loads a tampered row on purpose (see Acknowledging changes).

Scans

Sentinel::model($class)->scan() verifies every row in chunks, soft-deleted rows included. A where closure (or a builder of that model) narrows the scan of one model without loading it into memory — it filters, never orders — and a progress callback receives the rows processed after every chunk:

$report = Sentinel::model(Invoice::class)->scan('financial', chunk: 500);
$report->scanned;          // rows × seals verified
$report->counts;           // list<StatusCount>
$report->findings;         // up to maxFindings VerificationResult
$report->truncated;
$report->hasFindings();                                                         // any failure
$report->hasFindings(VerificationStatus::Tampered, VerificationStatus::Missing); // only these
$report->count(VerificationStatus::Outdated);

$report = Sentinel::model(Invoice::class)->scan(where: fn ($query) => $query->where('tenant_id', 7));
$report = Sentinel::model(Invoice::class)->scan('financial', where: Invoice::query()->whereYear('created_at', 2026), limit: 10_000);

Sentinel::scan(new ScanOptions(models: […], seal: null, chunk: 500, checkLedger: true, limit: null, maxFindings: 1000, checkSchema: false, where: null, progress: null)) is the general form, and sentinel:verify wraps it.