Apps and profiles

defineApp(policy, options) returns the policy with the app's sources, features and services bound to it. Pass the result wherever a policy goes: core createPermDock, every adapter and the CLI. Each one reads the app definition, and its own options win key by key.

// src/permdock.ts
import {
  approvalPolicies,
  defineApp,
  hostedPolicies,
  limits,
  memoryLimitStore,
} from "permdock";
import { memoryApprovalStore } from "permdock/approvals";
import { policy } from "./policy";

export const app = defineApp(policy, {
  memberships, // MembershipSource, or several
  customRoles, // CustomRoleSource
  relations, // RelationSource
  approvalPolicies: approvalPolicies(approvalPolicySource),
  policies: hostedPolicies(policySource),
  limits: limits(memoryLimitStore()),
  sink,
  store: memoryApprovalStore(),
  profile: process.env.NODE_ENV === "production" ? "prod" : "dev",
});

// src/server.ts
import { createPermDock } from "permdock/hono";
import { app } from "./permdock";

export const { protect, middleware } = createPermDock(app, { subject });

What an app holdsCopy Anchor Link

hostedPolicies, approvalPolicies and limits are features, not bare sources. The code that merges hosted grants, tightens approvals and counts quotas ships only with an app that imports them, so a plain RBAC app does not carry it.

ProfilesCopy Anchor Link

• dev fills in in-process defaults: one memory ApprovalStore that every adapter of the app shares, so a request opened through one adapter resumes through another, and limits(memoryLimitStore()) when a grant has a limit. The defaults come from defineApp, never from an adapter, so an adapter bundle carries no store. A new app runs before any infrastructure exists. Memory stores are per process: their state is lost on restart and is not shared between instances.
• prod fills in nothing. defineApp throws at startup when a grant requires approval and there is no store, or a grant has a limit and there are no limits. The alternative is an app that starts and then denies every such call at run time.

No adapter falls back to a memory store on its own. An approval store exists because the app or the adapter call named one, or because the profile is dev.

WhyCopy Anchor Link

Before defineApp, each adapter took its own copy of the same sources and services, and the CLI and the runtime named the same tables twice. A team that added a second surface (an MCP server next to a Next.js app) wired everything again and could miss the sink or the store on one of them. One app definition removes that duplication without a new interface: the result is still a Policy, so no adapter signature changes and an adapter option still overrides the app.

The profile makes the trade-off between a quick start and a safe production setup explicit. A memory store is right for the first hour and wrong in production. The dev profile gives it, prod refuses to start without the real one, and the choice is one line the reader can see.