Verbs History Laravel Package

Technical Evaluation

Architecture fit

• hirethunk/verbs-history is a companion package to hirethunk/verbs, the event-sourcing framework for Laravel. It adds history/audit-trail capture (state snapshots per aggregate) on top of Verbs' event store. It is not a standalone capability — it inherits Verbs' architecture, service-provider registration, and aggregate/projector conventions.
• Fit is good only if the platform already uses (or plans to use) Verbs for event sourcing. For teams on plain Eloquent, adopting this means adopting Verbs first: a significant architectural commitment (aggregates, projectors, reactors, event upcasting, replay semantics), not a bolt-on audit log.
• v0.6.0's sole change is aligning with Verbs v0.6, which confirms the package is deliberately version-locked to the core framework. Coupling is by design and is the dominant architectural fact about this dependency.

Integration feasibility

• Low-friction mechanics: Composer install, Laravel package auto-discovery, publish config/migrations, apply a history trait to aggregates/models. Typical install is hours, not days.
• Real effort sits in the Verbs prerequisite: event-sourcing literacy, projection design, and backfilling history for pre-existing records (history only exists from the point capture is enabled forward).
• v0.6.0 is an alignment release, so it is only adoptable alongside a Verbs v0.6 upgrade — treat the two as a single, coupled change.

Technical risk

