README

Universal, deterministic, infrastructure-only build orchestrator for the PilotPHP Agent-First framework.

pilotphp/build accepts a contracts DeclarationReplay (typically produced by pilotphp/core after composition resolution), selects BuildStageInterface declarations, prepares each stage once, computes a canonical fingerprint, and publishes content-addressed generations atomically.

Build does not discover packages, validate manifests, or depend on core. The application calls core and build separately.

Installation

composer require pilotphp/build

Requires PHP 8.5 and pilotphp/contracts.

This package does not depend on pilotphp/core, pilotphp/config, pilotphp/container, pilotphp/runtime, pilotphp/console, pilotphp/operation, or pilotphp/app. Domain packages implement PilotPHP\Contracts\Build\BuildStageInterface and register stages during package register() — core replays those declarations; build compiles them.

What it does

Selects build stages from DeclarationReplay (BuildStageInterface only)
Validates and deterministically orders the stage dependency graph
Calls prepare() exactly once per stage; builds a shared fingerprint
Skips compile() on cache hit; compiles once per stage on miss
Writes artifacts only through the contracts ArtifactWriterInterface
Publishes generations atomically and preserves the last successful current

What it does not do

No package discovery, manifest validation, capability binding, composition resolution, runtime loop, HTTP/gRPC transport, console commands, or operation dispatch. Constructing BuildOrchestrator does not start a build. Stages are never passed manually on BuildRequest.

Quick start

use PilotPHP\Build\BuildOrchestrator;
use PilotPHP\Build\Plan\BuildRequest;
use PilotPHP\Contracts\Package\DeclarationReplay;

// Application composition root (after core.resolve):
$resolved = $core->resolve($compositionRequest);

$result = (new BuildOrchestrator())->build(new BuildRequest(
    projectRoot: $projectRoot,
    outputRoot: $outputRoot,
    profile: 'prod',
    declarations: $resolved->declarations(), // DeclarationReplay from contracts
));

echo $result->fingerprint();
echo $result->cacheStatus()->value;
echo $result->generationRelativePath();

After a successful build:

var/cache/pilot/
  current.php
  locks/<fingerprint>.lock
  generations/<fingerprint>/
    build-manifest.php
    artifacts/...

See docs/third-party-stage.md for a minimal stage implementation and docs/application-integration.md for the full app flow.

Build ABI

Constant	Value
`BuildAbi::COMPILER_VERSION`	`0.1.4`
`BuildAbi::ARTIFACT_SCHEMA`	`pilotphp.build-artifacts.v1`
`BuildAbi::FINGERPRINT_SCHEMA`	`pilotphp-build-fingerprint-v1`
`BuildAbi::CURRENT_POINTER_SCHEMA`	`pilotphp.build-current.v1`

Documentation

Document	Description
docs/adr-resolved-composition-metadata.md	ADR: resolved composition metadata omitted from fingerprint
docs/application-integration.md	Application composition root: core then build
docs/architecture.md	End-to-end infrastructure orchestrator architecture
docs/artifacts.md	Artifact descriptors, manifest, writers, and publication
docs/atomic-publication.md	Staging, rename, and current pointer protocol
docs/build-lifecycle.md	Ordered lifecycle, prepare/compile split, failures
docs/build-pipeline.md	Internal pipeline: collect, prepare, compile, publish
docs/build-plan.md	`BuildRequest`, `BuildResult`, `BuildOptions`, cache status
docs/build-stages.md	How build consumes the contracts Build SPI
docs/cache.md	Cache hit policy and integrity
docs/compatibility.md	SemVer policy and machine-readable contract surface
docs/concurrency.md	Fingerprint locks and concurrent builds
docs/fingerprinting.md	Canonical fingerprint schema
docs/fingerprints-and-cache.md	Overview: fingerprint identity and cache reuse
docs/migration.md	Migration from discovery/composition-owned build
docs/performance.md	Benchmarks and performance characteristics
docs/public-api.md	Every public type: consumer, lifecycle, compatibility
docs/security.md	Path safety, lock files, and trust boundaries
docs/stage-discovery.md	Replay-based stage selection (not package discovery)
docs/stage-graph.md	Graph validation and deterministic ordering
docs/third-party-stage.md	Generic third-party stage via contracts Build SPI

Agent guidance

See AGENTS.md for invariants and Definition of Done when modifying this package.

License

MIT

pilotphp / build

Maintainers

Package info

Statistics

Security