Pioneer Compiler Specification

1. Introduction

Pioneer is a compiler-directed architecture for porting Illuminate and Laravel-style applications to Deno-compatible and edge-compatible runtimes while preserving the productive Laravel programming model. This specification defines the private Find How compiler contract: how source files are discovered, how providers declare application capabilities, how kernel entry points become deployable artifacts, and which rules runtime source must satisfy before it is certified.

The numbered rules in Rule Catalog are normative. Sections that describe motivation, examples, or deferred topics are informative unless they explicitly use RFC 2119 language. A Pioneer implementation conforms to this document only when it enforces the normative rules, emits the generated artifacts described here, and rejects source that would require runtime discovery, dynamic container lookup, unsafe public typing, or unvalidated trust boundary flow.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [RFC2119].

2. Goals And Non-Goals

Pioneer exists to make Laravel-style applications statically analyzable without flattening their domain model into a generic JavaScript framework. The compiler owns discovery, identity, dependency wiring, validation gates, and deployment shape so application and Illuminate source can remain small, direct, and tree-shakable.

Normative goals:

• Preserve familiar Laravel folders, managers, facades, providers, routes, queues, schedules, events, broadcasts, models, migrations, and Artisan-style commands.

• Replace runtime reflection, classmaps, boot methods, dynamic container lookup, and filesystem scans with compile-time module graph facts.

• Emit kernel-specific bundles with only the bindings, modules, validation gates, and runtime adapters required by each entry point.

• Treat data resources, model resources, binding keys, and module-backed entities as stable compiler identities rather than ad hoc strings.

• Keep public behavior compatible with harvested Laravel parity tests where a component claims Laravel parity.

Non-goals:

• Pioneer is not a public open-source standard for this repository.

• Pioneer does not define a Composer replacement or a PHP runtime compatibility layer.

• Pioneer does not allow production source to recover Laravel dynamism through JavaScript Proxy, decorators, runtime registries, global service locators, or unsafe type casts.

• Pioneer does not require the emitted runtime to contain an application container when direct calls can preserve behavior.

3. Terminology

Application source

User-authored modules that are compiled by Pioneer.

Illuminate source

Pioneer-owned ports of Laravel and Illuminate components.

Provider file

