@shaferllc/keel 0.59.0 → 0.68.0

package/AGENTS.md

@@ -0,0 +1,167 @@
+# AGENTS.md — working in Keel with an AI agent
+
+Guidance for AI coding agents (Claude Code, Cursor, …) editing **Keel** — the
+house framework for Node.js — or an app built on it. Humans: this is also a fast
+orientation. For prose guides see [`docs/`](./docs); for a machine-readable
+surface, run the [MCP server](#mcp-server-recommended).
+
+> **The fastest path:** connect the Keel MCP server (below) and call
+> `keel_overview` first. It returns conventions, the folder map, every doc
+> topic, and the generators. Then `keel_search_docs` / `keel_read_doc` for
+> depth, `keel_search_api` to find exports, `keel_scaffold` to generate code.
+
+---
+
+## What Keel is
+
+A small, legible MVC framework: a real **service container**, **service
+providers**, dot-notation **config**, expressive **routing**, active-record
+**models**, a **queue**, **auth**, and a code-generating **console**.
+[Hono](https://hono.dev) powers HTTP; everything above it is Keel's. The whole
+core is a few hundred lines per file in `src/core/` — read it, nothing is magic.
+
+## The one import rule
+
+Everything userland comes from a single entry point:
+
+```ts
+import { Router, Model, config, ServiceProvider } from "@shaferllc/keel/core";
+```
+
+- **In a consuming app** (the `keel-app` starter, or your own): use
+  `@shaferllc/keel/core`. This is what generated stubs emit.
+- **Inside this framework repo's example app** (`app/`, `routes/`, `bootstrap/`):
+  the code uses the `@keel/core` tsconfig **path alias** that points at
+  `src/core/`. Match the file you're editing — don't "fix" `@keel/core` to the
+  package name inside this repo.
+
+Never deep-import `@shaferllc/keel/core/model.js`. If a symbol isn't exported
+from `/core`, that's intentional. Find exports with `keel_search_api` or read
+`src/core/index.ts`.
+
+## Folder layout of a Keel app
+
+| Path | What lives there |
+|------|------------------|
+| `app/Controllers/` | Controller classes (resolved from the container → DI) |
+| `app/Providers/` | Service providers (`register()` then `boot()`) |
+| `app/Http/Middleware/` | Hono middleware handlers |
+| `app/Http/Kernel.ts` | The HTTP kernel — global middleware, error handling |
+| `app/Models/` | Active-record models extending `Model` |
+| `app/Jobs/`, `app/Notifications/`, `app/Transformers/` | Queue jobs, notifications, API serializers |
+| `config/*.ts` | Config files; read via `config("app.name")` |
+| `routes/web.ts` | Route definitions — default export receives the `Router` |
+| `database/factories/`, `database/seeders/`, `database/migrations/` | Data tooling |
+| `bootstrap/app.ts` | Assembles the `Application`, boots providers, loads routes |
+| `.env` | Environment, loaded into `env(...)` and config |
+
+## Core mental model
+
+1. **Container.** Every service is registered in and resolved out of the
+   container. `bind` (transient), `singleton` (once), `instance` (existing
+   value), `make(Token)` (resolve). Constructor injection: a controller/service
+   with `constructor(private app: Container)` gets it automatically.
+2. **Providers.** `register()` binds things into the container; `boot()` runs
+   after all providers registered, to wire things together. Register providers
+   in `bootstrap/providers.ts`.
+3. **Config.** `config("app.port", 3000)` reads `config/app.ts` merged with
+   `.env`. Dot-notation, with a default.
+4. **Routing.** `router.get("/x", [Controller, "method"])` or a closure. Name
+   routes with `.name()`, group with `.group()`, constrain params with
+   `.where()`, build URLs with `router.url("name", params)`.
+5. **Request context.** Inside a handler, `param()`, `query()`, `body()`,
+   `json()`, `text()` read/write the current request via async-local context —
+   no need to thread `c` everywhere (though the Hono `Ctx` is available).
+
+## How to add things (prefer the generators)
+
+Use `keel_scaffold` (MCP) or the console — both emit the correct stub with the
+right imports and target path. Then wire it up.
+
+| Goal | Command | Then |
+|------|---------|------|
+| Controller | `keel make:controller Post` (`-r` for REST) | add a route in `routes/web.ts` |
+| Provider | `keel make:provider Billing` | register in `bootstrap/providers.ts` |
+| Middleware | `keel make:middleware Auth` | attach in `app/Http/Kernel.ts` or per-route |
+| Model | *(no generator — extend `Model`)* | set `static table`; add relations |
+| Factory | `keel make:factory User` | reference the model |
+| Seeder | `keel make:seeder Database` | call factories in `run()` |
+| Job | `keel make:job SendWelcome` | `dispatch(new SendWelcomeJob())` |
+| Notification | `keel make:notification Paid` | `notify(user, new PaidNotification())` |
+| Transformer | `keel make:transformer User` | return it from a controller |
+
+**Scaffolding does not write files** via MCP — it returns code + path; you write
+it. The console (`keel make:*`) does write, and refuses to overwrite.
+
+A minimal controller and route:
+
+```ts
+// app/Controllers/PostController.ts
+import type { Ctx } from "@shaferllc/keel/core";
+export class PostController {
+  index(c: Ctx) { return c.json({ ok: true }); }
+}
+
+// routes/web.ts
+router.get("/posts", [PostController, "index"]).name("posts.index");
+```
+
+## Commands
+
+```bash
+npm run dev            # example app on http://localhost:3000 (tsx watch)
+npm run serve          # keel serve
+npm run keel -- routes # list registered routes
+npm run keel -- make:controller Foo
+npm run mcp            # start the MCP server over stdio (dev)
+npm test               # node --test over tests/*.test.ts
+npm run typecheck      # tsc --noEmit — run before you finish
+npm run build          # regenerate AI artifacts + compile to dist/
+npm run build:ai       # regenerate llms.txt, llms-full.txt, docs/ai-manifest.json
+```
+
+## Conventions & guardrails
+
+- **TypeScript, strict, ESM.** `.js` extensions in relative imports (NodeNext).
+  No default exports except where the pattern already uses them (routes).
+- **Match the surrounding file** — comment density, naming, idioms. Keel prizes
+  legibility; write code that reads like `src/core/`.
+- **Test with the real thing.** `TestClient`/`testClient` drives the HTTP stack
+  in-process; `hash.fake()`, `fakeDisk()`, `ArrayTransport`, `MemoryDriver`, and
+  `EventBuffer` make side-effecting subsystems deterministic. See
+  [`docs/testing.md`](./docs/testing.md).
+- **Run `npm run typecheck` before finishing.** The whole framework is typed end
+  to end; a green `tsc` is the bar.
+- **After editing docs or the export surface, run `npm run build:ai`** so
+  `llms.txt`, `llms-full.txt`, and `docs/ai-manifest.json` stay in sync (the MCP
+  server reads the manifest).
+
+## MCP server (recommended)
+
+Keel ships an MCP server exposing its docs, the full public API surface, the
+generators, and framework conventions to any MCP-capable agent.
+
+**Claude Code:**
+```bash
+claude mcp add keel -- npx -y keel-mcp        # in an app that depends on @shaferllc/keel
+```
+Or, hacking on the framework itself:
+```bash
+claude mcp add keel -- npm --prefix /path/to/keel run mcp
+```
+
+**`.mcp.json` / Cursor / other clients:**
+```json
+{ "mcpServers": { "keel": { "command": "npx", "args": ["-y", "keel-mcp"] } } }
+```
+
+Tools: `keel_overview`, `keel_search_docs`, `keel_read_doc`, `keel_search_api`,
+`keel_list_generators`, `keel_scaffold`. Resources: `keel://overview`,
+`keel://llms-full`, `keel://docs/<slug>`. See [`docs/ai.md`](./docs/ai.md).
+
+## Where to read next
+
+- [`docs/getting-started.md`](./docs/getting-started.md) — a guided first hour
+- [`docs/architecture.md`](./docs/architecture.md) — a request from socket to response
+- [`docs/container.md`](./docs/container.md) — the DI core everything rests on
+- [`llms-full.txt`](./llms-full.txt) — every guide in one file, for a fresh context

package/README.md

@@ -108,11 +108,38 @@ npm run keel serve --port 8080      # start the server on a chosen port
 npm run keel make:controller Post   # -> app/Controllers/PostController.ts
 npm run keel make:provider Billing  # -> app/Providers/BillingServiceProvider.ts
 npm run keel make:middleware Auth   # -> app/Http/Middleware/authMiddleware.ts
+npm run keel mcp                    # start the MCP server (docs + API for AI agents)
 ```
 
 Under the hood the console binary is `bin/keel.ts`; the npm scripts wrap it with
 `tsx`.
 
+## Built for AI ⚓🤖
+
+Keel is designed to be **written with an AI agent**. Alongside the human docs it
+ships a machine-readable surface that stays generated-in-sync, never stale:
+
+- **An MCP server.** `keel-mcp` exposes Keel's docs, its full public API (380+
+  exports), the generators, and its conventions to any [MCP](https://modelcontextprotocol.io)
+  client. Connect it in Claude Code:
+  ```bash
+  claude mcp add keel -- npx -y keel-mcp
+  ```
+  Tools: `keel_overview`, `keel_search_docs`, `keel_read_doc`, `keel_search_api`,
+  `keel_list_generators`, `keel_scaffold`. Resources: `keel://overview`,
+  `keel://llms-full`, `keel://docs/<slug>`.
+- **[`AGENTS.md`](./AGENTS.md).** The agent playbook — the one import rule, the
+  folder map, the container/provider model, a "how to add X" table, and the
+  guardrails. `CLAUDE.md` points to it.
+- **[`llms.txt`](./llms.txt) + [`llms-full.txt`](./llms-full.txt).** A
+  [spec-compliant](https://llmstxt.org) doc index and a one-file concatenation of
+  every guide, both shipped in the npm package for drop-in context.
+- **Generators an agent can drive.** `keel_scaffold` (or `keel make:*`) emits the
+  correct stub with the right imports and path for every construct.
+
+Full guide: **[docs/ai.md](./docs/ai.md)**. Regenerate the surface after doc or
+export changes with `npm run build:ai` (also runs automatically on `npm run build`).
+
 ## Project layout
 
 ```
@@ -191,7 +218,8 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [Redis](./docs/redis.md) | Pluggable client, memory driver, cache adapter |
 | [Logger](./docs/logger.md) | Structured logging, per-request `reqId`, redaction |
 | [Static Files](./docs/static-files.md) | serveStatic(), caching, dot-file safety |
-| [Storage](./docs/storage.md) | Pluggable disks (local/S3/R2), edge-safe |
+| [Storage](./docs/storage.md) | Pluggable disks (local/S3/R2), signed URLs, direct uploads |
+| [Health Checks](./docs/health.md) | `/health/live` + `/health/ready`, pluggable checks |
 | [Views](./docs/views.md) | Hono JSX components, layouts, the View service |
 | [Templates](./docs/templates.md) | `{{ }}` + `@`-tag templating engine, edge-safe |
 | [Middleware](./docs/middleware.md) | Global middleware, writing your own |
@@ -205,6 +233,7 @@ See [docs/architecture.md](./docs/architecture.md) for the full picture.
 | [The Console](./docs/console.md) | `serve`, `routes`, `make:*` generators |
 | [Architecture](./docs/architecture.md) | Container, kernel, request lifecycle |
 | [Built on Hono](./docs/hono.md) | The Hono layer underneath, and using it directly |
+| [Building with AI](./docs/ai.md) | MCP server, `AGENTS.md`, `llms.txt`, agent workflow |
 
 ## Testing
 

package/bin/keel-mcp.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Published entry for the Keel MCP server. Registered as the `keel-mcp` bin,
+// so an installed app can wire it up with `npx keel-mcp` (see docs/ai.md).
+import { runMcpServer } from "../dist/mcp/server.js";
+
+runMcpServer().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/core/application.d.ts

@@ -12,7 +12,7 @@ import { Config, type ConfigData } from "./config.js";
 import { Router } from "./http/router.js";
 import { View } from "./view.js";
 import { type ProviderClass } from "./provider.js";
-import type { Listener } from "./events.js";
+import type { Listener, EventName, EmitArgs, Resolve } from "./events.js";
 /** A configurator: a plain function that sets the app up and may return anything. */
 export type Configurator = (app: Application) => unknown;
 export interface BootOptions {
@@ -58,13 +58,13 @@ export declare class Application extends Container {
      * `app.on(...)` and the global `listen()` helper reach the same emitter.
      * Returns an unsubscribe function.
      */
-    on<T = unknown>(event: string, listener: Listener<T>): () => void;
+    on<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
     /** Subscribe for a single emission. Returns an unsubscribe function. */
-    once<T = unknown>(event: string, listener: Listener<T>): () => void;
+    once<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
     /** Unsubscribe a listener registered with `on()`/`once()`. */
-    off<T = unknown>(event: string, listener: Listener<T>): this;
+    off<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): this;
     /** Emit an app event, awaiting every listener in registration order. */
-    emit<T = unknown>(event: string, payload?: T): Promise<void>;
+    emit<T = unknown, E extends EventName = EventName>(event: E, ...args: EmitArgs<Resolve<T, E>>): Promise<void>;
     /** Merge a config object into the repository under its top-level keys. */
     private mergeConfig;
     /** Load .env via dotenv (Node only; no-op elsewhere). */

package/dist/core/application.js

@@ -95,8 +95,8 @@ export class Application extends Container {
         return this;
     }
     /** Emit an app event, awaiting every listener in registration order. */
-    async emit(event, payload) {
-        await this.make(Events).emit(event, payload);
+    async emit(event, ...args) {
+        await this.make(Events).emit(event, ...args);
     }
     /** Merge a config object into the repository under its top-level keys. */
     mergeConfig(data) {
@@ -168,9 +168,21 @@ export class Application extends Container {
         for (const provider of this.providers) {
             await provider.boot();
         }
+        // A provider's shutdown() joins the app's shutdown hooks, so it runs (LIFO)
+        // on terminate() alongside any onShutdown() a provider registered by hand.
+        // ready()/shutdown() are optional — plain duck-typed providers may omit them.
+        for (const provider of this.providers) {
+            if (typeof provider.shutdown === "function") {
+                this.onShutdown(() => provider.shutdown());
+            }
+        }
         this.booted = true;
         for (const hook of this.readyHooks)
             await hook(this);
+        for (const provider of this.providers) {
+            if (typeof provider.ready === "function")
+                await provider.ready();
+        }
         return this;
     }
     /**

package/dist/core/auth.d.ts

@@ -12,6 +12,7 @@
  *   await auth().user();      // the full user (via your provider)
  */
 import type { MiddlewareHandler } from "hono";
+import { type AccessToken } from "./tokens.js";
 /** Loads a user by the id stored in the session. Register with setUserProvider. */
 export type UserProvider = (id: string) => unknown | Promise<unknown>;
 /** Tell Keel how to load the authenticated user from its id. */
@@ -58,3 +59,49 @@ export declare function authGuard(options?: {
 export declare function bearerAuth(options?: {
     optional?: boolean;
 }): MiddlewareHandler;
+/**
+ * Verifies a Basic-auth credential pair. Return the authenticated user's id to
+ * log them in for the request (so `auth().user()` resolves through your
+ * provider), `true` to allow without an identity, or a falsy value to reject.
+ * Verify the password with `hash.verify` — and reach for `hash.dummy` on a miss
+ * so timing doesn't reveal which usernames exist.
+ */
+export type BasicVerifier = (username: string, password: string) => string | number | boolean | null | undefined | Promise<string | number | boolean | null | undefined>;
+/**
+ * HTTP Basic authentication. Reads `Authorization: Basic <base64>`, decodes the
+ * `username:password` pair, and hands it to your `verify` callback. On failure
+ * it answers `401` with a `WWW-Authenticate` challenge (so a browser prompts).
+ * Handy for internal tools and quick API gates — always behind HTTPS, since the
+ * credentials ride on every request.
+ *
+ *   router.get("/admin", handler).use(
+ *     basicAuth(async (user, pass) => {
+ *       const row = await findAdmin(user);
+ *       return (await hash.verify(row?.password ?? hash.dummy, pass)) && row ? row.id : false;
+ *     }),
+ *   );
+ */
+export declare function basicAuth(verify: BasicVerifier, options?: {
+    realm?: string;
+}): MiddlewareHandler;
+/**
+ * Opaque access-token auth — the revocable, ability-scoped counterpart to
+ * `bearerAuth()` (which verifies a stateless JWT). Reads `Authorization: Bearer
+ * keel_…`, verifies it against the [token store](./tokens.ts), and makes the
+ * token's owner the authenticated id — plus stashes the token itself so handlers
+ * can check abilities via `token()` / `tokenCan()`.
+ *
+ *   router.get("/api/posts", handler).use(tokenAuth({ abilities: ["posts:read"] }));
+ *
+ * Rejects a missing, invalid, expired, or under-scoped token with `401`. Pass
+ * `{ optional: true }` to let unauthenticated requests through.
+ */
+export declare function tokenAuth(options?: {
+    optional?: boolean;
+    abilities?: string[];
+    connection?: string;
+}): MiddlewareHandler;
+/** The opaque access token verified by `tokenAuth()` on this request, or null. */
+export declare function token(): AccessToken | null;
+/** Whether this request's access token grants an ability (`false` if there's none). */
+export declare function tokenCan(ability: string): boolean;

package/dist/core/auth.js

@@ -14,6 +14,7 @@
 import { session } from "./session.js";
 import { ctx } from "./request.js";
 import { jwt } from "./crypto.js";
+import { verifyToken, tokenAllows } from "./tokens.js";
 const KEY = "auth_id";
 let provider;
 /** Tell Keel how to load the authenticated user from its id. */
@@ -103,3 +104,79 @@ export function bearerAuth(options = {}) {
         await next();
     };
 }
+/**
+ * HTTP Basic authentication. Reads `Authorization: Basic <base64>`, decodes the
+ * `username:password` pair, and hands it to your `verify` callback. On failure
+ * it answers `401` with a `WWW-Authenticate` challenge (so a browser prompts).
+ * Handy for internal tools and quick API gates — always behind HTTPS, since the
+ * credentials ride on every request.
+ *
+ *   router.get("/admin", handler).use(
+ *     basicAuth(async (user, pass) => {
+ *       const row = await findAdmin(user);
+ *       return (await hash.verify(row?.password ?? hash.dummy, pass)) && row ? row.id : false;
+ *     }),
+ *   );
+ */
+export function basicAuth(verify, options = {}) {
+    const realm = options.realm ?? "Restricted";
+    return async (c, next) => {
+        const challenge = () => c.json({ error: "Unauthenticated", status: 401 }, 401, {
+            "WWW-Authenticate": `Basic realm="${realm}", charset="UTF-8"`,
+        });
+        const raw = c.req.header("authorization")?.match(/^Basic\s+(.+)$/i)?.[1];
+        if (!raw)
+            return challenge();
+        let decoded;
+        try {
+            decoded = new TextDecoder().decode(Uint8Array.from(atob(raw), (ch) => ch.charCodeAt(0)));
+        }
+        catch {
+            return challenge(); // not valid base64
+        }
+        const sep = decoded.indexOf(":");
+        if (sep === -1)
+            return challenge();
+        const result = await verify(decoded.slice(0, sep), decoded.slice(sep + 1));
+        if (!result)
+            return challenge();
+        if (result !== true)
+            c.set("auth_id", String(result));
+        await next();
+    };
+}
+/**
+ * Opaque access-token auth — the revocable, ability-scoped counterpart to
+ * `bearerAuth()` (which verifies a stateless JWT). Reads `Authorization: Bearer
+ * keel_…`, verifies it against the [token store](./tokens.ts), and makes the
+ * token's owner the authenticated id — plus stashes the token itself so handlers
+ * can check abilities via `token()` / `tokenCan()`.
+ *
+ *   router.get("/api/posts", handler).use(tokenAuth({ abilities: ["posts:read"] }));
+ *
+ * Rejects a missing, invalid, expired, or under-scoped token with `401`. Pass
+ * `{ optional: true }` to let unauthenticated requests through.
+ */
+export function tokenAuth(options = {}) {
+    return async (c, next) => {
+        const raw = c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+        const token = raw ? await verifyToken(raw, options.connection) : null;
+        const scoped = token && (options.abilities ?? []).every((a) => tokenAllows(token, a));
+        if (!token || !scoped) {
+            if (options.optional)
+                return next();
+            return c.json({ error: "Unauthenticated", status: 401 }, 401);
+        }
+        c.set("auth_id", token.tokenableId);
+        c.set("access_token", token);
+        await next();
+    };
+}
+/** The opaque access token verified by `tokenAuth()` on this request, or null. */
+export function token() {
+    return ctx().get("access_token") ?? null;
+}
+/** Whether this request's access token grants an ability (`false` if there's none). */
+export function tokenCan(ability) {
+    return tokenAllows(token(), ability);
+}

package/dist/core/authorization.d.ts

@@ -25,6 +25,8 @@ type Constructor = new (...args: never[]) => object;
 export type GateCallback = (user: User, ...args: Args) => boolean | Promise<boolean>;
 /** Runs before every check; return a boolean to short-circuit (e.g. admin bypass). */
 export type BeforeCallback = (user: User, ability: string, args: Args) => boolean | undefined | Promise<boolean | undefined>;
+/** Runs after every check; return a boolean to override the result (e.g. audit + veto). */
+export type AfterCallback = (user: User, ability: string, args: Args, result: boolean) => boolean | undefined | Promise<boolean | undefined>;
 /** Define a gate — an ad-hoc ability keyed by name. */
 export declare function define(ability: string, callback: GateCallback): void;
 /**
@@ -35,9 +37,15 @@ export declare function define(ability: string, callback: GateCallback): void;
 export declare function policy(model: Constructor, impl: object | (new () => object)): void;
 /** Register a callback that runs before every check (return a boolean to decide). */
 export declare function gateBefore(callback: BeforeCallback): void;
+/**
+ * Register a callback that runs *after* every check and can override its result
+ * — return a boolean to replace it, or `undefined` to keep it. Pairs with
+ * `gateBefore` to bracket every decision (logging, audit, a late veto).
+ */
+export declare function gateAfter(callback: AfterCallback): void;
 /** Override how the "current user" is resolved (default: `auth().user()`). */
 export declare function setUserResolver(resolver: () => User | Promise<User>): void;
-/** Reset gates, policies, the before-hook, and the resolver (test helper). */
+/** Reset gates, policies, hooks, and the resolver (test helper). */
 export declare function clearAuthorization(): void;
 /** Whether the current user is allowed the ability (with the given arguments). */
 export declare function can(ability: string, ...args: Args): Promise<boolean>;

package/dist/core/authorization.js

@@ -23,6 +23,7 @@ import { auth } from "./auth.js";
 const gates = new Map();
 const policies = new Map();
 let beforeCallback;
+let afterCallback;
 let userResolver = () => auth().user();
 /** Define a gate — an ad-hoc ability keyed by name. */
 export function define(ability, callback) {
@@ -41,18 +42,28 @@ export function policy(model, impl) {
 export function gateBefore(callback) {
     beforeCallback = callback;
 }
+/**
+ * Register a callback that runs *after* every check and can override its result
+ * — return a boolean to replace it, or `undefined` to keep it. Pairs with
+ * `gateBefore` to bracket every decision (logging, audit, a late veto).
+ */
+export function gateAfter(callback) {
+    afterCallback = callback;
+}
 /** Override how the "current user" is resolved (default: `auth().user()`). */
 export function setUserResolver(resolver) {
     userResolver = resolver;
 }
-/** Reset gates, policies, the before-hook, and the resolver (test helper). */
+/** Reset gates, policies, hooks, and the resolver (test helper). */
 export function clearAuthorization() {
     gates.clear();
     policies.clear();
     beforeCallback = undefined;
+    afterCallback = undefined;
     userResolver = () => auth().user();
 }
-async function evaluate(user, ability, args) {
+/** Resolve a check to a raw boolean, before the after-hook runs. */
+async function decide(user, ability, args) {
     if (beforeCallback) {
         const decided = await beforeCallback(user, ability, args);
         if (typeof decided === "boolean")
@@ -71,6 +82,15 @@ async function evaluate(user, ability, args) {
         return Boolean(await gate(user, ...args));
     return false; // unknown ability — deny by default
 }
+async function evaluate(user, ability, args) {
+    const result = await decide(user, ability, args);
+    if (afterCallback) {
+        const overridden = await afterCallback(user, ability, args, result);
+        if (typeof overridden === "boolean")
+            return overridden;
+    }
+    return result;
+}
 /** Whether the current user is allowed the ability (with the given arguments). */
 export async function can(ability, ...args) {
     return evaluate(await userResolver(), ability, args);

package/dist/core/cache.d.ts

@@ -5,6 +5,23 @@
  * the global `cache()` helper.
  *
  *   const stats = await cache().remember("stats", 60, () => computeStats());
+ *
+ * Features borrowed from bentocache (AdonisJS' cache), kept inside keel's
+ * single-store, edge-safe model:
+ *
+ *   - Stampede protection — concurrent `remember()` calls for the same cold key
+ *     run the factory ONCE and share the result, instead of dog-piling.
+ *   - Grace / stale-on-error — with a `grace` window, an expired value is kept
+ *     a little longer and served if the refreshing factory throws.
+ *   - Tags — group entries and invalidate them together with `deleteByTag()`.
+ *   - Namespaces — `namespace("users")` scopes keys under a prefix, and its
+ *     `flush()` clears only that namespace.
+ *
+ * Tag and namespace invalidation use version stamps, not a key index: each tag
+ * carries a counter, every entry records the counter values it was written at,
+ * and invalidation just bumps the counter — so an entry whose tag has moved on
+ * reads as a miss. O(1) invalidation, no key-set bookkeeping, works on any
+ * `CacheStore`.
  */
 export interface CacheStore {
     get(key: string): Promise<unknown> | unknown;
@@ -20,22 +37,82 @@ export declare class MemoryStore implements CacheStore {
     delete(key: string): void;
     clear(): void;
 }
+/** Options for `put`/`add`. */
+export interface PutOptions {
+    /** Tags to associate with this entry, for `deleteByTag` invalidation. */
+    tags?: string[];
+}
+/** Options for the `remember` family. */
+export interface RememberOptions extends PutOptions {
+    /**
+     * Grace window in seconds. After the value's TTL lapses, keep it this much
+     * longer and serve it if the refreshing factory throws (stale-on-error).
+     */
+    grace?: number;
+}
 export declare class Cache {
     private store;
     constructor(store?: CacheStore);
+    private prefix;
+    private nsTag?;
+    private inflight;
+    /** Apply this cache's namespace prefix to a logical key. */
+    private k;
+    private tagKey;
+    private tagVersion;
+    /** Snapshot the current version of each tag, to stamp onto a new entry. */
+    private stampTags;
+    /** True if any recorded tag version is behind the live one (invalidated). */
+    private tagsInvalidated;
+    /**
+     * Read the raw envelope for a key. Returns undefined when absent OR when a tag
+     * has invalidated it — tag/namespace invalidation is a hard miss (not grace-
+     * eligible). TTL freshness is left to callers, so grace can still see a stale
+     * entry.
+     */
+    private entry;
+    private write;
     get<T = unknown>(key: string, fallback?: T): Promise<T>;
-    /** Store a value, optionally expiring after `ttlSeconds`. */
-    put(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /** Store a value, optionally expiring after `ttlSeconds`, with optional tags. */
+    put(key: string, value: unknown, ttlSeconds?: number, options?: PutOptions): Promise<void>;
+    /** Store a value only if the key is absent. Returns whether it was written. */
+    add(key: string, value: unknown, ttlSeconds?: number, options?: PutOptions): Promise<boolean>;
     has(key: string): Promise<boolean>;
+    /** The inverse of `has` — true when the key is absent or expired. */
+    missing(key: string): Promise<boolean>;
     forget(key: string): Promise<void>;
+    /** Forget several keys at once. */
+    forgetMany(keys: string[]): Promise<void>;
     /** Read and remove a value. */
     pull<T = unknown>(key: string, fallback?: T): Promise<T>;
     flush(): Promise<void>;
+    /**
+     * Invalidate every entry carrying any of these tags by bumping the tag's
+     * version — entries stamped with the old version then read as a miss. O(#tags),
+     * no key scan; invalidated entries fall out on their own TTL.
+     */
+    deleteByTag(tags: string[]): Promise<void>;
+    /**
+     * A cache scoped under a key prefix. Keys written through it live at
+     * `name:key`, and its `flush()` clears only this namespace (via an implicit
+     * tag) — the rest of the store is untouched. Namespaces nest.
+     *
+     *   const users = cache().namespace("users");
+     *   await users.put("1", user);   // stored at "users:1"
+     *   await users.flush();          // clears only the users namespace
+     */
+    namespace(name: string): Cache;
     /**
      * Return the cached value, or compute it with `factory`, cache it for
      * `ttlSeconds`, and return it.
+     *
+     * Concurrent calls for the same cold key share one factory run (stampede
+     * protection). With `{ grace }`, an expired value is retained that many extra
+     * seconds and served if the refreshing factory throws (stale-on-error). With
+     * `{ tags }`, the cached value joins those tags for `deleteByTag`.
      */
-    remember<T>(key: string, ttlSeconds: number, factory: () => T | Promise<T>): Promise<T>;
-    /** Like remember(), but cached forever (no TTL). */
-    rememberForever<T>(key: string, factory: () => T | Promise<T>): Promise<T>;
+    remember<T>(key: string, ttlSeconds: number, factory: () => T | Promise<T>, options?: RememberOptions): Promise<T>;
+    /** Like remember(), but cached forever (no TTL). Also stampede-protected. */
+    rememberForever<T>(key: string, factory: () => T | Promise<T>, options?: PutOptions): Promise<T>;
+    private resolve;
 }