• Pre-1.0 volatility: both packages are 0.x. Semver gives no stability guarantee; minor bumps can and do break. v0.6.0 is a minor version that changes the core dependency constraint, which is itself a breaking-adjacent event for anyone pinned to Verbs 0.5.x.
• Constraint collision: installing this release forces verbs ^0.6. Any other package or internal code pinned to Verbs 0.5.x will block the resolver or force a wider upgrade.
• Upgrade blast radius: Verbs 0.6 may alter event payloads, projector behavior, replay, or snapshot formats. The history package consumes that state, so history rows written under 0.5.x may not render or replay identically post-upgrade.
• Bus factor / governance: small maintainer set (Thunk + community contributors; v0.6.0 is a first-time contributor's PR). No vendor SLA, no LTS, no published deprecation policy.
• Unbounded growth: history tables are append-only and grow with every state change, not every business event. This is a storage and query-cost risk that surfaces months after launch, not at install.

Key questions

1. Does Verbs v0.6 ship breaking changes to event payloads, snapshots, or replay? Is there an upcaster/migration path for streams written on 0.5.x?
2. Does verbs-history v0.6.0 require a schema migration or backfill of the existing history table, or is it drop-in?
3. Is there a supported pruning/retention/archival mechanism for history rows, and what is the recommended index strategy for large aggregates?
4. What is the maintainers' path to 1.0 and their stated compatibility policy between verbs and verbs-history minor versions?
5. Is history captured inside the same DB transaction as the event append? (Determines whether history can silently diverge from the event store.)
6. Any published benchmarks for history read/write at 10M+ rows?
7. Is there a clean fallback if we need to remove the package later, or does history data become load-bearing for auditing/compliance?

Integration Approach

Stack fit

• Requires Laravel (10/11-era), PHP 8.1+, and hirethunk/verbs ^0.6. Confirm the host app's Laravel/PHP matrix against Verbs v0.6 before committing.
• Best fit: greenfield or actively-evolving services where event sourcing is already the chosen pattern, and where an audit/history trail is a product or compliance requirement rather than a nice-to-have.
• Poor fit: CRUD applications, teams without event-sourcing experience, or systems with hard stability requirements (regulated, multi-year support windows).

Migration path

• v0.6.0 is an alignment release, not an additive feature — there is no partial adoption. The upgrade path is: pin and test Verbs v0.6 in isolation, then bring verbs-history to v0.6.0, then validate existing history rendering and replay.
• For existing Verbs 0.5.x deployments, budget a dedicated upgrade ticket with a rollback plan (DB snapshot + tagged release), not a routine dependency bump.
• For new adopters, install both packages at matched versions from day one and record that pairing in the repo (e.g. a compatibility note in the README or an ADR).

Compatibility

• Hard constraint: verbs-history v0.6.0 ⇄ verbs ^0.6. Verify whether the constraint is ^0.6 or 0.6.* — the former tolerates future 0.6.x patches but also any behavioral drift within them.
• Audit the full dependency tree for anything else pinned to Verbs 0.5.x before attempting the upgrade; resolve those first.
• Confirm DB portability (MySQL/Postgres/SQLite) for the history migrations — JSON column support differs and affects indexing/query strategy.

Sequencing

1. Spike: install Verbs v0.6 + verbs-history v0.6.0 in a sandbox; replay a representative event stream.
2. Verify history schema and whether a data migration is required.
3. Resolve any transitive packages pinned to Verbs 0.5.x.
4. Upgrade in a branch: bump Verbs → bump verbs-history → run migrations → run replay/projection tests → diff history output against pre-upgrade snapshots.
5. Ship behind a feature flag if history feeds user-visible UI; monitor write latency and table growth for the first two weeks.
6. Document version pairing and add a CI check that asserts verbs and verbs-history minor versions stay aligned.

Operational Impact

Maintenance

• Expect recurring, non-optional maintenance: every Verbs minor bump will require a corresponding verbs-history bump, and lag between the two will block your upgrades. Treat the pair as one dependency with a shared upgrade cadence.
• Pin exact versions in composer.json and rely on automated dependency alerts plus a periodic manual review of the upstream changelog — pre-1.0 packages do not reliably signal breakage through semver alone.
• Low code footprint on our side (a trait plus config), so most maintenance cost is upgrade coordination, not patching.

Support

• Community-only: GitHub issues and PRs from a small maintainer group. No vendor contract, no SLA, no guaranteed security response.
• Mitigation: keep an internal fork-and-patch capability warm, and ensure at least one engineer can read the package source. It is small enough that this is realistic.
• If history becomes compliance-critical (audit trail, regulatory retention), the absence of vendor support is a material risk that should be escalated before adoption, not after.

Scaling

• Write path: one history row per tracked state change, added to the same request/transaction as the event append — expect measurable write amplification on hot aggregates. Benchmark before launch.
• Read path: history timelines are typically "latest N for aggregate X" queries; composite indexes on (aggregate type, aggregate id, recorded_at) are essential.
• Storage: append-only tables grow monotonically. Define retention and archival policy up front — partition by date, archive cold rows to object storage, or prune by policy where audit retention allows.
• Replay/hydration cost grows with history size if history is used to reconstruct state; prefer event-store replay with history as a read-side audit view rather than a source of truth.

Failure modes

• Silent divergence: if history writes are not transactional with event appends, history can drift from the event store — the worst failure for an audit feature because it is invisible until an investigation.
• Upgrade deadlock: a transitive package pinned to Verbs 0.5.x blocks the v0.6.0 upgrade mid-sprint.
• Replay regression: Verbs 0.6 behavior changes render 0.5.x-era history rows incorrectly or throw on hydration.
• Unbounded table growth degrading query latency and backup/restore windows months post-launch.
• Abandonment: upstream stalls pre-1.0; we are left maintaining a fork with no upgrade path.
• Each of these needs a detection signal: history-vs-event-store reconciliation check, dependency CI gate, post-upgrade replay test suite, table-size alerting, and a documented fork procedure.

Ramp-up

• Engineer time to first working integration: roughly 1–2 days for someone already fluent in Verbs; 1–2 weeks for a team new to event sourcing, dominated by conceptual ramp (aggregates, projectors, replay, idempotency) rather than this package's API.
• TPM should budget: one spike, one dedicated upgrade ticket per Verbs minor release, and ongoing ownership assigned to a named engineer.
• Onboarding docs should capture the version-pairing rule, the retention policy, and the reconciliation check — these are the three things a new maintainer will otherwise get wrong.