Fix Composer discovery for public package classes

README.md

@@ -105,6 +105,8 @@ composer require wordpress/agents-api:^0.1
 
 Composer autoloads `agents-api.php` through the package `files` autoload entry. The consuming project must load Composer's generated `vendor/autoload.php` during WordPress bootstrap. After that, the same public API is available as in the plugin activation path.
 
+Public agent package definitions are classmapped, so Composer-aware IDEs and static analyzers discover their concrete types without executing the WordPress runtime bootstrap.
+
 Pin released tags (`^0.1`, `0.1.x`, or an exact `0.1.0` tag) for reproducible production installs. Track `main` only for active substrate development.
 
 ## Consumer Integration

composer.json

@@ -17,15 +17,21 @@
   "autoload": {
     "files": [
       "agents-api.php"
+    ],
+    "classmap": [
+      "src/Registry/class-wp-agent.php",
+      "src/Packages/"
     ]
   },
   "suggest": {
     "woocommerce/action-scheduler": "Required to actually run cron-triggered workflows. The substrate detects Action Scheduler at runtime and no-ops cleanly when absent; install this package (or any plugin that ships it, like WooCommerce) to enable scheduled workflow runs."
   },
   "scripts": {
     "phpstan": "phpstan analyse --no-progress --memory-limit=2G",
+    "phpstan-consumer": "phpstan analyse --no-progress --memory-limit=1G -c tests/fixtures/phpstan-consumer.neon",
     "smoke": [
       "php tests/composer-autoload-smoke.php",
+      "@phpstan-consumer",
       "php tests/bootstrap-version-skew-smoke.php",
       "php tests/bootstrap-smoke.php",
       "php tests/message-envelope-smoke.php",

tests/composer-autoload-smoke.php

@@ -9,11 +9,22 @@
 
 echo "agents-api-composer-autoload-smoke\n";
 
-require dirname( __DIR__ ) . '/vendor/autoload.php';
+$loader = require dirname( __DIR__ ) . '/vendor/autoload.php';
 
 if ( defined( 'AGENTS_API_LOADED' ) ) {
 	fwrite( STDERR, "FAIL: Composer autoload initialized Agents API outside WordPress.\n" );
 	exit( 1 );
 }
 
-echo "PASS: Composer autoload returns without WordPress.\n";
+$package_file = $loader->findFile( 'WP_Agent_Package' );
+if ( ! is_string( $package_file ) || ! str_ends_with( str_replace( '\\', '/', $package_file ), '/src/Packages/class-wp-agent-package.php' ) ) {
+	fwrite( STDERR, "FAIL: Composer classmap does not expose WP_Agent_Package.\n" );
+	exit( 1 );
+}
+
+if ( class_exists( 'WP_Agent_Package', false ) ) {
+	fwrite( STDERR, "FAIL: Composer autoload eagerly loaded WP_Agent_Package outside WordPress.\n" );
+	exit( 1 );
+}
+
+echo "PASS: Composer autoload returns without WordPress and exposes package classmaps lazily.\n";

tests/fixtures/phpstan-consumer.neon

@@ -0,0 +1,6 @@
+parameters:
+	level: 7
+	paths:
+		- phpstan-consumer.php
+	bootstrapFiles:
+		- ../../vendor/autoload.php

tests/fixtures/phpstan-consumer.php

@@ -0,0 +1,23 @@
+<?php
+/**
+ * Consumer fixture proving Composer exposes guarded package contracts to PHPStan.
+ *
+ * @package AgentsAPI\Tests
+ */
+
+/**
+ * Exercise package types without loading the WordPress runtime bootstrap.
+ *
+ * @param WP_Agent_Package $package Package contract.
+ * @return array<int,mixed>
+ */
+function agents_api_phpstan_consume_package( WP_Agent_Package $package ): array {
+	$report = WP_Agent_Package_Capability_Checker::check( $package, array() );
+
+	return array(
+		$package->get_slug(),
+		$report->to_array(),
+		WP_Agent_Package_Artifact_Status::classify( 'installed', 'current' ),
+		WP_Agent_Package_Artifact_Hasher::hash( array() ),
+	);
+}