Monitor Laravel Package

Product Decisions This Supports

• Turning "reliability" from a debate into a reviewable spec. A control point is a named, owned contract for one operation that matters: what it tolerates (recover), what it guarantees (ensure), how long it may take (within), how many retries it gets (attempts), and who gets paged (escalate). monitor:points --check in CI can fail the build on duplicates, names off the agreed pattern, a point with no escalation and no catch-all, and any class in a critical namespace that isn't a control point. That converts "did we cover the risky paths this release?" from a retro argument into a green/red gate a PM can point at in release sign-off. The SARIF output means the findings land in the existing code-scanning UI rather than a new dashboard nobody opens.
• Build vs. buy on resilience plumbing. Backoff retry with jitter, deadlock-safe transaction retries, cache-backed circuit breakers, idempotency (once('invoice:'.$id, ttl: 3600)), and escalation ship as one fixed, documented pipeline (breaker → retry → transaction). The fixed order is the actual product decision — a breaker sees one failure per run, so your on-call math isn't inflated by retries. That's a defensible "adopt, don't hand-roll" memo against the try/catch archaeology most services accumulate, and far cheaper than funding a platform squad to rebuild it.
• Graceful degradation as an explicit, reviewable decision. recover(CardDeclined::class, fn ($e) => ChargeResult::declined($e->code)) puts "declined cards return a typed result; an outage pages payments on-call" into a diff instead of an implicit catch block. null, false, and 0 are valid handler results, so "show a placeholder avatar" vs. "fail the page" becomes a per-surface choice someone can review and reverse. ensure() runs after every policy and is never retried — the correct semantics for "it technically succeeded but the result is wrong," which is where most money bugs live.
• Prioritising hardening work with evidence. Outcome plus eleven typed events plus an optional monitor_outcomes table give you per-point status, attempts, duration, limits breached, and a timeline, queryable by domain. "Which of our critical flows do we actually retry the most, and which ones breach their time budget?" becomes a query, not an anecdote — a legitimate input to quarterly roadmap sequencing (fix the payment path before the notification path). The store is off by default and writes off the request path, so measurement doesn't create a new latency or availability risk.
• On-call and incident policy you can encode. Circuit breakers are a real shared state machine (closed/open/half-open with a single probe in cache), and throttleEscalation() caps page volume to one per point per window. That's how a PM defends "we don't want 4,000 Slack pings during a Stripe incident" without arguing about it mid-incident. Http::breaker('stripe') extends the same circuit to raw HTTP calls, so the policy holds even outside a formal control point.
• Sizing the AI-assisted-development investment. Shipped agent guidelines (Boost-composed), a read-only MCP server exposing list_points/explain_point/outcomes/escalations, a generation command (make:control-point emits the class and a fake-based test), a Pest expectation, and a PHPStan rule all attack the same adoption cost: the second and third engineer declaring a point correctly without a reviewer explaining the convention. This is a real lever on team throughput, not a novelty — but see adoption caveats below.
• Positioning caution that is itself a decision input: the package blurb describes "lightweight health checks," while v1.0.0 is a control-point/reliability framework with no compatibility layer from 0.1. Treat the marketing copy as stale and evaluate the release notes. If you were shopping for uptime/health-check tooling, this is not that package.

When to Consider This Package

Strong fit when:

• You are on Laravel 12 or 13 and PHP 8.3–8.5 (hard requirement; Laravel 11 is dropped — check this before spending evaluation time).
• You have a handful of genuinely critical operations — payments, filings, ledger entries, third-party state mutation, emails a user is actively waiting on — and the failure stories are currently implicit in scattered try/catch blocks.
• You already run CI with PHPStan and Pest; the monitor.uncontrolled rule and toBeControlled() expectation only pay off if those gates exist.
• You have no platform/SRE squad to own bespoke resilience primitives, and one or two engineers can own the convention.
• You want the contract to survive personnel changes: the inventory (monitor:points), monitor:explain, and the generated tests mean the "why" is machine-readable rather than tribal.
• You are already using or evaluating Laravel Boost / MCP-based agent workflows; the guideline and skill are effectively free.

Look elsewhere when:

• You want observability, not contracts. If the need is traces, spans, error aggregation, and dashboards across services, buy Sentry / Honeycomb / Datadog / Laravel Nightwatch. Monitor emits a trace id and W3C traceparent and writes NDJSON, but it is not an APM — don't let it become the answer to "we can't see production."
• You need supported, long-lived dependencies. 3 stars, 0 dependents, and a from-scratch 1.0 with an explicit no-compatibility-layer stance is real adoption risk. Mitigations exist (MIT license, single well-known Laravel consultancy behind it, thin surface), but budget for pinning the version and reading upgrade notes every minor, or forking the pieces you need.
• You need uptime/health-check endpoints. Wrong package, despite the blurb. Use spatie/laravel-health or Laravel's built-in health route.
• You are polyglot or non-Laravel. The value is concentrated in first-party integration (Context, queues, kernels, Octane-safe flushing). A Node or Go service gets nothing.
• Your team won't adopt opinionated conventions. The package's leverage comes from everyone declaring points the same way. If the org can't enforce the --check gate as a merge blocker, you get a dependency and a half-used framework.
• You need distributed transaction semantics or exactly-once delivery. once() is a cache-backed TTL idempotency key, not a durable outbox. If correctness depends on guaranteed single execution across failures, you need a different architecture.

How to Pitch It (Stakeholders)

To executives (one paragraph): A small, MIT-licensed Laravel package that makes our riskiest operations — charging cards, filing with a regulator, calling a third party — declare up front what they tolerate, what they guarantee, how long they may take, and who gets paged. The practical value is a CI gate: we can state, release by release, that every money-moving or promise-breaking path has a declared failure story, instead of discovering gaps in a postmortem. It also replaces hand-rolled retry and circuit-breaker code with one documented pipeline, and records every outcome so hardening work can be prioritised by evidence. No new infrastructure, no per-seat cost. The honest caveat: it is young and thinly adopted, so we adopt it behind a pinned version with a contained blast radius, and we do not treat it as a replacement for error monitoring.

To engineering: One fixed pipeline (breaker → retry → transaction) instead of bespoke try/catch. Two entry points per point — run() returns the value or throws, attempt() returns an immutable Outcome and never throws — so business logic and diagnostics don't fight. Nesting carries parent run id and stack; jobs start clean with dispatched_from_run instead of leaking a foreign parent across processes. Monitor::fake() is a proper framework Fake with positive and negative assertions and canning. make:control-point generates the class and a test that already passes. Events are the source of truth; logs and the DB store are just listeners. Provider does nothing at boot; store flushes after the response, never on the request path. PHPStan rule and Pest expectation mean enforcement is static, not a code-review opinion.

To security / compliance: Context and exception messages pass through Redactor while identifiers are preserved, so records stay joinable without leaking PII; redaction failure degrades and never blocks a control point. The record schema is versioned and published (monitor/1), with origin and domain as first-class fields for audit queries. The MCP server is read-only, off by default, and redacts per response — safe to leave disabled until someone explicitly wants it.

To whoever owns the risk: the ask is a two-week spike on one domain (payments), a pinned version, and one named owner of the --check gate. If the spike doesn't produce cleaner failure semantics than what exists, we drop the dependency — it's a library, not a migration.