Skip to content

v0.5.0 — audit envelope settles, durability lands

Choose a tag to compare

View all tags
@dberry37388 dberry37388 released this 19 May 19:18
· 338 commits to main since this release
v0.5.0
0851416

Theme: the audit evidence envelope settles, and durability lands underneath it. v0.5.0 bundles four issues from the milestone — #21 SwarmRunner decomposition, #30 actor envelope unification + schema_version bump, #23 laravel/ai wrap behind Swarm\Contracts, and #20 audit outbox + queue/dead-letter failure policies.

Highlights

Added

  • Audit outbox + queue/dead-letter failure policies (#20). Sink failures can now be persisted to a new swarm_audit_outbox table and retried via swarm:relay --type=audit. The relay drains both durable and audit lanes in a single pass. SinkFailureDecision gains Queue and DeadLetter cases. ConfiguredSinkFailureHandler recognizes queue and dead_letter in addition to v0.4's swallow / log / halt. Dead-letter transitions emit Log::error for monitoring. Payload and last_error columns are sealed when swarm.persistence.encrypt_at_rest is enabled.
  • Opt-in audit outbox retention via swarm.audit.outbox.dead_letter_retention_days (default null — preserve indefinitely for regulated callers).
  • Audit outbox health checks. swarm:health runs staleness and dead-letter checks by default. New swarm:health --audit flag for focused investigation.
  • Swarm\Contracts\Agent and Swarm\Contracts\HasStructuredOutput marker interfaces (#23) wrap laravel/ai's pre-1.0 contracts so swarm has its own stability story. Migration required for custom agent classes — one-line use change documented in UPGRADING.md.

Changed (BREAKING)

  • swarm.audit.failure_policy defaults to queue (was swallow in v0.4). Run php artisan migrate on database persistence to create the outbox table. Cache persistence falls back to log-and-swallow automatically. Set SWARM_AUDIT_FAILURE_POLICY=swallow to restore v0.4 behavior.
  • EvidenceEnvelope::SCHEMA_VERSION bumps from \"1\" to \"2\" (#30). Shape change on command.* evidence only: legacy top-level 'actor' => 'artisan' literal removed; actor identity now in metadata.actor as an Actor value object array, matching every other category.
  • SwarmRunner decomposed into RunAuditEmitter, DispatchValidator, LeaseManager (#21). Internal refactor; public API unchanged.

Upgrade path

See `UPGRADING.md` v0.5.0 for the full migration checklist:

  1. `composer update builtbyberry/laravel-swarm`
  2. `php artisan migrate` (creates `swarm_audit_outbox`; required for the new default failure policy on database persistence)
  3. If you ignore `schema_version` in sinks: no action. If you pin a single value: update to accept `"2"` (and tolerate both during rolling deploys).
  4. If you have custom agent classes: switch `use Laravel\Ai\Contracts\Agent;` to `use BuiltByBerry\LaravelSwarm\Contracts\Agent;`. The swarm marker extends the vendor interface so existing methods continue to work unchanged.
  5. If you have a custom `SinkFailureHandler` with an exhaustive `match` on `SinkFailureDecision`: add cases for `Queue` and `DeadLetter` to avoid `UnhandledMatchError`.

Compatibility

  • PHP ^8.5
  • Laravel ^13.0
  • laravel/ai ^0.6

Full changelog

See `CHANGELOG.md` for the complete entry.

Assets 2
Loading