This rulebook records the code patterns all repository source follows — packages, scripts, site and tests alike. AGENTS.md owns process boundaries and links here; architecture-rules.md governs how new architecture is designed. Read this before writing or changing code in any role. Numbering is stable; cite rules by number.
- Use Effection
function*generators withyield*; no Promises, async or await. - Use
@effectionx/fs, nevernode:fsdirectly and never synchronously; where@effectionx/fslacks an equivalent, adapt the runtime's async primitive as an operation. A synchronous site is allowed only to keep a named correctness invariant, carrying oneoxlint-disable-next-line local/no-sync-filesystemand a comment naming that invariant; there is no file-wide or directory-wide exemption. Enforced:local/no-sync-filesystem. - Convert a promise to an operation with
until, notcall. - Comment only surprising behavior; never what code does.
- Describe implemented behavior in the present tense; no roadmap language in specs or source.
- Parse to infer types; do not cast with
as. - No braceless
ifstatements. - Changes to release configuration require matching changes to specs/release-process-spec.md.
- Prefer stateless generators: use a plain function when it only returns another operation.
- Structure source through names and modules; no section-divider comments.
Enforced:
local/no-section-divider-comments(autofixes). - Prefer expanding Executable.md capabilities over JavaScript in documents; do not add JavaScript to an MD document without verifying with the user or planner. Authoring style: .agents/executable-style.md.
- Use contextual APIs for environment-specific behavior; shared production
modules neither access host APIs nor detect the runtime. Runtime-named entrypoints and adapters install host behavior —
packages/cli/src/{deno,node,bun,compiled}.tsare the CLI's;packages/test-supportis the tests' exempt boundary (#156). - Hand outcomes back as Effection
Result; no local ok-union types — put the success payload undervalueand the failure data on anError— and return a narrowed failure rather than rebuilding it. Enforced:local/prefer-effection-result(autofixes the rebuild). - Keep
maingreen — a process rule; its statement lives in AGENTS.md (Verification), kept under this number so citations stay stable. - State shared across loaded copies uses stable, namespaced names. Choose owned handles for instance operations, Context for scoped service selection, and contextual Api middleware for per-call composition. Security enforcement, durable identity and reconciliation never trust replaceable context state.
- An event listener installed by an operation has that operation's lifetime:
wait for one event with
once()from@effectionx/node/events, and a longer subscription binds a stable handler and removes that same handler in the owner's teardown —.off()for Node,.removeEventListener()with the matching capture mode for the DOM — with the cleanup established synchronously before the subscription: anensure()yielded after the subscription has established nothing. Where teardown must wait on the event itself, keep the handler through the wait and remove it in a synchronousfinallyinside that sameensure(). A native resource is never created before the cleanup that releases it, and only the resource's own closing event proves it is finished, never an assigned exit status. Each owner's child-reaping is held by a focused lifecycle regression. Full lifecycle rules: architecture.md. Enforced:local/require-scope-bound-event-registration(no autofix).