IICP Directory — PHP reference implementation

Laravel reference implementation of the IICP discovery and control plane. The directory registers providers, receives heartbeats, publishes capability and health evidence, selects eligible routes, and issues control-plane tokens and receipts. Task payloads are sent directly between consumers and selected providers and must not pass through the directory.

This makes the directory an intent-resolution and provider-eligibility control plane, not a task-execution protocol or universal agent runtime. MCP, A2A, HTTP or another negotiated binding may execute after selection. See the public protocol positioning and adjacent-protocol comparison.

Maturity

This is active pre-1.0 software and the implementation used by the current IICP Genesis Seed. Public source availability does not imply that independent multi-root federation, every optional profile, or production operation without review is complete.

The protocol is defined in the public IICP specification.

Directory flavors

PHP is the supported implementation behind the current Genesis Seed. The Rust directory is a pre-1.0 operator preview of the same implementation-neutral contract. Its publication does not move production traffic or deprecate PHP.

Applications should use the protocol contract rather than depend on implementation-specific internals. Consumer and provider agents can start with the public agent bootstrap guide.

Local setup

Requirements: PHP 8.3 or newer, Composer, and the SQLite extensions used by the test suite.

cp .env.example .env
composer install
php artisan key:generate
php artisan migrate
php artisan serve

Use a generated application key and dedicated database credentials. Never copy credentials from the public Genesis Seed.

Verification

composer install --no-interaction --prefer-dist
php artisan test --compact
php artisan test --compact tests/Feature/OpenApiContractTest.php
python3 scripts/check_seed_parity.py \
  --manifest parity/seed-manifest-v1.10.76.2.json \
  --php-dir . \
  --git-revision c489d4e02a636b337ba4237f8543f83675162db0

Run the released lifecycle profile against a disposable SQLite database and loopback test server with ./scripts/run_lifecycle_conformance.sh. The lane pins the IICP v1.10.8 runner, rechecks the production SSRF boundary, uses the existing testing-only liveness bypass and emits only a content-free summary. It does not contact or modify Genesis.

The versioned parity manifests identify and preserve the reviewed extraction snapshot at the pinned public Git revision. Current development is authoritative in this public repository; it is not required to remain a live mirror of a private tree. The manifests do not certify live operational equivalence on another host.

Version namespaces

The repository uses separate version namespaces that should not be compared as one release sequence:

• openapi: 3.1.0 selects the OpenAPI format;
• info.version: 1.7.0 versions the documented OpenAPI contract;
• runtime v1.10.94 identifies the current application release; and
• parity manifest v1.10.76.2 identifies the final historical extraction snapshot from the earlier seed source.

The public repository is the source authority for releases beginning with v1.10.77.1. See RELEASE_POLICY.md for compatibility, verification and support rules.

A release artifact with complete deployment metadata publishes /.well-known/iicp-deployment.json. The record signs the runtime version, release tag, source revision, artifact digest and compatibility range with the directory key. Missing metadata or signing material returns 503 instead of an unsigned claim.

Major protocol surfaces

• provider registration, deregistration and heartbeat;
• intent, model and policy-aware discovery;
• public node, intent and mesh statistics;
• dispatch tickets and consumer tokens;
• credits, reputation and signed receipts;
• signed lifecycle events and snapshot preparation;
• operator identity, DSR and policy-manifest lifecycle;
• telemetry, health evidence and conformance badges.

See routes/api_protocol.php, routes/api_public.php, and openapi.yaml for the implementation surface. The IICP specification is normative and OpenAPI is its machine-readable HTTP projection; a contradiction between runtime and OpenAPI is a contract defect, not permission to choose whichever behavior is convenient. contracts/route-classification.json records every application route and gives a reviewed reason for surfaces intentionally excluded from the current OpenAPI projection.

Configuration and operations

An optional, disabled-by-default restricted trust-domain membership foundation is documented in docs/RESTRICTED_TRUST_DOMAIN.md. It does not alter public defaults, enable federation or represent a production Genesis deployment.

• .env.example contains placeholders and safe defaults only.
• APP_ENV=local or testing permits local endpoints for development; production mode rejects private and loopback provider routes.
• Signing keys, database passwords and deployment configuration must remain outside the repository.
• Back up a self-hosted database before and after migrations or maintenance.

See OPERATIONS.md for generic self-host backup, migration, retention and restore guidance.

Repository boundary

This repository owns the PHP directory implementation. It does not own the protocol specification, client SDKs, website, production topology, production credentials, or the deployment of iicp.network.

See SECURITY.md, CONTRIBUTING.md, and PUBLICATION_READINESS.md before operating or contributing.

Rehearsal evidence and cleanup

The operator stack and upgrade rehearsal scripts preserve a content-free attempt record even when a command fails. They print the private evidence directory; workload.json records the phase and original exit code before teardown, checks.json retains validated successful checks, and closure.json records the separate cleanup outcome. Raw logs, environment values and database contents are not copied into these reports. A passing process alone is not qualification.

IICP_OPERATOR_REHEARSAL_DIR and IICP_OPERATOR_UPGRADE_DIR now select an existing, owned parent directory (or a root-owned sticky temporary directory); the scripts create their own private child workspace. They never remove that parent. Symlink parents and occupied Compose project names are refused. Default project names use the iicp-operator-rehearsal- or iicp-operator-upgrade- prefix; explicit project names must retain an allowed operator prefix (including the existing capacity harness). Each invocation appends a random suffix so concurrent invocations do not share a project. Legacy result-output variables create a new owner-only file and refuse an existing destination rather than overwriting it.

Cleanup is limited to the exact rehearsal project, followed by checks for remaining containers (including stopped containers), volumes and networks. Failure evidence and failed workspaces are retained for diagnosis; these workspaces can contain private generated secrets and must not be committed or uploaded wholesale. Successful workspaces are removed after evidence is saved. Retained evidence is intentionally not pruned automatically.

A workload failure preserves its exit code. Failed evidence export, incomplete cleanup, or --keep after an otherwise successful workload returns exit code 3; retained resources cannot count as a clean run. --keep retains both workspace and resources for inspection. No broad Docker cleanup is performed.

The capacity harness explicitly verifies and consumes a successful retained rehearsal, then writes a separate capacity/closure.json and performs the same scoped cleanup. The original retained receipt is not rewritten as a clean pass.