Contracts Laravel Package

Technical Evaluation

Architecture fit. orchestra/contracts is an interfaces-only package — no service provider, no config, no routes, no runtime code. Its architectural value is entirely derivative: it only makes sense inside the Orchestra Platform graph (or Orchestra Testbench), where it lets components depend on stable abstractions (extension discovery, application access, shared memory, authorization bridging, notifier, widget) instead of on concrete orchestra/foundation classes. For a TPM, the meaningful framing is that adopting this package is really a proxy for the larger decision: do we standardize our Laravel admin/extension layer on Orchestra? If that answer is no, this package delivers nothing on its own and should be skipped in favor of Illuminate\Contracts\* plus PSR.

Integration feasibility. Low-effort to install (composer require orchestra/contracts:^7.0, matching Laravel 9), but the real gate is a single command: composer why-not orchestra/contracts against our target Laravel major. That check takes minutes and answers go/no-go faster than any README. If we are not already on orchestra/foundation or orchestra/testbench, integration effort is not justified — the package adds a dependency without adding a capability.

Technical risk. Three risks dominate, none of them runtime bugs:

1. Upgrade gating. Version branches track Laravel majors (v7 → Laravel 9). The most probable real-world failure is a Laravel major shipping while the matching Orchestra branch lags — a schedule risk we absorb on the maintainer's calendar, not ours.
2. Signature drift. The package ships no published BC policy and no signature-assertion suite. A "minor" interface change surfaces as a fatal type error in our implementing classes at boot. Mitigation is our own conformance test asserting implements plus constructor/method signatures.
3. Portability does not hold. The interfaces reference Illuminate\Contracts\Foundation\Application and Illuminate\Support\Collection. If the intent was framework-agnostic ports, this package does not deliver it.

Secondary signals — zero stars, zero dependents — are almost certainly a Packagist artifact (Orchestra's own components necessarily require it), so log them as an unknown, not as proof of abandonment. Either way they argue against putting this on a critical path.

Key questions for the review. (1) Have we already committed to Orchestra, or are we evaluating this in isolation? (2) Will feature code be enforced to type-hint the contracts rather than the concrete foundation classes — through code review, not just intent? (3) Who is the named owner of the pin and the Laravel-major upgrade mapping? (4) Have we decided the vendored-fork fallback in advance? (5) Does this sit on any capability whose release it could block?

Integration Approach

Stack fit. Laravel-only by construction, given the illuminate type-hints. Fits when we are (a) building or publishing a package into the Orchestra ecosystem and want the narrow contract surface instead of depending on the full platform, or (b) deliberately isolating an abstraction layer so a future re-platform doesn't ripple through feature modules. It does not fit a general Laravel codebase; Illuminate\Contracts, PSR, and spatie/laravel-package-tools cover the general case with far broader community support and no justification burden.

Migration path — adapter-first, dependency-second. The sequence that keeps optionality real:

1. Define our own application-facing port for the concern we need (extension registry, authorization, notification).
2. Write two adapters — one against Orchestra (implementing the Orchestra contract), one against current code.
3. Only once the seam is proven, bind the Orchestra interface as the adapter's contract and take the Composer dependency.

A future re-platform of the admin layer then touches adapters, not feature modules. Teams that want only the interface vocabulary should consider vendoring the MIT-licensed interfaces into an App\Contracts namespace — a few hundred lines of in-house maintenance in exchange for removing upgrade-gating risk entirely. That fork decision must be made before we need it, not under pressure.

Compatibility. Pin deliberately and centralize the constraint. If more than one service consumes the contracts, publish a shared internal package or Composer platform constraint so one upstream major bump does not fan out into N coordinated upgrades. Make composer why-not a CI pre-merge check to catch illuminate range collisions early, and audit for transitive Orchestra — if a dependency already pulls it in, we are managing this pin regardless of a deliberate decision.

Sequencing. Dependency audit (hours) → confirm Orchestra commitment → read the src/ interfaces rather than the README → read the corresponding implementations in orchestra/foundation for semantics → build the adapter and conformance test → pin and name an owner → record the vendored-fork procedure in the runbook. The contracts are not self-documenting; their meaning lives in the concrete classes that satisfy them, so the reading step is not optional.

Operational Impact

Maintenance. This is a low-code, high-attention dependency: nothing to patch in the package, but a recurring obligation to map upstream releases onto our Laravel upgrade calendar. Budget roughly an engineer-hour per Laravel major for the mechanical work, plus the wait time we do not control. Without a named owner, the upgrade block happens to us rather than being planned for.

Support. Single maintainer, effectively zero external dependents, no SLA. The operating assumption should be "no response upstream" — treat it as the default, not the exception. That is acceptable for an internal architectural boundary and unacceptable for anything customer-facing or launch-blocking.

Scaling. Not a runtime scaling concern — there is no runtime. The scaling risk is organizational: every additional feature module that codes against the contracts increases the surface that must stay consistent with an interface set we do not control. The mitigation is discipline enforced in code review — modules depend on the interfaces, never on the concrete Orchestra classes. If that discipline lapses, the advertised exit path stops being real and we are effectively pinned to the platform.

Failure modes to plan around.

• Upgrade gating — Laravel major ships, matching branch lags. Mitigate with a pre-agreed vendored fork.
• Semantic drift — interface signature change appears as a fatal type error at boot in our implementing classes. Mitigate with a conformance test that asserts implements and signature shape, failing in CI with a clear message.
• Dependency conflict — illuminate range collisions. Mitigate with composer why-not as a pre-merge gate.
• Transitive pull — an unrelated dependency drags Orchestra in, making the pin unavoidable. Mitigate with a pre-adoption dependency audit.
• Silent abandonment — no upstream response, no branch for the next Laravel major. Mitigate by verifying fork feasibility (license, file count) now and writing the procedure into the runbook.

Ramp-up. An afternoon for an engineer fluent in Laravel contracts and container binding. The hidden cost is not the interfaces — it is understanding Orchestra's extension, memory, authorization, notifier, and widget semantics, which requires reading the implementation packages. Plan for that reading time explicitly; it is consistently underestimated when this package is scoped as "just interfaces."

TPM 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, enforce interface-first coding in review, and decide the vendored-fork fallback in advance rather than reactively. Keep it off any critical path.