@siremzam/sentinel 0.3.0 → 0.3.2

package/README.md

@@ -1,5 +1,10 @@
 # @siremzam/sentinel
 
+[![npm version](https://img.shields.io/npm/v/@siremzam/sentinel)](https://www.npmjs.com/package/@siremzam/sentinel)
+[![CI](https://github.com/vegtelenseg/sentinel/actions/workflows/ci.yml/badge.svg)](https://github.com/vegtelenseg/sentinel/actions/workflows/ci.yml)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/@siremzam/sentinel)
+[![license](https://img.shields.io/npm/l/@siremzam/sentinel)](./LICENSE)
+
 **TypeScript-first, domain-driven authorization engine for modern SaaS apps.**
 
 Most Node.js authorization libraries were built in the CRUD era — they model permissions as `create`, `read`, `update`, `delete` on "resources." But modern apps don't think that way. They think in domain verbs: `invoice:approve`, `project:archive`, `user:impersonate`.
@@ -14,6 +19,64 @@ This library was built from a different starting point:
 
 **Zero runtime dependencies. ~1,800 lines. 1:1 test-to-code ratio.**
 
+> ### Try it live
+>
+> **[Open the interactive playground →](https://vegtelenseg.github.io/sentinel-example/)**
+>
+> Policy editor, multi-tenant evaluation, explain traces, and audit log — all in the browser.
+> ([source](https://github.com/vegtelenseg/sentinel-example))
+
+---
+
+### What's New in 0.3.2
+
+- README rewrite: evaluation walkthrough, concepts glossary, patterns & recipes, migration guide, benchmark data
+- Standalone example (`examples/standalone/`) — no HTTP server needed
+- "When NOT to Use This" and "Testing Your Policies" sections
+
+See the full [CHANGELOG](./CHANGELOG.md).
+
+---
+
+## Table of Contents
+
+- [How It Compares](#how-it-compares)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [How Evaluation Works](#how-evaluation-works)
+- [Concepts](#concepts)
+- [Core Features](#core-features)
+  - [Policy Factory](#policy-factory)
+  - [Conditions (ABAC)](#conditions-abac)
+  - [Async Conditions](#async-conditions)
+  - [Wildcard Action Patterns](#wildcard-action-patterns)
+  - [Role Hierarchy](#role-hierarchy)
+  - [Priority and Deny Resolution](#priority-and-deny-resolution)
+  - [Multitenancy](#multitenancy)
+  - [Strict Tenancy](#strict-tenancy)
+  - [Condition Error Handling](#condition-error-handling)
+- [Observability](#observability)
+  - [Decision Events](#decision-events)
+  - [explain() — Debug Authorization](#explain--debug-authorization)
+  - [toAuditEntry()](#toauditentry)
+  - [permitted() — UI Rendering](#permitted--ui-rendering)
+- [Integration](#integration)
+  - [Middleware (Express, Fastify, NestJS)](#middleware)
+  - [Server Mode](#server-mode)
+  - [JSON Policy Serialization](#json-policy-serialization)
+- [Performance](#performance)
+  - [Evaluation Cache](#evaluation-cache)
+  - [Benchmarks](#benchmarks)
+- [Patterns and Recipes](#patterns-and-recipes)
+- [Testing Your Policies](#testing-your-policies)
+- [Migration Guide](#migration-guide)
+- [When NOT to Use This](#when-not-to-use-this)
+- [Security](#security)
+- [API Reference](#api-reference)
+- [Philosophy](#philosophy)
+- [Contributing](#contributing)
+- [License](#license)
+
 ---
 
 ## How It Compares
@@ -77,7 +140,11 @@ const { allow, deny } = createPolicyFactory<MySchema>();
 const engine = new AccessEngine<MySchema>({
   schema: {} as MySchema,
 });
+```
+
+> **Why `{} as MySchema`?** The `schema` field exists purely for TypeScript inference — it carries your type information through the engine at compile time. The runtime value is never read. Think of it as a type witness, not data.
 
+```typescript
 engine.addRules(
   allow()
     .id("admin-full-access")
@@ -164,13 +231,72 @@ const unsubscribe = engine.onDecision((d) => auditLog.write(toAuditEntry(d)));
 unsubscribe(); // when done
 ```
 
+> **[Open the playground →](https://vegtelenseg.github.io/sentinel-example/)** to see all of this running interactively.
+
 ---
 
-## Features
+## How Evaluation Works
 
-### createPolicyFactory
+When you call `engine.evaluate(subject, action, resource, context?, tenantId?)`, the engine runs this algorithm:
 
-Eliminates the `<MySchema>` generic parameter on every rule:
+```
+1. Resolve the subject's roles
+   └─ Filter role assignments by tenantId (if provided)
+   └─ Expand via role hierarchy (if configured)
+
+2. Find candidate rules
+   └─ For each rule: does role match? action match? resource match?
+   └─ Wildcard patterns ("invoice:*") are pre-compiled to regex at addRule() time
+
+3. Sort candidates
+   └─ Higher priority first
+   └─ At equal priority, deny rules sort before allow rules
+
+4. Evaluate candidates in order (first match wins)
+   └─ No conditions? → rule matches immediately
+   └─ Has conditions? → all conditions must return true
+   └─ Condition throws? → treated as false (fail-closed)
+
+5. Return decision
+   └─ Matched rule found → use its effect (allow or deny)
+   └─ No match → default deny
+```
+
+Every decision includes the matched rule (or null), a human-readable reason, evaluation duration, and full request context. Decisions with only unconditional rule matches are eligible for LRU caching.
+
+---
+
+## Concepts
+
+If you're new to authorization systems, here's a quick glossary:
+
+<details>
+<summary><strong>Expand glossary</strong></summary>
+
+| Term | Meaning |
+|---|---|
+| **RBAC** | Role-Based Access Control. Permissions are assigned to roles, users are assigned roles. |
+| **ABAC** | Attribute-Based Access Control. Permissions depend on attributes of the subject, resource, or environment — expressed as conditions. |
+| **Subject** | The entity requesting access — typically a user. Has an `id` and an array of `roles`. |
+| **Resource** | The thing being accessed — `"invoice"`, `"project"`, `"user"`. |
+| **Action** | What the subject wants to do to the resource — `"invoice:approve"`, `"project:archive"`. Uses `resource:verb` format. |
+| **Policy Rule** | A single authorization rule: "allow managers to perform invoice:approve on invoice." Has an effect (`allow` or `deny`), and optionally conditions, priority, and a description. |
+| **Condition** | A function attached to a rule that receives the evaluation context and returns `true` or `false`. Used for ABAC — e.g., "only if the user owns the resource." |
+| **Tenant** | An organizational unit in a multi-tenant system (e.g., a company). Users can have different roles in different tenants. |
+| **Decision** | The result of evaluating a request — contains `allowed`, the matched rule, timing, and a human-readable reason. |
+| **Effect** | Either `"allow"` or `"deny"`. Determines what happens when a rule matches. |
+| **Priority** | A number (default 0) that determines rule evaluation order. Higher priority rules are checked first. |
+| **Role Hierarchy** | A definition that one role inherits all permissions of another — e.g., `admin` inherits from `manager`. |
+
+</details>
+
+---
+
+## Core Features
+
+### Policy Factory
+
+`createPolicyFactory` eliminates the `<MySchema>` generic parameter on every rule:
 
 ```typescript
 import { createPolicyFactory } from "@siremzam/sentinel";
@@ -181,6 +307,129 @@ allow().roles("admin").anyAction().anyResource().build();
 deny().roles("viewer").actions("report:export").on("report").build();
 ```
 
+### Conditions (ABAC)
+
+Attach predicates to any rule. All conditions on a rule must pass for it to match:
+
+```typescript
+allow()
+  .roles("member")
+  .actions("invoice:update")
+  .on("invoice")
+  .when(ctx => ctx.subject.id === ctx.resourceContext.ownerId)
+  .when(ctx => ctx.resourceContext.status !== "finalized")
+  .build();
+```
+
+Conditions receive the full `EvaluationContext` — subject, action, resource, resourceContext, and tenantId. Stack multiple `.when()` calls; they are AND'd together.
+
+### Async Conditions
+
+For conditions that need database lookups or API calls:
+
+```typescript
+const engine = new AccessEngine<MySchema>({
+  schema: {} as MySchema,
+  asyncConditions: true,
+});
+
+engine.addRule(
+  allow()
+    .roles("member")
+    .actions("report:export")
+    .on("report")
+    .when(async (ctx) => {
+      const quota = await db.getExportQuota(ctx.subject.id);
+      return quota.remaining > 0;
+    })
+    .build(),
+);
+
+const decision = await engine.evaluateAsync(user, "report:export", "report");
+```
+
+When `asyncConditions` is enabled, use `evaluateAsync()`, `permittedAsync()`, and `explainAsync()` instead of their synchronous counterparts.
+
+### Wildcard Action Patterns
+
+Use `*` in action patterns to match groups of actions:
+
+```typescript
+// Match all invoice actions
+allow().roles("manager").actions("invoice:*" as MySchema["actions"]).on("invoice").build();
+
+// Match all read actions across resources
+allow().roles("viewer").actions("*:read" as MySchema["actions"]).anyResource().build();
+```
+
+Wildcard patterns are pre-compiled to regexes at `addRule()` time — no per-evaluation regex cost.
+
+### Role Hierarchy
+
+Define that higher roles inherit all permissions of lower roles:
+
+```typescript
+import { RoleHierarchy } from "@siremzam/sentinel";
+
+const hierarchy = new RoleHierarchy<MySchema>()
+  .define("owner", ["admin"])
+  .define("admin", ["manager"])
+  .define("manager", ["member"])
+  .define("member", ["viewer"]);
+
+const engine = new AccessEngine<MySchema>({
+  schema: {} as MySchema,
+  roleHierarchy: hierarchy,
+});
+
+engine.addRules(
+  allow().id("viewer-read").roles("viewer").actions("invoice:read").on("invoice").build(),
+  allow().id("member-create").roles("member").actions("invoice:create").on("invoice").build(),
+  allow().id("admin-approve").roles("admin").actions("invoice:approve").on("invoice").build(),
+);
+
+// Admins can read (inherited from viewer), create (from member), AND approve (their own)
+// Members can read (from viewer) and create, but NOT approve
+// Viewers can only read
+```
+
+Cycles are detected at definition time and throw immediately.
+
+### Priority and Deny Resolution
+
+- Higher `priority` wins (default: 0)
+- At equal priority, `deny` wins over `allow`
+- This lets you create broad deny rules with targeted allow overrides
+
+```typescript
+// Deny impersonation for everyone at priority 0
+deny().anyRole().actions("user:impersonate").on("user").build();
+
+// Allow it for owners at priority 10 — this wins
+allow().roles("owner").actions("user:impersonate").on("user").priority(10).build();
+```
+
+### Multitenancy
+
+Role assignments are tenant-scoped. When evaluating with a `tenantId`, only roles assigned to that tenant (or globally, with no tenantId) are considered:
+
+```typescript
+const user: Subject<MySchema> = {
+  id: "user-1",
+  roles: [
+    { role: "admin", tenantId: "acme-corp" },
+    { role: "viewer", tenantId: "globex" },
+    { role: "member" }, // global — applies in any tenant
+  ],
+};
+
+// In acme-corp context: user has admin + member roles
+engine.evaluate(user, "invoice:approve", "invoice", {}, "acme-corp");
+
+// In globex context: user has viewer + member roles
+engine.evaluate(user, "invoice:approve", "invoice", {}, "globex");
+```
+
 ### Strict Tenancy
 
 Prevents accidental cross-tenant access by requiring explicit `tenantId` when the subject has tenant-scoped roles:
@@ -211,22 +460,29 @@ const engine = new AccessEngine<MySchema>({
 });
 ```
 
-### permitted() — UI Rendering
+---
 
-Ask "what can this user do?" to drive button visibility and menu items:
+## Observability
+
+### Decision Events
+
+Every evaluation emits a structured `Decision` event. Subscribe at construction or at runtime:
 
 ```typescript
-const actions = engine.permitted(
-  user,
-  "invoice",
-  ["invoice:create", "invoice:read", "invoice:approve", "invoice:send"],
-  { ownerId: user.id },
-  "tenant-a",
-);
-// Set { "invoice:create", "invoice:read" }
-```
+import { toAuditEntry } from "@siremzam/sentinel";
 
-For async conditions, use `engine.permittedAsync()`.
+const engine = new AccessEngine<MySchema>({
+  schema: {} as MySchema,
+  onDecision: (decision) => {
+    const entry = toAuditEntry(decision);
+    auditLog.write(entry);
+  },
+});
+
+// Or at runtime
+const unsubscribe = engine.onDecision((d) => auditLog.write(toAuditEntry(d)));
+unsubscribe(); // when done
+```
 
 ### explain() — Debug Authorization
 
@@ -264,50 +520,121 @@ const entry = toAuditEntry(decision);
 // Safe to JSON.stringify — no functions, no circular references
 ```
 
-### Role Hierarchy
+### permitted() — UI Rendering
 
-Define that higher roles inherit all permissions of lower roles:
+Ask "what can this user do?" to drive button visibility and menu items:
 
 ```typescript
-import { RoleHierarchy } from "@siremzam/sentinel";
+const actions = engine.permitted(
+  user,
+  "invoice",
+  ["invoice:create", "invoice:read", "invoice:approve", "invoice:send"],
+  { ownerId: user.id },
+  "tenant-a",
+);
+// Set { "invoice:create", "invoice:read" }
+```
 
-const hierarchy = new RoleHierarchy<MySchema>()
-  .define("owner", ["admin"])
-  .define("admin", ["manager"])
-  .define("manager", ["member"])
-  .define("member", ["viewer"]);
+For async conditions, use `engine.permittedAsync()`.
 
-const engine = new AccessEngine<MySchema>({
-  schema: {} as MySchema,
-  roleHierarchy: hierarchy,
-});
+---
 
-engine.addRules(
-  allow().id("viewer-read").roles("viewer").actions("invoice:read").on("invoice").build(),
-  allow().id("member-create").roles("member").actions("invoice:create").on("invoice").build(),
-  allow().id("admin-approve").roles("admin").actions("invoice:approve").on("invoice").build(),
+## Integration
+
+### Middleware
+
+**Express:**
+
+```typescript
+import { guard } from "@siremzam/sentinel/middleware/express";
+
+app.post(
+  "/invoices/:id/approve",
+  guard(engine, "invoice:approve", "invoice", {
+    getSubject: (req) => req.user,
+    getResourceContext: (req) => ({ id: req.params.id }),
+    getTenantId: (req) => req.headers["x-tenant-id"],
+  }),
+  handler,
 );
+```
 
-// Admins can read (inherited from viewer), create (from member), AND approve (their own)
-// Members can read (from viewer) and create, but NOT approve
-// Viewers can only read
+**Fastify:**
+
+```typescript
+import { fastifyGuard } from "@siremzam/sentinel/middleware/fastify";
+
+fastify.post("/invoices/:id/approve", {
+  preHandler: fastifyGuard(engine, "invoice:approve", "invoice", {
+    getSubject: (req) => req.user,
+    getResourceContext: (req) => ({ id: req.params.id }),
+    getTenantId: (req) => req.headers["x-tenant-id"],
+  }),
+}, handler);
 ```
 
-Cycles are detected at definition time and throw immediately.
+**NestJS:**
 
-### Wildcard Action Patterns
+```typescript
+import {
+  createAuthorizeDecorator,
+  createAuthGuard,
+} from "@siremzam/sentinel/middleware/nestjs";
 
-Use `*` in action patterns to match groups of actions:
+const Authorize = createAuthorizeDecorator<MySchema>();
+
+const AuthGuard = createAuthGuard<MySchema>({
+  engine,
+  getSubject: (req) => req.user as Subject<MySchema>,
+  getTenantId: (req) => req.headers["x-tenant-id"] as string,
+});
+
+@Controller("invoices")
+class InvoiceController {
+  @Post(":id/approve")
+  @Authorize("invoice:approve", "invoice")
+  approve(@Param("id") id: string) {
+    return { approved: true };
+  }
+}
+
+app.useGlobalGuards(new AuthGuard());
+```
+
+No dependency on `@nestjs/common` or `reflect-metadata`. Uses a WeakMap for metadata storage.
+
+### Server Mode
+
+Run the engine as a standalone HTTP authorization microservice. This is useful when authorization logic needs to be shared across polyglot services (e.g., a Go API and a Python worker both calling the same policy engine), or when you want to decouple authorization decisions from your application servers entirely.
 
 ```typescript
-// Match all invoice actions
-allow().roles("manager").actions("invoice:*" as MySchema["actions"]).on("invoice").build();
+import { AccessEngine } from "@siremzam/sentinel";
+import { createAuthServer } from "@siremzam/sentinel/server";
 
-// Match all read actions across resources
-allow().roles("viewer").actions("*:read" as MySchema["actions"]).anyResource().build();
+const engine = new AccessEngine<MySchema>({ schema: {} as MySchema });
+engine.addRules(/* ... */);
+
+const server = createAuthServer({
+  engine,
+  port: 3100,
+  authenticate: (req) => {
+    return req.headers["x-api-key"] === process.env.AUTH_SERVER_KEY;
+  },
+  maxBodyBytes: 1024 * 1024, // 1 MB (default)
+});
+
+await server.start();
 ```
 
-Wildcard patterns are pre-compiled to regexes at `addRule()` time for performance.
+**Endpoints:**
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/health` | GET | Health check with rules count and uptime |
+| `/rules` | GET | List loaded rules (serialization-safe) |
+| `/evaluate` | POST | Evaluate an authorization request |
+
+Zero dependencies. Uses Node's built-in `http` module.
 
 ### JSON Policy Serialization
 
@@ -340,6 +667,10 @@ const rules = importRulesFromJson<MySchema>(json, conditions);
 
 Unknown condition names throw with a helpful error listing available conditions.
 
+---
+
+## Performance
+
 ### Evaluation Cache
 
 For hot paths where the same subject/action/resource is checked repeatedly:
@@ -360,99 +691,233 @@ engine.cacheStats;       // { size: 0, maxSize: 1000 }
 
 Only unconditional rule evaluations are cached — conditional results are always re-evaluated because they depend on `resourceContext`.
 
-### Server Mode
+### Benchmarks
 
-Run the engine as a standalone HTTP authorization microservice:
+Measured on Node v18.18.0, Apple Silicon (ARM64). Run `npm run benchmark` to reproduce.
 
-```typescript
-import { createAuthServer, AccessEngine } from "@siremzam/sentinel";
+| Scenario | 100 rules | 1,000 rules | 10,000 rules |
+|---|---|---|---|
+| `evaluate` (no cache) | 4.3 µs / 231k ops/s | 42.6 µs / 23k ops/s | 1,091 µs / 917 ops/s |
+| `evaluate` (cache hit) | 0.6 µs / 1.66M ops/s | 1.8 µs / 553k ops/s | 29.1 µs / 34k ops/s |
+| `evaluate` (all conditional) | 3.4 µs / 292k ops/s | 40.2 µs / 25k ops/s | 1,064 µs / 940 ops/s |
+| `permitted` (18 actions) | 60.2 µs / 17k ops/s | 718 µs / 1.4k ops/s | 18,924 µs / 53 ops/s |
+| `explain` (full trace) | 22.4 µs / 45k ops/s | 564 µs / 1.8k ops/s | 6,444 µs / 155 ops/s |
 
-const engine = new AccessEngine<MySchema>({ schema: {} as MySchema });
-engine.addRules(/* ... */);
+Most SaaS apps have 10–50 rules. At 100 rules, a single evaluation takes **4.3 µs** — you can run 230,000 authorization checks per second on a single core. With caching enabled, that drops to **0.6 µs**.
 
-const server = createAuthServer({
-  engine,
-  port: 3100,
-  authenticate: (req) => {
-    return req.headers["x-api-key"] === process.env.AUTH_SERVER_KEY;
-  },
-  maxBodyBytes: 1024 * 1024, // 1 MB (default)
-});
+---
 
-await server.start();
-```
+## Patterns and Recipes
 
-**Endpoints:**
+Real-world authorization scenarios and how to model them.
 
-| Endpoint | Method | Description |
-|---|---|---|
-| `/health` | GET | Health check with rules count and uptime |
-| `/rules` | GET | List loaded rules (serialization-safe) |
-| `/evaluate` | POST | Evaluate an authorization request |
+### Ownership — "Users can only edit their own resources"
 
-Zero dependencies. Uses Node's built-in `http` module.
+```typescript
+allow()
+  .id("edit-own-invoice")
+  .roles("member")
+  .actions("invoice:update")
+  .on("invoice")
+  .when(ctx => ctx.subject.id === ctx.resourceContext.ownerId)
+  .describe("Members can edit their own invoices")
+  .build();
+```
 
-### Middleware
+### Time-Gated Access — "Trial expires after 14 days"
 
-**Express:**
+```typescript
+allow()
+  .id("trial-access")
+  .roles("trial")
+  .actions("report:export")
+  .on("report")
+  .when(ctx => {
+    const createdAt = new Date(ctx.resourceContext.trialStartedAt as string);
+    const daysSince = (Date.now() - createdAt.getTime()) / (1000 * 60 * 60 * 24);
+    return daysSince <= 14;
+  })
+  .describe("Trial users can export for 14 days")
+  .build();
+```
+
+### Feature Flags — "Beta feature for specific tenants"
 
 ```typescript
-import { guard } from "@siremzam/sentinel/middleware/express";
+const BETA_TENANTS = new Set(["acme-corp", "initech"]);
 
-app.post(
-  "/invoices/:id/approve",
-  guard(engine, "invoice:approve", "invoice", {
-    getSubject: (req) => req.user,
-    getResourceContext: (req) => ({ id: req.params.id }),
-    getTenantId: (req) => req.headers["x-tenant-id"],
-  }),
-  handler,
-);
+allow()
+  .id("beta-analytics")
+  .anyRole()
+  .actions("analytics:view")
+  .on("analytics")
+  .when(ctx => BETA_TENANTS.has(ctx.tenantId ?? ""))
+  .describe("Analytics dashboard is in beta for select tenants")
+  .build();
 ```
 
-**Fastify:**
+### Async Conditions — "Check external quota service"
 
 ```typescript
-import { fastifyGuard } from "@siremzam/sentinel/middleware/fastify";
+allow()
+  .id("api-rate-limit")
+  .roles("member")
+  .actions("api:call")
+  .on("api")
+  .when(async ctx => {
+    const usage = await rateLimiter.check(ctx.subject.id);
+    return usage.remaining > 0;
+  })
+  .describe("Members can call API within rate limit")
+  .build();
+```
 
-fastify.post("/invoices/:id/approve", {
-  preHandler: fastifyGuard(engine, "invoice:approve", "invoice", {
-    getSubject: (req) => req.user,
-    getResourceContext: (req) => ({ id: req.params.id }),
-    getTenantId: (req) => req.headers["x-tenant-id"],
-  }),
-}, handler);
+### Broad Deny with Targeted Override
+
+```typescript
+// Deny all destructive actions at priority 0
+deny()
+  .id("freeze-destructive")
+  .anyRole()
+  .actions("project:delete", "project:archive")
+  .on("project")
+  .describe("Destructive project actions are frozen")
+  .build();
+
+// Allow owners to override at priority 10
+allow()
+  .id("owner-override")
+  .roles("owner")
+  .actions("project:delete", "project:archive")
+  .on("project")
+  .priority(10)
+  .describe("Owners can still delete/archive their projects")
+  .build();
 ```
 
-**NestJS:**
+### IP-Based Restriction via Async Condition
 
 ```typescript
-import {
-  createAuthorizeDecorator,
-  createAuthGuard,
-} from "@siremzam/sentinel/middleware/nestjs";
+allow()
+  .id("admin-from-office")
+  .roles("admin")
+  .actions("settings:update")
+  .on("settings")
+  .when(async ctx => {
+    const ip = ctx.resourceContext.clientIp as string;
+    const geo = await geoService.lookup(ip);
+    return geo.isOfficeNetwork;
+  })
+  .describe("Admin settings changes only from office network")
+  .build();
+```
 
-const Authorize = createAuthorizeDecorator<MySchema>();
+---
 
-const AuthGuard = createAuthGuard<MySchema>({
-  engine,
-  getSubject: (req) => req.user as Subject<MySchema>,
-  getTenantId: (req) => req.headers["x-tenant-id"] as string,
-});
+## Testing Your Policies
 
-@Controller("invoices")
-class InvoiceController {
-  @Post(":id/approve")
-  @Authorize("invoice:approve", "invoice")
-  approve(@Param("id") id: string) {
-    return { approved: true };
-  }
-}
+Authorization policies are security-critical code — they should be tested like any other business logic. The `explain()` method is purpose-built for this:
 
-app.useGlobalGuards(new AuthGuard());
+```typescript
+import { describe, it, expect } from "vitest";
+
+describe("invoice policies", () => {
+  it("allows managers to approve invoices in their tenant", () => {
+    const result = engine.explain(manager, "invoice:approve", "invoice", {}, "acme");
+
+    expect(result.allowed).toBe(true);
+    expect(result.reason).toContain("manager-invoices");
+  });
+
+  it("denies viewers from approving invoices", () => {
+    const result = engine.explain(viewer, "invoice:approve", "invoice", {}, "acme");
+
+    expect(result.allowed).toBe(false);
+    expect(result.reason).toBe("No matching rule — default deny");
+  });
+
+  it("respects ownership conditions", () => {
+    const result = engine.explain(
+      member,
+      "invoice:read",
+      "invoice",
+      { ownerId: "someone-else" },
+      "acme",
+    );
+
+    // Find the ownership rule and verify the condition failed
+    const ownershipRule = result.evaluatedRules.find(
+      e => e.rule.id === "member-own-invoices",
+    );
+    expect(ownershipRule?.conditionResults[0]?.passed).toBe(false);
+  });
+
+  it("prevents cross-tenant access", () => {
+    // User is admin in acme, viewer in globex
+    const resultAcme = engine.evaluate(user, "invoice:approve", "invoice", {}, "acme");
+    const resultGlobex = engine.evaluate(user, "invoice:approve", "invoice", {}, "globex");
+
+    expect(resultAcme.allowed).toBe(true);
+    expect(resultGlobex.allowed).toBe(false);
+  });
+});
 ```
 
-No dependency on `@nestjs/common` or `reflect-metadata`. Uses a WeakMap for metadata storage.
+`explain()` returns per-rule evaluation details — which rules matched on role, action, and resource, and which conditions passed or failed. This makes your tests self-documenting: when a test fails, the explain trace tells you exactly *why* the decision changed.
+
+---
+
+## Migration Guide
+
+### Coming from CASL
+
+| CASL | Sentinel |
+|---|---|
+| `defineAbility(can => { can('read', 'Article') })` | `allow().actions("article:read").on("article").build()` |
+| `ability.can('read', 'Article')` | `engine.evaluate(user, "article:read", "article")` |
+| `subject('Article', article)` | Actions use `resource:verb` format natively — no wrapper needed |
+| `conditions: { authorId: user.id }` | `.when(ctx => ctx.subject.id === ctx.resourceContext.authorId)` |
+| No multi-tenancy | Built-in: `{ role: "admin", tenantId: "acme" }` |
+| No explain/debug | `engine.explain()` gives per-rule trace |
+
+**Key difference:** CASL uses MongoDB-style conditions (declarative objects). Sentinel uses functions, which gives you full TypeScript expressiveness — async calls, date math, external lookups — with compile-time type safety on the context.
+
+### Coming from Casbin
+
+| Casbin | Sentinel |
+|---|---|
+| Model file (`model.conf`) | Pure TypeScript schema interface |
+| Policy file (`policy.csv`) | Fluent builder API or JSON import |
+| `e.Enforce("alice", "data1", "read")` | `engine.evaluate(user, "data:read", "data")` |
+| Custom matchers for ABAC | `.when()` conditions with full TypeScript |
+| Role manager | `RoleHierarchy` with cycle detection |
+
+**Key difference:** Casbin requires learning its own DSL for model definitions. Sentinel is pure TypeScript — your IDE autocompletes everything, and your policy definitions are type-checked at compile time.
+
+### Coming from accesscontrol
+
+| accesscontrol | Sentinel |
+|---|---|
+| `ac.grant('admin').createAny('video')` | `allow().roles("admin").actions("video:create").on("video").build()` |
+| CRUD only: create, read, update, delete | Domain verbs: `invoice:approve`, `order:ship` |
+| `ac.can('admin').createAny('video')` | `engine.evaluate(user, "video:create", "video")` |
+| No conditions/ABAC | Full ABAC with `.when()` conditions |
+| No multi-tenancy | Built-in per-tenant role assignments |
+
+**Key difference:** accesscontrol is locked into CRUD semantics. If your app has domain-specific actions (approve, archive, impersonate, ship), you'll fight the library. Sentinel treats domain verbs as first-class.
+
+---
+
+## When NOT to Use This
+
+Being honest about boundaries:
+
+- **You need a full policy language.** If you want Rego (OPA), Cedar (AWS), or a declarative DSL, this isn't that. Sentinel policies are TypeScript code, not a separate language.
+- **You need a Zanzibar-style relationship graph.** If your authorization model is "who can access this Google Doc?" with deeply nested sharing relationships, use [SpiceDB](https://authzed.com/) or [OpenFGA](https://openfga.dev/).
+- **You need a hosted authorization service.** If you want a managed SaaS solution rather than an embedded library, look at [Permit.io](https://permit.io/) or [Oso Cloud](https://www.osohq.com/).
+- **Your model is truly just CRUD on REST resources.** If `create`, `read`, `update`, `delete` is all you need and you don't have tenants, simpler libraries like [accesscontrol](https://www.npmjs.com/package/accesscontrol) may be sufficient.
+
+Sentinel is built for TypeScript-first SaaS applications with domain-specific actions, multi-tenant requirements, and a need for observable, testable authorization logic.
 
 ---
 
@@ -501,7 +966,7 @@ See [SECURITY.md](./SECURITY.md) for responsible disclosure instructions.
 
 | Option | Description |
 |---|---|
-| `schema` | Your schema type (used for type inference) |
+| `schema` | Your schema type (used for type inference, not read at runtime) |
 | `defaultEffect` | `"deny"` (default) or `"allow"` |
 | `onDecision` | Listener called on every evaluation |
 | `onConditionError` | Called when a condition throws (fail-closed) |
@@ -573,74 +1038,6 @@ Returned by `engine.explain()`:
 
 ---
 
-## Key Concepts
-
-### Domain Actions, Not CRUD
-
-Actions use `resource:verb` format: `invoice:approve`, `order:ship`, `user:impersonate`. Your domain language, not generic CRUD.
-
-### Conditions (ABAC)
-
-Attach predicates to any rule. All conditions on a rule must pass for it to match:
-
-```typescript
-allow()
-  .roles("member")
-  .actions("invoice:update")
-  .on("invoice")
-  .when(ctx => ctx.subject.id === ctx.resourceContext.ownerId)
-  .when(ctx => ctx.resourceContext.status !== "finalized")
-  .build();
-```
-
-### Async Conditions
-
-For conditions that need database lookups or API calls:
-
-```typescript
-const engine = new AccessEngine<MySchema>({
-  schema: {} as MySchema,
-  asyncConditions: true,
-});
-
-engine.addRule(
-  allow()
-    .roles("member")
-    .actions("report:export")
-    .on("report")
-    .when(async (ctx) => {
-      const quota = await db.getExportQuota(ctx.subject.id);
-      return quota.remaining > 0;
-    })
-    .build(),
-);
-
-const decision = await engine.evaluateAsync(user, "report:export", "report");
-```
-
-### Priority & Deny Resolution
-
-- Higher `priority` wins (default: 0)
-- At equal priority, `deny` wins over `allow`
-- This lets you create broad deny rules with targeted allow overrides
-
-### Multitenancy
-
-Role assignments are tenant-scoped. When evaluating with a `tenantId`, only roles assigned to that tenant (or globally, with no tenantId) are considered:
-
-```typescript
-const user: Subject<MySchema> = {
-  id: "user-1",
-  roles: [
-    { role: "admin", tenantId: "acme-corp" },
-    { role: "viewer", tenantId: "globex" },
-    { role: "member" }, // global — applies in any tenant
-  ],
-};
-```
-
----
-
 ## Philosophy
 
 1. **Policies belong in one place.** Not scattered across middleware, handlers, and services.