Pioneer Rules

1. Introduction

This specification is the active working table for Pioneer rules. The numbered rules below are normative unless marked otherwise. Examples and cleanup items are informative.

2. Rules

3. 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.

Data and model identity usage:

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.

4. Open Cleanup Items