A phase-2 entry point imported through @provider/* or @provider-dev/* that declares bindings, aliases, migrations, model features, config merges, middleware aliases, and other provider-owned compiler facts.

Kernel entry point

A phase-3 file that imports a kernel facade from @find-how/pioneer and makes top-level declarations for HTTP, Artisan, Queue, Schedule, Broadcast, or Event kernels.

Consumed-by-DI module

A handler, listener, command, queue job, middleware, service, policy, observer, model feature, or related module that is reached through compiler wiring rather than imported as a kernel entry point.

Bare nominal path

A compiler-normalized ESM module identity without a file extension, such as @app/http/handlers/ListOrders.

Data resource

A compiler-derived identity for a database table, column, index, or related resource, such as db:edge:users or db:edge:users.email.

Binding snapshot

The exact compile-time binding shape available to one kernel entry point after providers, contextual bindings, middleware context augmentation, and destructuring analysis are applied.

Alias namespace

A compiler-owned lookup domain in which an ergonomic name resolves to a single canonical bare nominal path or generated data resource. Alias namespaces are distinct for bindings, middleware, model aliases, table sugar, and any other compiler-defined lookup domain.

Provider key

The canonical provider identity derived from the import-map provider root and resolved provider file. Provider keys are unique within one compilation unit.

Validation gate

A generated or component-owned function that accepts unknown at a trust boundary and either returns typed data or throws an operational error.

Proof certificate

A compiler-generated record that binds a source content hash, compiler tool versions, checked rule set, and pass/fail state to a component or emitted artifact.

4. Conformance Classes

This specification defines multiple conformance classes. A product MAY conform to more than one class. Claims of conformance MUST identify the class and the rule set version used for certification.

5. Architecture Overview

Pioneer splits application interpretation into three compiler phases and one runtime emission stage. Phase 1 constructs the canonical module graph. Phase 2 turns provider declarations, migrations, model declarations, config, and module metadata into a typed application graph. Phase 3 extracts kernel entry points and their binding snapshots. Emission writes runtime modules, contracts, manifests, TypeGraph records, validation gates, and deployment adapters.

The module graph is the root of trust. Any source fact that cannot be derived from Deno-compatible resolution, import maps, provider declarations, migration metadata, or explicit kernel facade calls is not part of the compiled application. Runtime code therefore does not discover providers, scan route files, load a classmap, ask a package manifest for framework metadata, or infer identity from arbitrary strings.

The emitted runtime is allowed to be smaller and more direct than the developer surface. The compiler may inline factories, erase the container, replace facades with direct binding calls, and emit Cloudflare Durable Object wrapper classes for edge processes. These transformations must preserve the public contracts defined by component contracts.d.ts files and parity tests.

6. Compiler Pipeline

The compiler pipeline is deterministic for a fixed source tree, import map, lockfile, compiler version, and external schema inputs.

6.1. Phase 1: Autoload And Module Graph

Phase 1 loads Deno configuration, package/workspace metadata, import maps, and lockfiles. It builds the Deno-compatible module graph, extracts imports and exports, classifies source files, and emits the initial autoload and TypeGraph records. Phase 1 is responsible for resolving extensionless nominal paths and for separating ordinary aliases from provider discovery roots.

6.2. Phase 2: Provider, Data, And Model Wiring

Phase 2 consumes provider files and builds the application graph: binding registry, alias map, tag map, migration registry, config merge map, listener registry, observer registry, policy registry, middleware alias/group registry, publish manifest, contextual bindings, service extensions, data graph, model graph, and generated contracts. Provider declarations are unconditional compile-time facts. There is no provider boot phase.

6.3. Phase 3: Kernel Extraction

Phase 3 consumes kernel facade declarations and unrolls routes, route groups, mounts, resource routes, queue jobs, schedules, events, broadcasts, and Artisan commands. It computes one binding snapshot per entry point, applies middleware context augmentation, validates handler target contracts, and records all resource edges needed by deployment planning.

6.4. Emission

Emission writes only artifacts that are justified by graph reachability. A conforming implementation emits runtime boot modules, kernel adapters, contracts, validation gates, manifests, TypeGraph records, and proof certificates as needed. It may emit separate artifacts for local Deno development, Cloudflare Workers, Cloudflare Durable Objects, queues, scheduled jobs, and CLI processes.

6.5. Source Classification Algorithm

A Pioneer compiler MUST classify every Pioneer-participating source file into exactly one category before phase-2 wiring begins.

1. If the file is resolved from a @provider/* or @provider-dev/* import-map root, classify it as a provider file and validate it against R18.
2. Otherwise, if the file imports any kernel facade from @find-how/pioneer and makes at least one top-level kernel declaration, classify it as a kernel entry point and validate it against R15.
3. Otherwise, if the file is referenced by a provider declaration, kernel declaration, model feature reference, middleware reference, listener registration, policy registration, observer registration, queue registration, command registration, or contextual binding, classify it as a consumed-by-DI module.
4. Otherwise, if the file is reachable only through ordinary static imports, classify it as a pure internal utility.
5. If two categories match the same file, the compiler MUST report a source-classification error and MUST NOT emit runtime artifacts for that compilation.

6.6. Provider Discovery Algorithm

A Pioneer compiler MUST discover providers only from import-map entries whose keys match @provider/* or @provider-dev/*. For each provider root, the compiler MUST resolve the root with Deno-compatible resolution, compute a provider key, parse the provider file, and record only top-level declarations from the explicit provider whitelist.

The compiler MUST reject:

• provider arrays or package manifest provider metadata;

• filesystem glob scanning used as a provider registry;

• provider files that export values;

• provider files that import kernel facades;

• provider boot/register lifecycle methods;

• provider-key collisions.

6.7. Alias Resolution Algorithm

When source provides a string that is not already a canonical bare nominal path or generated data resource identity, the compiler MUST resolve it through the active alias namespace.

1. Select the alias namespace from the operation being validated, such as binding lookup, middleware lookup, model lookup, or table sugar.
2. Find provider declarations that bind the supplied string in that namespace.
3. If no declaration matches, report an unresolved-alias error.
4. If more than one canonical identity matches, report an ambiguous-alias error.
5. Replace the source string with the matched canonical identity in compiler records and emitted artifacts.

The emitted runtime MUST NOT repeat alias lookup unless a target-specific adapter requires a user-facing string for interoperability. Even then, compiler records MUST preserve the canonical identity.

6.8. Binding Snapshot Algorithm

For each kernel entry point, the compiler MUST build a binding snapshot:

1. Start with globally provided bindings reachable from production providers and the active runtime target.
2. Apply contextual provider bindings that match the consuming module or kernel entry point.
3. Apply middleware context extensions in route order for HTTP entry points.
4. Read destructured parameter names and namespace member accesses from each consumed-by-DI module reachable from the entry point.
5. Resolve every requested name to a canonical binding or generated data resource.
6. Report an unavailable-binding error for any requested binding that is not present in the snapshot.
7. Emit only bindings, modules, validation gates, and adapters that are reachable from the final snapshot.

6.9. Data Resource Identity Algorithm

For each configured database connection, the compiler MUST derive data resource identity from config merges, registered migration directories, migration SQL or schema introspection, and model declarations.

The compiler MUST assign table, column, and index identities using the exact forms defined in Data And Model Resource Model. Table-name sugar MUST resolve to exactly one generated table identity. Ambiguous table sugar, missing migrations, incompatible model table declarations, unresolved model features, and generated contract mismatches are compile-time errors.

7. Runtime Model

Runtime source is intentionally constrained. Components are factories, constants, and plain objects. Instance state is closure state. Public APIs return null for expected absence, throw operational errors for recoverable failures, and throw plain Error for developer errors. Web Standards are the transport base, so request and response abstractions extend platform primitives rather than replacing them.

The emitted runtime must not depend on runtime package scanning, reflection, dynamic class construction, or a mutable global container. It may include compiler-owned wrappers where the target runtime requires a shape not allowed in user source, such as Durable Object classes.

8. Provider Model

Providers are compile-time declaration files, not runtime lifecycle objects. A provider imported through @provider/* or @provider-dev/* imports app from .pioneer/autoload.ts, declares facts at top level, exports nothing, and does not import kernel facades. The provider surface centers on app.provide(canonicalPath, target, options?) and an explicit whitelist of declarations for aliases, tags, migrations, listeners, observers, policies, middleware aliases/groups, context extensions, config merges, translations, views, components, publish mappings, contextual bindings, and service extensions.

Provider declarations must use canonical bare nominal paths or aliases that resolve to canonical paths. Provider-key collisions are fatal because they make provider identity ambiguous. Alias collisions are handled by alias policy and do not replace nominal identity.

9. Kernel Entry Points

A kernel entry point self-identifies by importing one or more kernel facades from @find-how/pioneer and making top-level declarations. The kernel facade set is closed: Route, Artisan, Queue, Schedule, Broadcast, and Event. Middleware is HTTP route metadata and module-backed behavior, not a kernel facade.

Entry-point files have no exports. Handler references, middleware references, queue handlers, listener targets, and command handlers resolve through the same canonical identity and alias policy as provider registrations. The compiler rejects kernel entry points that require unavailable bindings or unresolved module-backed targets.

10. Binding And Identity Model

Pioneer distinguishes canonical identity from ergonomic names. A module-backed entity is identified by its resolved bare ESM module specifier. A generated data resource is identified by a compiler-generated resource key. Aliases are secondary names declared by providers; they must resolve to exactly one canonical identity in the relevant namespace before they can be used.

Binding access is static. Handlers and other consumed-by-DI modules receive a destructured view of the binding snapshot. Namespace-style and leaf-style access are both allowed when they can be resolved to the same nominal leaves. Dynamic member access, computed binding names, and runtime app.make(variable) are not production constructs.

11. Data And Model Resource Model

Database resources are generated from database config, registered migrations, migration SQL, schema introspection, database manager and driver bindings, and model declarations. Table identities use db:<connection>:<table>; column identities use db:<connection>:<table>.<column>; index identities use db:<connection>:<table>#<index>. Model identities use their bare module specifier.

Models bind to the data graph through Model.table(...) and feature references such as Model.use([...]). The compiler validates model fillable/hidden/cast/scope/feature requirements against generated data contracts and emits model contracts, database contracts, validation gates, TypeGraph resource records, and per-entrypoint resource snapshots.

12. Validation And Error Model

Every external trust boundary has a validation gate that accepts unknown and returns typed data or throws an operational error. Trust boundaries include HTTP request bodies, route params, query strings, environment variables, database rows, model hydration, queue payloads, third-party API responses, file reads, and runtime platform events.

Public APIs have three outcome categories. Expected absence returns T | null. Operational failure throws an Error produced by a component-owned error factory declared in contracts.d.ts. Developer error throws plain Error immediately. A single execution path must not conflate absence, operational failure, and invariant failure.

13. Generated Artifacts

A conforming compiler may emit a subset of these artifacts depending on target runtime and graph reachability:

• .pioneer/graph/autoload.json and .pioneer/graph/typegraph.json.

• .pioneer/graph/autoload.ts and .pioneer/graph/autoload.d.ts when requested.

• .pioneer/boot.ts and kernel-specific boot modules.

• Generated database contracts, model contracts, and validation gates.

• Provider, alias, tag, migration, listener, observer, policy, middleware, publish, config, and contextual binding manifests.

• Per-entrypoint binding snapshots and deployment resource snapshots.

• Proof certificates that bind source content hashes to passed rule sets.

Generated artifacts are compiler outputs. Source code must not treat generated manifests as a second registry that can override module graph facts.

13.1. Artifact Schema Requirements

Generated artifacts MUST be deterministic for the same normalized compiler input. JSON artifacts MUST use stable key ordering when written to disk. Generated TypeScript declaration artifacts MUST be type-checkable without importing runtime source that is not reachable from the same component.

Artifact consumers MUST treat unknown fields as non-normative extensions unless the artifact version declares them as required. Artifact producers MUST bump the artifact version when removing a required field or changing the interpretation of a required field.

14. Interoperability Requirements

Two conforming Pioneer compilers processing the same normalized inputs MUST agree on:

• source file classification;

• canonical bare nominal paths;

• provider keys and provider declaration records;

• alias namespace resolution results;

• generated data resource identities;

• kernel entry-point identities;

• binding snapshot membership;

• validation gate placement;

• proof certificate invalidation inputs.

Two conforming runtime emitters MAY produce different JavaScript module layouts, but they MUST preserve the same public contracts, validation behavior, error outcome categories, and Laravel parity behavior for the same reachable entry point.

15. Security And Privacy Considerations

Pioneer treats source discovery, generated artifacts, environment variables, database rows, external payloads, and deployment metadata as trust boundaries. A compiler MUST NOT allow unsafe casts, unchecked data hydration, runtime provider discovery, or mutable generated manifests to bypass validation gates.

Generated artifacts can reveal source topology, deployment resources, database schema, model shape, route shape, and private component names. Implementations SHOULD keep generated artifacts inside private build outputs unless explicitly published. This repository is confidential and proprietary; publication of this specification does not grant source, patent, or implementation rights.

16. Rule Catalog

The following rules are active. Rules are grouped by concern for readability, but the rule identifiers are stable and remain the normative reference targets.

16.1. Source Shape Rules

16.2. Binding And Provider Rules

16.3. Compiler, Kernel, Data, And Validation Rules

17. Examples

17.1. Canonical Identity Examples

Correct canonical path usage:

app.events.listen("@app/events/UserRegistered", "@app/listeners/SendWelcomeEmail");
Queue.job("@app/queues/ProcessOrder", "@app/queues/handlers/ProcessOrderHandler");
Route.get("/orders", "@app/http/handlers/ListOrders").middleware("@app/http/middleware/RateLimit");

Correct alias usage:

app.alias("@app/events/UserRegistered", "UserRegistered");
app.middleware.alias("@app/http/middleware/RateLimit", "rateLimit");

app.events.listen("UserRegistered", "@app/listeners/NotifyAdmins");
Route.get("/orders", "@app/http/handlers/ListOrders").middleware("rateLimit");

Compile error without a registered alias:

app.events.listen("UserRegistered", "@app/listeners/SendWelcomeEmail");

External trigger names, such as route paths, queue broker names, cron expressions, and Artisan signatures, are transport or user-facing metadata rather than canonical module identity.

17.2. Provider And Model Example

app.config.merge("database", "@app/config/database");
app.migrations("@app/database/migrations");
app.provide("@app/models/user", "@app/models/user");
app.alias("@app/models/user", "User");
app.provide(
  "@find-how/auth/model-features/authenticatable",
  "@find-how/auth/model-features/authenticatable",
);

export default Model
  .use(["@find-how/auth/model-features/authenticatable"])
  .table("users", {
    fillable: ["name", "email"],
    hidden: ["passwordHash"],
  });

The compiler resolves @app/models/user to Model.table("users"), the active database connection, db:edge:users, the migration-derived table type, and all feature requirements. User and users remain ergonomic names, not canonical identity.

17.3. Handler Destructuring Example

export default async ({ request, params, User, View }) => {
  const user = await User.find(params.id);
  if (user === null) {
    return View.notFound();
  }

  return View.render("users.show", { user });
};

The handler does not import or access app. The compiler treats the destructured parameter as a request for bindings from the active HTTP kernel snapshot. If User or View are unavailable in that snapshot, compilation fails before runtime.

18. Conformance And Diagnostics

A conforming implementation MUST reject source that violates any active rule. Diagnostics SHOULD name the rule identifier, the offending module, the relevant canonical identity when known, and the smallest actionable repair.

Every diagnostic record emitted to machine-readable output MUST contain:

Required diagnostic classes:

• Source-shape violations, such as user-authored classes, proxies, unsafe casts, public runtime annotations, or forbidden type predicates.

• Discovery violations, such as provider filesystem scans, provider boot methods, classmaps, package manifest framework metadata, or unresolved provider roots.

• Identity violations, such as unresolved aliases, non-canonical strings, extension-bearing module keys, alias collisions, or provider-key collisions.

• Binding violations, such as unavailable destructured bindings, dynamic container access, unavailable namespace members, or invalid contextual overrides.

• Data/model violations, such as ambiguous table sugar, unresolved model features, migration/model mismatches, or missing validation gates.

• Certification violations, such as stale proof certificates or conversion changes that lose public inference without declaration repair.

The following diagnostic code prefixes are reserved:

Conformance tests SHOULD include harvested Laravel parity tests, static rule fixtures, generated-artifact snapshots, TypeGraph edge checks, and end-to-end kernel emission tests for each supported runtime target.

Each normative rule SHOULD have at least one positive fixture and one negative fixture. Negative fixtures SHOULD assert a stable diagnostic code, rule identifier, and source location. Generated-artifact snapshot tests SHOULD ignore non-semantic ordering only when the artifact format explicitly allows it.

19. Deferred Topics

The following topics are not active rules in this version:

• Replication packs, adversarial verification, spec-to-artifact kill switches, and old replication-pack references.

• Public package metadata schemas for provider discovery.

• Runtime provider registration or runtime provider boot hooks.

• Rule numbers R36 and above.