Contracts Laravel Package

Product Decisions This Supports

• Platform standardization, not package adoption. orchestra/contracts is an interfaces-only package — extension discovery, application access, shared memory, authorization bridging, notifier and widget abstractions — with zero runtime behavior, no service provider, no config, no routes. The decision it actually informs is whether we standardize our Laravel admin/extension layer on the Orchestra Platform. It does not support a feature or roadmap decision on its own.
• Exit-path insurance for the admin layer. Contracts separating abstractions from implementations mean feature modules coded against the interfaces can be re-platformed without a rewrite — but only if engineering codes against Orchestra\Contracts\* rather than concrete orchestra/foundation classes. This lets us responsibly make the roadmap claim "our admin layer is swappable," conditional on that discipline being enforced in code review.
• Scoping third-party compatibility commitments. Any roadmap item promising "our Laravel packages plug into an Orchestra-based host" must be scoped against this contract surface. It is the sanctioned integration point; committing to Orchestra compatibility without naming it is an unscoped promise.
• Build-vs-buy / fork-vs-depend. MIT-licensed, small file count, stable in shape. For a product team that wants only the interface vocabulary but not the platform, vendoring the interfaces into an internal namespace is a legitimate, costed alternative that eliminates upgrade-gating risk. Decide this before we need it, not under pressure.
• Dependency-footprint as (modest) positioning. Keeping abstractions in a zero-runtime package rather than forcing consumers onto the full platform is a small differentiator for library-style products where install cost is part of the pitch. Worth noting; not worth building a narrative on.
• Ecosystem-risk register entry. Zero stars and zero dependents is low independent adoption evidence — likely a Packagist artifact, since Orchestra's own components necessarily require it. Log it as an unknown, not proof of abandonment. Either way, it argues against putting this package on a critical launch path or behind a customer-facing capability.

Recommendation: Hold / do not adopt as a new dependency unless an Orchestra commitment already exists. Its value is derivative of that platform decision, not independent of it. If we do adopt, pin deliberately, name an owner for the upgrade cadence, and decide the vendored-fork fallback in advance.

When to Consider This Package

Adopt only when all of the following hold:

• We have already committed to Orchestra Platform (or Orchestra Testbench for package testing) and need to type-hint or implement its extension points.
• We are publishing a package into the Orchestra ecosystem and want the narrow contract surface rather than a dependency on the full platform.
• We are deliberately isolating an abstraction layer so a future reimplementation doesn't ripple through feature code — and we will actually enforce coding against interfaces.
• The team accepts a single-maintainer, near-zero-adoption dependency and has pre-agreed appetite to fork or vendor it if upstream stalls.
• A composer why-not orchestra/contracts check against our target Laravel version passes. That single command answers go/no-go faster than any README; make it a CI pre-merge check to catch illuminate range collisions early.

Look elsewhere when:

• We are not on Orchestra. Laravel's native Illuminate\Contracts\* and PSR interfaces cover the general cases; spatie/laravel-package-tools covers package scaffolding with far broader community support and needs no justification.
• We need a supported, actively-maintained contract layer. Zero dependents means no downstream pressure to keep pace with Laravel majors. The most probable real-world failure is an upgrade block waiting on an upstream tag — a cost we absorb on the maintainer's schedule. Budget roughly an engineer-hour per Laravel major plus the wait we don't control.
• We need portability beyond Laravel. The interfaces reference illuminate types (Illuminate\Contracts\Foundation\Application, Illuminate\Support\Collection), so moving to a non-Laravel container is a rewrite, not a swap. A hand-written narrow interface set is a cleaner boundary if framework-agnostic ports are the goal.
• The concrete Orchestra packages are already a hard dependency. Adding contracts at that point buys architectural tidiness, not optionality. Audit first for transitive Orchestra — if a dependency already pulls it in, we're managing this pin regardless.
• It is being evaluated standalone. It has no value in isolation; it is only meaningful inside the Orchestra graph and cannot be meaningfully piloted without the implementation packages. Version branches track Laravel majors (v7 tracks Laravel 9).

Planned mitigations if adopted: pin via a shared internal package or Composer platform constraint so one upstream major bump doesn't fan out into N coordinated upgrades; add a conformance test asserting our adapters implements the interfaces so signature drift fails in CI rather than as a fatal type error at boot; and write the fork procedure into the runbook before we need it.

How to Pitch It (Stakeholders)

To executives: This is a small, free, MIT-licensed glue package — a set of interface definitions from the Orchestra Platform, a Laravel admin/extension framework. It adds no features and no runtime code; it exists so components can talk to each other without hard dependencies. It costs essentially nothing to use and delivers nothing on its own. External adoption is effectively zero, meaning one maintainer is the whole support model. The decision actually on the table is not this package: it is whether we standardize on Orchestra as our Laravel admin layer. If we do, this comes along for free; if we don't, we should skip it and use Laravel's native contracts. Runtime risk is nil; the risk is strategic — upgrade timing we don't control, which we address by pinning versions and pre-approving a cheap fork fallback.

To engineering: Treat it as an architectural boundary, not a capability. It is interfaces-only, safe to depend on narrowly, and trivially reversible to install — but pin it, expect to own the upgrade cadence across Laravel majors, and keep it off any critical path given the single-maintainer, zero-dependent profile. If we adopt Orchestra, code against these contracts rather than the concrete classes so the exit path is real; resolve implementations from the container rather than naming concrete Orchestra classes. If we don't, Illuminate\Contracts plus PSR is the lower-risk default.

Three things to plan around: upgrade gating (a Laravel major ships while the matching branch lags — mitigate with a pre-decided vendored fork), semantic drift (an interface signature change surfaces as a fatal type error in our implementing classes at boot — mitigate with our own conformance test asserting the interfaces we implement), and dependency conflicts (illuminate range collisions — mitigate with composer why-not as a CI pre-merge check). Sequence the work as: dependency audit (hours) → confirm Orchestra commitment → pin with a named owner → conformance test → fork procedure documented. Allocate an afternoon of ramp-up for anyone fluent in Laravel contracts and container binding; the hidden cost is understanding Orchestra's extension, memory, and widget semantics, which requires reading the implementation packages, not this repo.