Message Repository For Illuminate Laravel Package

Product Decisions This Supports

• Build vs. buy for event-sourced persistence. This package is the thin "glue" layer: it implements EventSauce's MessageRepository contract (append, load full stream, load after version) over Laravel's Illuminate\Database connection. The decision it unlocks is not "should we build an event store" but "should we spend sprint time on domain modelling instead of writing and maintaining a ~hundred-line repository adapter." It is cheap enough that the honest comparison is against an internal spike, and the answer is usually to adopt, pin, and move on.
• Whether to put event sourcing on the roadmap at all. Because the adapter is small, replaceable, and requires no second datastore, it lowers the cost of a scoped pilot — one bounded context, one aggregate, audit trail only — before committing the wider product to CQRS and event sourcing. This is the decision the package most directly de-risks: an affordable try-before-you-commit.
• Roadmap capabilities it makes reachable. An append-only audit and compliance log, temporal queries ("what did this record look like in March?"), replayable state after a bad deploy, outbox-style integration with Laravel queues and jobs, and read-model projections built off the same stream. None of these are features of the package, but each becomes a wiring exercise rather than a platform project once the stream is in your existing database.
• Storage portability as a deliberate strategy call. Domain code talks to EventSauce's interface, never to this package. "Laravel DB today, Doctrine DBAL or a managed event store later" stays a reversible binding change rather than a re-platforming programme. That keeps the architecture decision reviewable at each stage instead of being a one-way door.
• Dependency and governance posture. Small surface area, no SaaS contract, no second operational datastore. The trade is that the dependency is a read-only sub-split publishing artifact from the EventSauce monorepo, so the decision to adopt carries a companion decision: who owns tracking upstream releases, how versions are pinned, and whether we keep a fork as fallback.

When to Consider This Package

Adopt when:

• You are on Laravel (or another Illuminate app) and have already chosen or are actively piloting EventSauce for a bounded context. This package is not a general-purpose event store and adds nothing without the core library and a serializer.
• You want message persistence on your existing MySQL/Postgres/SQLite connection via illuminate/database — not a parallel Doctrine connection, not a second datastore, and you value inheriting Laravel's connection pooling, read/write splitting, and multi-database config for free.
• Your access pattern is straightforward: append a message stream, load it by aggregate and version. Audit trails, moderate write volumes, single-tenant or simple isolation.
• You want the domain layer to stay framework-free. The adapter is a boundary, not a leak of Eloquent into your aggregates — there are no models, observers, or model events involved.
• Your team would rather own a small integration than own a persistence subsystem, and you are willing to hand-write the migration and the unique index that the package deliberately does not ship.

Look elsewhere — or budget to write your own adapter — when:

• Read the health signals correctly first. Zero stars and zero dependents are an artifact of the sub-split packaging model, not proof of abandonment; the real signal is the parent EventSaucePHP/EventSauce monorepo. If the parent is not releasing and this split is not being re-synced, treat the package as unmaintained and plan accordingly.
• You need high write throughput, partitioning, streaming reads, or snapshots at scale. The repository contract is deliberately simple, and sharding, retention, and replay-cost control become your problem.
• You expect Eloquent ergonomics on the event table — relationships, HasUuids, soft deletes, query-builder convenience. Everything model-like must be reimplemented at the repository boundary.
• You need multi-tenancy enforcement, per-stream encryption at rest, or schema/versioning guarantees. None ship out of the box; per-tenant connections are possible but you own the wiring.
• You require commercial support, SLAs, or a vendor to escalate to. Support is community-only via the monorepo tracker, and PRs cannot be filed against this repository.
• Laravel's native events plus an audit-log package already satisfy the requirement. Do not adopt event sourcing to solve a logging problem — the operational discipline it demands (immutability, versioning, projection rebuilds) is disproportionate to that need.

How to Pitch It (Stakeholders)

For executives: this is a small, free, open-source integration component that lets us evaluate event sourcing — and the audit trail, replay, and point-in-time reporting it enables — without buying a platform or standing up a second database. It runs on the database we already operate. The downside is deliberately bounded: days of integration effort, one new table, and no vendor lock-in, because our domain code depends on an abstraction rather than on this package. The one governance caveat is that it is a read-only published artifact mirrored from an upstream project, so we should pin the version, assign an owner to watch upstream releases, and treat a fork as an inexpensive fallback. Recommendation: fund a time-boxed pilot on one non-critical bounded context, measure it against the audit-trail use case, and decide on wider adoption before expanding scope.

For engineering: this supplies the MessageRepository implementation for EventSauce backed by Illuminate's database connection — essentially one class plus a serializer contract, with no service provider, no config file, and no published migration. You own the schema: an aggregate root id, an aggregate root version, and a serialized payload/headers column, plus a unique index on (aggregate root id, version) — without which optimistic concurrency is advisory only and silent stream corruption is possible. The adapter never manages transactions and does not participate in Eloquent lifecycle hooks, so wrap writes in DB::transaction(), map duplicate-key violations to a retry or a domain-level conflict (eventsauce/backoff pairs well here), and be aware that loading replays the full stream unless you layer snapshotting separately. Because this is a read-only sub-split, verifying behavior means reading the parent monorepo's tests, and a serializer change is a data migration, not a dependency bump. Sequence it: spike append/reload/conflict behavior on SQLite in CI, harden the index and concurrency mapping, pilot one aggregate behind a feature flag, and only then expand.