pilotphp / contracts
Stable public contracts for the PilotPHP Agent-First framework ecosystem.
Maintainers
Requires
- php: ^8.5
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.88
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.5
README
Stable public contracts for the PilotPHP Agent-First framework ecosystem.
Leaf infrastructure-only Composer distribution: interfaces, immutable value objects, enums, package/declaration SPI, and a minimal universal Build SPI. No runtime implementations. Not a Pilot extension package. Production dependency: PHP 8.5+ only.
Current line: 0.1.4 (unreleased / 0.1.4-dev until tagged).
Scope
Shared, transport-neutral vocabulary for every other PilotPHP package without forcing them to depend on each other.
Belongs here: inter-package interfaces, validated immutable VOs, enums, package registration contracts, declaration provenance/record/replay, Build SPI.
Does not belong: orchestration, discovery, I/O, caches, publishers, transport/ORM/framework implementations, speculative abstractions, fictitious Pilot extension entry points.
See AGENTS.md and docs/architecture.md.
Installation
composer require pilotphp/contracts
A Composer dependency on pilotphp/contracts is a PHP type/library
dependency. It is not a Pilot activation dependency: contracts is never
discovered via pilot/package.json, never appears in rootPackages, and
never participates in composition as a package node.
Namespaces
| Namespace | Contents |
|---|---|
PilotPHP\Contracts\Package | Package description, registration, declaration provenance/record/replay |
PilotPHP\Contracts\Build | Universal Build SPI |
PilotPHP\Contracts\Kernel | Application entry point lifecycle |
PilotPHP\Contracts\Container | Read-only service resolution |
PilotPHP\Contracts\Config | Typed configuration access |
PilotPHP\Contracts\Runtime | Transport-neutral invocation handling |
Build SPI (summary)
Domain packages implement BuildStageInterface and register the stage as a
package declaration. pilotphp/build collects stages from declaration
replay of active resolved packages only. Domain packages must not
depend on pilotphp/build. Details: docs/build-spi.md.
Documentation
| Doc | Topic |
|---|---|
| docs/architecture.md | Leaf role and boundaries |
| docs/public-api.md | Full public API map |
| docs/package-contracts.md | Package system |
| docs/declarations.md | Declaration model + replay |
| docs/capabilities.md | Capability rules |
| docs/build-spi.md | Build SPI |
| docs/runtime-contracts.md | Runtime surface |
| docs/lifecycle.md | Activation + worker lifecycle |
| docs/compatibility.md | SemVer / 0.x policy |
| docs/security.md | Diagnostics and path rules |
Development
make install
make check
Repository
Standalone Git repository. No monorepo.