# ICOM Framework — development prompt

Build and deploy an original, understandable PHP framework at framework.icom.la. Target the ease of writing a small Laravel application, explicit modular architecture associated with Symfony, a request lifecycle compatible with persistent PHP workers, practical security defaults, and portable deployments. Treat superiority as a hypothesis to measure, never as a release claim.

## Deliverable

Ship a usable, MIT-licensed 0.3 developer preview with source, Composer installation, a command-line entry point, complete local documentation, a live API playground, regression tests and reproducible benchmark commands. Require PHP 8.4+. Preserve unrelated hosting data. Deploy only public entry points and assets under the subdomain document root; store application source and secrets outside it. Use HTTPS and production error handling.

## Architecture and behavior

- Use PSR-4 autoloading, PSR-7 requests/responses, PSR-15 middleware, PSR-11 dependency injection, PSR-3 logging, PSR-14 events and PSR-16 cache interfaces. Use maintained interface/HTTP-message packages; do not reinvent these standards or vendor modified third-party source.
- Provide fluent method routing, named parameters, names/URL generation, route-specific middleware, HEAD/OPTIONS/405 semantics, and a request-bound service container. No global mutable application facade. Detect circular dependencies and disallow singleton capture of scoped services.
- Resolve typed controller dependencies and request parameters explicitly. Isolate each request container and release it in finally blocks. Include guarded FrankenPHP and Swoole adapters; document experimental status and runtime restrictions honestly.
- Provide deterministic validation with field-level errors and rejection of unknown rules; escaped PHP views; PDO prepared queries, identifier-safe query builder, transactions and a migration command; a file cache with TTL and atomic writes; a locked rate limiter with Retry-After.
- Apply CSP, nosniff, referrer and framing controls, unique request IDs, structured logs, generic production error responses, body-size limits, strict host validation and a signed expiring CSRF double-submit cookie for the browser demo. Never trust forwarded client addresses by default. Use password_hash/password_verify and libsodium authenticated encryption helpers. No default user, password or exposed administration console.
- Include environment/configuration loading without executable configuration from users. Keep credentials and logs out of public output, downloadable distributions and version control.
- Provide liveness/readiness routes, graceful bounded worker loops, Docker/FrankenPHP and Kubernetes deployment examples, CI tests, and rollback instructions. Mark examples not exercised on hosting as unverified.

## Developer experience

Use the brand ICOM Framework. Build a restrained, accessible documentation interface with an overview, installation, routing, container, middleware, validation, database, cache, security, authentication/policies, queues, events, ORM, runtime, testing and release status and the full development prompt. Include a working playground for a GET greeting and CSRF-protected POST validation, with response status, timing, JSON output and curl examples. Make the source archive and its SHA-256 digest downloadable. Avoid fictional Packagist/GitHub URLs or fabricated performance numbers.

## Verification and release gates

Test route ordering/methods, route URL encoding, request injection, container scope isolation and captive dependency rejection, middleware ordering, validation edge cases, SQL parameterization and identifier injection, cache expiry/corruption, concurrent rate limiting, authenticated-encryption tampering, CSRF tampering/expiry, error redaction and repeated requests through one application instance. Test actual production HTTP routes, headers, CSRF positive/negative cases, hidden-file protection and TLS. Browser-test desktop and mobile, navigation, copy controls and both playground requests. Run composer validate/audit and PHP lint. Record real measurements with workload/runtime/machine details; do not compare against Laravel/Symfony without running equivalent applications under equal conditions.

## Release boundaries and further work

A 0.3 preview is not an enterprise certification, a replacement for the Laravel/Symfony ecosystems, or a proven throughput improvement. Password sessions, resource policies, leased SQL queues, PSR-14 events and optional Redis/Doctrine integrations are now included and must have behavior tests. TOTP MFA, one-use recovery codes, administrator-mediated reset, explicit tenant membership policies, local security audit and real MariaDB tests are required in 0.3. OIDC/SAML, recovery delivery services, automatic tenant query scoping, distributed tracing exporters, production SQL/cluster rollout, independent security review and production worker soak tests remain further work. Provide integrations where useful, but never present stubs as completed features.

## Source references checked 2026-09-10

- Laravel 13 release notes (PHP 8.3+): https://laravel.com/framework/docs/releases
- Symfony 8.1 current release (PHP 8.4+): https://symfony.com/releases/8.1
- FrankenPHP worker state/reset requirements: https://github.com/php/frankenphp/blob/main/docs/worker.md
- PHP-FIG standards: https://www.php-fig.org/psr/

