Laravel Assignment Laravel Package

Product Decisions This Supports

• Shipping "safe to leave running" automation. This package handles offers, assignment queues, expiry notifications, and a scheduled assignment:tick. Release v1.0.1 is almost entirely about making those loops not silently rot — expired offers now actually notify their assignee, and queue rows for deleted models get cleaned up instead of accumulating forever. That is the difference between a feature we can enable by default and one we have to babysit.
• Support-cost and on-call load. Two of these fixes remove quiet, hard-to-diagnose failure modes: a user sitting on an expired offer with no offer_expired notification (looks like "the app forgot me"), and an ever-growing queue of orphaned entries (looks like "the tick is slow / the table is huge"). Both generate tickets that look like product bugs but are actually library bugs. Worth folding into our reliability budget rather than building our own.
• Build vs. buy. The library now takes a firm stance on invalid configuration — zero/negative TTL and empty-string role throw rather than producing a pre-expired offer or a phantom default slot. That is exactly the kind of guardrail we would have had to write ourselves, and it argues for buying/keeping this dependency instead of an in-house assignment queue.
• Contract clarity for our own code. The '' vs null role bug is a data-modeling ambiguity we would have replicated: reads filtered on role = '' while writes shared the default slot with null, so assignee('') and assignee() disagreed about the same slot. Having the library reject '' outright means our role handling must be explicit — a decision to encode in our integration layer, not scatter across call sites.
• Roadmap signal — no new capability. This is a hardening patch: no new features, no new APIs to expose to users. Do not schedule user-facing work against it; schedule verification work.

When to Consider This Package

• Adopt if we need offer/assignment semantics with TTL-based expiry, an assignee notification on expiry, a queue with a scheduled drain (assignment:tick), and we want someone else to own the tick/queue/expiry edge cases. Also if we want a library that fails loudly on bad configuration rather than degrading quietly.
• Upgrade to v1.0.1 promptly if already using it, but treat it as a behavioral change despite the patch version:
  • Code paths that previously created an already-expired offer (TTL ≤ 0) now throw InvalidArgumentException — including indirectly, because a profile whose offerTtl() returns ≤ 0 now makes autoAssign(), flushQueue(), and assignment:tick throw. A single misconfigured profile can take down the scheduled tick, not just one request. Audit every offerTtl() implementation and every offer()/expiresIn() caller before deploy.
  • Any caller passing '' as a role now throws on both read and write. Search for empty-string roles coming from request input, CSV imports, or nullable columns defaulting to '' — these will move from "works, sort of" to a 500.
• Look elsewhere if we need role hierarchies beyond a simple slot model, per-offer custom notification channels, distributed queueing guarantees, or if our product genuinely needs to represent "offer that is already expired" as a valid state (e.g. historical backfill/import tooling) — this release deliberately forbids that.
• Don't adopt just for this patch if we haven't validated the core model; the fixes reduce operational drag but add no capability.

How to Pitch It (Stakeholders)

For executives: v1.0.1 is a stability release for the assignment/offer engine, not a feature release. It fixes three things that were causing silent, ticket-generating failures: users were not being notified when their offer expired, deleted records left permanent junk in the assignment queue, and invalid configuration quietly produced already-expired offers. No new functionality, no user-visible changes, low effort — but it is a patch version with real behavior changes, so we need a short audit before rollout.

For engineering: Four changes, all correctness fixes, all with upgrade implications. (1) Assigning or offering over an expired offer now dispatches OfferExpired, so the assignee actually gets the offer_expired notification. (2) flushQueue() and assignment:tick now delete queue entries whose assignable model no longer exists — previously unbounded queue growth. (3) offer() and expiresIn() throw InvalidArgumentException for TTL below one second; a profile whose offerTtl() returns ≤ 0 will now make autoAssign(), flushQueue(), and assignment:tick throw — this is the highest-risk item, because it can break the scheduled job, so validate all offerTtl() implementations and add a guard/test. (4) Empty-string role now throws on read and write; previously '' shared the default slot with null on write but filtered on role = '' on read, so assignee('') and assignee() silently disagreed. Action items: grep for offerTtl, offer(, expiresIn(, and '' role arguments; add tests for TTL ≤ 0 and empty-role inputs; deploy behind the normal migration window and watch the tick for exception spikes.