Am Driver Laravel Package

Product Decisions This Supports

• Build vs. buy for control-plane integration. If your product must be provisioned, started, stopped, quota-limited, upgraded, and metered by Application Manager (AM), this package is the “buy/adopt” option for the connector layer. It replaces bespoke webhook, auth, idempotency, callback, and state-push plumbing with a contract-driven bundle.
• Managed-service and multi-tenant roadmap. It directly supports decisions to offer tenant provisioning (CREATE_INSTANCE), lifecycle operations (START, STOP, QUOTA_EXCEEDED, UPGRADE_INSTANCE), operational-state reporting, and instance introspection/state views. These are the primitives behind a managed or hosted product tier.
• Monetization and packaging experiments. The billing session methods (createSubscriptionUpgradeSession, createSubscriptionResubscribeSession, target formula IDs) support upgrade paths such as entry tier → higher tier, and reactivation flows. PMs can use these to test packaging, upgrade prompts, and entitlement changes without inventing a billing integration.
• Usage metering and consumption-based pricing. pushResourceConsumption() gives a standard way to report resource consumption (e.g., storage, seats) back to AM. This supports decisions about metered billing, quota enforcement, and usage dashboards.
• Standardization across a product portfolio. The stable source values (captain-learning, accident-prediction, application-manager) imply a portfolio-level integration convention. Adopting it reduces one-off integration design and makes cross-product orchestration more consistent.
• Roadmap sequencing for “managed app” readiness. The feature set maps to a maturity ladder: connect and authenticate → handle provisioning → report state → meter consumption → support upgrades/resubscriptions → defer long-running operations. PMs can use this as a checklist for launch readiness.
• Operational risk decisions. The package’s idempotency keys, callback model, deferred execution dispatchers, and receipt/snapshot stores affect reliability and support burden. Those are product-level decisions about SLA expectations, retry behavior, and incident recovery, not just engineering details.

When to Consider This Package

Consider it when:

• You are explicitly integrating a PHP application with Application Manager. This is a connector, not a general orchestration framework. Its value is highest when AM is already the control plane.
• You are on Symfony (or can tolerate framework-agnostic wiring). The bundle provides routes, configuration, token authentication, and service aliases; the Core namespace allows manual wiring without Symfony, but that shifts more integration work to your team.
• You need the full lifecycle contract rather than a single endpoint. CREATE, START, STOP, quota-exceeded, upgrade, get-info, set-stateview, consumption webhooks, and operational-state push are all covered. If you only need one webhook, direct HTTP may be simpler.
• You can accept pre-1.0 churn. The package is at 0.0.x with repeated breaking changes across 0.0.9, 0.0.14, 0.0.16, 0.0.17, 0.0.19, 0.0.22, and 0.0.23. Adoption is reasonable only with exact version pinning, a migration budget, and someone owning upstream changelog review.
• You have a maintainer relationship or can fork. MIT licensing and a small codebase make forking viable. With zero stars and zero dependents, external community support is not a realistic safety net; treat it as an internal or partner-owned dependency.
• You value the conformance artifacts. The OpenAPI 3.1.1 spec, integration manual, same-app dogfooding notes, and CLI simulators reduce ambiguity in what AM expects. That is useful for contract tests and for aligning product and engineering on behavior.

Look elsewhere when:

• You are not in the AM ecosystem. There is no reason to adopt an AM-specific connector for generic workflow orchestration, subscription billing, or tenant management.
• You need a stable public API or vendor SLA. A 0.0.x package with frequent breaking changes and no dependents is not a stable platform dependency. If you need long-term support, formal security review, or a compatibility guarantee, this is not it.
• Your stack is not PHP. The core is PHP; non-PHP services would be reimplementing the contract from the OpenAPI spec, at which point the package provides little direct leverage.
• You cannot absorb migration work. The 0.0.9 tenantId→instanceId change and the 0.0.14 token consolidation are examples of changes that touch DTOs, storage paths, configuration, and CLI usage. If your team cannot track upstream releases, pinning will eventually become debt.
• A thin direct integration is sufficient. If you only need to receive one command and post one callback, the bundle’s abstractions, handler interfaces, and Symfony configuration may be more surface area than value.

How to Pitch It (Stakeholders)

For executives: This package is an accelerator for connecting a PHP product to Application Manager. It gives us the standard provisioning, lifecycle, state-reporting, usage-metering, and upgrade/resubscribe flows without building a custom control-plane connector. That shortens time-to-market for a managed or hosted offering and reduces bespoke integration risk. The caveat is maturity: it is a 0.0.x package with low external adoption, a fast-moving contract, and recurring breaking changes. The right posture is a time-boxed pilot behind an internal adapter, with an exact version pin and a named owner for upstream changes. Do not treat it as a long-term stable platform dependency until it reaches 1.0 or we establish a maintainer commitment.

For engineering: The bundle handles the repetitive contract work: Symfony routes and token auth, orchestration command validation, idempotency, callbacks to AM, consumption webhooks, operational-state push, deferred execution dispatchers, local receipt/snapshot stores, and CLI simulators for end-to-end testing. Your product logic lives in handler implementations such as CreateInstanceHandlerInterface, StartInstanceHandlerInterface, UpgradeInstanceHandlerInterface, and the info/stateview handlers. The main costs are upgrade churn, French-language documentation, growing constructor dependencies in OrchestrationCommandProcessor, and the need to alias every host interface explicitly. Recommended approach: spike one integration, wrap the package behind our own anti-corruption interface, pin the exact version, add contract tests against the OpenAPI spec, and budget migration work for each upstream minor release. The OpenAPI spec and receptacle CLI make a local E2E loop feasible, which is a real de-risking advantage.

Bottom line: Adopt it as a tactical accelerator inside the AM ecosystem, not as a strategic platform bet. The opportunity is real for teams already committed to AM and Symfony; the risk is pre-1.0 churn and near-zero external validation. Fund a small pilot, measure integration time saved against migration overhead, and make the build-vs-buy call after one full lifecycle integration.