## Version 0.2 implementation and acceptance requirements

1. Add password authentication, database-backed hashed session tokens, idle/absolute expiration, session revocation and cookie middleware. Provision accounts through CLI only; no default account or public registration. Add role permissions plus explicit object-level policies. Test invalid credentials, timing-work fallback, session fixation/expiry/revocation, role changes and authorization failures.
2. Add a persistent database queue with JSON payloads, explicit named handler registration, delayed jobs, optimistic atomic reservation, ownership tokens, expiring leases, retries/backoff and failed-job inspection/retry. Never deserialize executable job classes from payloads. Use a fresh container scope for each job. Test competing workers, process loss, stale acknowledgements and poison jobs. Describe at-least-once behavior and idempotent-handler responsibilities.
3. Add PSR-14 event dispatch with listener priority and stoppable events. Test ordering, object identity and exception propagation.
4. Add optional, tested Predis-based PSR-16 cache and distributed atomic rate limiter. Separate application namespaces, authenticate serialized cache records, avoid FLUSHDB and fail closed on rate-store failures. Exercise against an actual isolated Redis process.
5. Add a Doctrine ORM integration as an optional maintained component, with per-request EntityManager disposal. Test persistence, query parameterization, relationships and scope isolation on SQLite. Keep core dependencies small; list installation requirements explicitly.
6. Exercise the actual FrankenPHP binary with concurrent/repeated HTTP requests, cookies, 4xx/5xx, worker recycling and response output. Verify its checksum. Publish the precise tested version, configuration, workload and limitations. Test Swoole only if an isolated supported runtime is available; never pretend a syntax check is a runtime test.
7. Expand documentation and the complete prompt, add operational CLI examples, source archive and SHA-256, run lint/audit/core and integration checks, preserve rollback, then deploy a new release. Test live HTTP and desktop/mobile documentation after deployment.

Remaining externally dependent work: real OIDC/SAML provider onboarding, external tracing collector, independent security assessment/compliance certification, production cluster testing and equal-workload comparative Laravel/Symfony benchmarks. Implementing local modules does not close these claims.

See docs/VERIFICATION.md for measured outcomes and limitations.

## Version 0.3 implementation and acceptance requirements

Continue ICOM Framework after v0.2, preserving PHP-FPM hosting and previous releases/downloads. Build actual identity security and exercise a shared SQL service. Keep claims proportional to evidence.

1. Add maintained RFC 6238 TOTP integration, encrypted account-bound secrets, expiring pending enrollment, password reauthentication, confirmation before activation, single-use recovery codes and replay prevention. Enrollment/disable/recovery-code changes revoke sessions. Do not expose a default account or send secrets to QR services.
2. Require a single-use, five-minute challenge after the password for MFA accounts. Bound attempts, serialize factor/token consumption and prevent password-only Sessions::login from bypassing MFA. Invalidate outstanding challenges on password/account/factor changes.
3. Add single-use expiring password reset tokens with administrator-mediated issuance to a private file. Reset preserves enrolled MFA and revokes sessions/challenges/reset tokens. No unauthenticated token issuance, implicit email delivery or MFA bypass. Add password change with current-password and factor verification.
4. Add an append-only application audit API/CLI covering account, session and factor events, excluding credentials, OTPs, raw tokens, email and request bodies. State the database operator can still modify records; no tamper-proof claim.
5. Add explicit tenant membership/policy helpers that check fresh membership and resource tenant equality. No inferred tenant from untrusted headers; trusted application routes select tenant IDs. Test cross-tenant denial and revoked membership.
6. Run an actual isolated MariaDB instance through PDO MySQL: migrations, prepared queries, rollback, sessions/MFA/reset consumption, concurrent queue claims and replay races. Fix found issues; do not relabel MariaDB as an Oracle MySQL/PostgreSQL certification.
7. Extend tests, docs and source distribution. Run server PHP 8.4 core tests, archive install, live HTTPS auth/MFA flows with temporary accounts, and desktop/mobile documentation QA. Snapshot private SQLite before additive migration, use a new release and retain rollback.

Remaining external/infrastructure work: real OIDC/SAML provider onboarding and delivery services, independent security assessment, staging cluster deployment/failover, tracing collector and long-duration production worker tests, comparative Laravel/Symfony applications and measurements.