Naming

PermDock has one naming rule: the brand is the noun. The decision object is a PermDock, the variable is permdock, and the import path, not the identifier, says which framework you are in. Three verbs carry the rest: create* sets something up once at module scope, get* resolves it for one request on the server, and use* reads it on the client. Every package, docs page, skill, error message and example follows this page.

The rest follows from that rule:

• Core and permdock/pdp build an instance with getPermDock(policy, user), and getPermDockSync is its synchronous twin. An adapter's createPermDock runs once at module scope.
• A factory result is <Entry>PermDock (ServerPermDock, AgentPermDock). It hands out the instance through getPermDock(input) or middleware(), and mounts its endpoint through permdockHandler(); never a permdock() member.
• The decisions every app makes are methods on the instance (can, decide, decideEach, decideIds, decideFor). A feature's own request is a free function that takes the instance first (decideCredential(permdock, request), decideAutomation, decideSupportSession, decideRoleChange, activate, whoCan, simulateArazzo), so an app that does not import the feature does not ship it.
• A subject resolver is subjectFrom<Source>(input, options) and returns Subject<<Source>Principal>.
• An option is named after its interface (principals for a PrincipalSource, approvalPolicies for an ApprovalPolicySource), and store means only ApprovalStore.
• An in-process default is memory<Interface>, a runner is test<Interface>, an adapted source is <origin><Interface> and a verifier factory is <thing>Verifier.
• A context or prop type puts the adapter first (ExpressPermDockRequest, HonoPermDockEnv) and spells out Context.
• Signed outputs are vnd.permdock.<format>+jwt and CloudEvents types are com.permdock.<family>.

Renamed in 0.5.0 lists every name these rules changed; permdock codemod 0.5 applies them.

The core namesCopy Anchor Link

import { getPermDock, getPermDockSync } from "permdock"; // core: Promise<PermDock>, PermDock
import { createPermDock } from "permdock/next"; // Next.js: { getPermDock, getPermission, getSnapshot, requirePermission, PermDockProvider, permdockHandler }
import { createPermDock } from "permdock/hono"; // Hono: { middleware, protect, permdockHandler }
import { createPermDock } from "permdock/mcp"; // MCP: { protectServer }

Never a function that returns PermDock or a Promise depending on its inputs.

There is no NextDock, HonoDock, createNextPermDock or createMcpPermDock. When two adapters are used in one file, alias at the import: import { createPermDock as createHonoPermDock } from 'permdock/hono'. A factory that returns a handler or a store, not an instance, is named after what it returns, without create: evaluationsHandler, nativeStore.

use* on the client, get* on the serverCopy Anchor Link

React reads permissions synchronously from a snapshot; servers resolve them asynchronously per request. PermDock follows the duality next-intl uses for useTranslations / getTranslations and useExtracted / getExtracted:

requirePermission is the throwing member of the usePermission / getPermission set: same arguments, and a denial becomes the forbidden() or unauthorized() interrupt.

The client hooks and <Protected> are direct exports with no factory: the permission reference carries all the types, so usePermission(permissions.post.update, post) is fully typed without a generic wrapper. Only the server side needs a factory, because only the server holds the policy. describe(decision) is a framework-free core export used by every UI adapter and by Problem Details (UI). Vue keeps the use* composable names. Svelte does not: it exports setPermDock / getPermDock and readable stores (permission, permissions, filter, tenant, …) because Svelte has no React-style hooks. Solid uses accessor functions. The UI parity table lists them.

Definition and policy vocabularyCopy Anchor Link

Strings appear only as .key and .scope on the wire, in audit events and in catalogs. The public API takes references.

The subjectFrom<Provider> pattern names the source of the material (a JWT, a Supabase claims object, a Clerk auth object, a Better Auth session, MCP authInfo), always returns a Subject (anonymous when the material cannot be trusted) and never throws, so every provider reads the same way at the call site: createPermDock(policy, subjectFromClerk(await auth())). See Authentication and PermDock.

Reserved wordsCopy Anchor Link

These never appear as public identifiers, for the reasons given:

What each adapter's createPermDock returnsCopy Anchor Link

A server adapter's result hands out the instance through getPermDock(input) (permdock/server, permdock/node, permdock/next) or middleware() (Hono, h3, Express, Fastify, Elysia, SvelteKit, Astro, SolidStart, TanStack Start, tRPC, oRPC), and mounts PermDock's endpoint through permdockHandler(), which returns the framework's handler. permdock/terminal, permdock/openai, permdock/claude-agent and permdock/eve also return getPermDock. A result never has a permdock() member.

These entries deliberately do not export createPermDock:

• permdock and permdock/pdp export getPermDock and getPermDockSync. Core has nothing to set up ahead of a request, so its instance builder is the server getter itself.
• permdock/react and permdock/react-native export PermDockProvider, usePermDock, usePermission, usePermissions, useFilter, useTenant, useMemberships, useRoles, useAssignableRoles, useAssignablePermissions, useApproval, useSubject, useDescribe, useGate, useProtectedAction, the refreshOn trigger eventSourceRefresh and <Protected> directly. permdock/react-native adds subjectId (required, null when signed out), the storage wrappers memorySnapshotStorage, secureStoreStorage and mmkvStorage, the subscriptions appStateForeground and netInfoOnline, the Expo Router guards usePermissionGuard and useSnapshotReady, and the snapshot sources localSnapshot and powerSyncSource. permdock/vue exports permdockPlugin plus the same composable names and <Protected>. permdock/svelte and permdock/solid keep the same surface under each framework's idiom.
• permdock/better-auth, permdock/clerk and permdock/supabase export their subjectFrom* mapper and, where the provider stores roles, a <provider>CustomRoleSource; both are values you pass to a factory.
• permdock/webmcp exports registerTools(document.modelContext, group, { permdock }) because it consumes a client PermDock rather than creating one. permdock/drizzle, permdock/prisma and permdock/kysely export toWhere. permdock/prisma also exports permdockExtension, resolveRelated, toPredicate and prismaModelFields. All three also export withSubject and checkRow. permdock/jwt exports subjectFromJwt, jwtSubjectResolver, verifyDpopProof, joseTokenVerifier and joseTokenSigner because it produces subjects, verifiers and signers for a factory, not an instance. Structurally typed providers (permdock/supabase, permdock/clerk, permdock/better-auth, permdock/convex, permdock/prisma, permdock/mcp, permdock/react-native) declare no peer dependency: they duck-type the SDK you already installed. permdock/supabase/middleware is the exception on the Supabase side: it calls defineMiddleware, so @supabase/middleware is its optional peer, while @supabase/server's JWTClaims is still duck-typed.
• permdock/approvals exports memoryApprovalStore and approvalsHandler, and permdock/cloud exports cloud; both produce values you pass to a factory (store, sink, policies) or a client provider (source) rather than a PermDock.
• permdock/testing, permdock/testing/saas, permdock/testing/saas/permissions and permdock/testing/fixtures export the test runners (describePolicy, the test<Interface> runners, testRlsParity, testOrmParity, testClientParity, testHttpAdapter, testAuthzen) the shared SaaS domain and the example catalog and manifest (betterSupabaseCatalog, betterSupabaseManifest). Test files import them; application entries never do, and Vitest is an optional peer.
• permdock/cli exports defineConfig (for permdock.config.ts) and run (the permdock binary as a function) plus the config types, and parseHookMarker / parseGrantsMarker with their result types SupabaseHookMarker / SupabaseGrantsMarker. It is a build-time entry: no runtime entry imports it.
• Build hooks: permdock/next/plugin exports createPermDockPlugin and permdock/unplugin exports createPermDockUnplugin (Vite, Rollup, webpack, Rspack, esbuild through unplugin). Both run collect at build time and never wire runtime API. The create prefix and the PermDock noun follow the factory rule; the suffix names the host (Plugin for Next's config API, Unplugin for the bundler family).

Names shared on purposeCopy Anchor Link

• PermDock methods and snapshot fields share a name when the field is the method's result serialized: permdock.actions(resource) and snapshot.actions, permdock.audiences() and snapshot.audiences, permdock.snapshot() and a snapshot option or prop, permdock.tenant(id) and principal.tenant. The method is on the instance; the field is the wire form a client hydrates from.
• One name can be exported by several entries with that entry's meaning, like createPermDock. getPermDock returns the instance in every entry that exports it: core takes the policy and the user, an adapter's factory result takes the request or query, and permdock/svelte reads it from component context. PermDockPluginOptions is the build plugin's options in permdock/next/plugin and permdock/unplugin, and the Vue app plugin's options in permdock/vue.
• Every entry returns <Entry>PermDock from createPermDock and takes <Entry>PermDockOptions, rather than <Prefix><Thing>, so the entry is the first word wherever both appear (recorded in the repository's docs/decisions/0019-adapter-suffix-and-no-dollar-members.md). Context and prop types follow the same order: ExpressPermDockRequest, ConvexPermDockContext, NextPermDockProviderProps.

Spec namesCopy Anchor Link

PermDock's subject vocabulary is TypeScript, camelCase and typed; the specifications it consumes are JSON claims with short registered names. subject fixes the rule: where a spec name exists, PermDock either uses it verbatim or maps to it exactly once, in the table below and on subject; PermDock never coins a second spelling for a concept a specification already names.

Files and foldersCopy Anchor Link

• The server factory lives in src/permdock/server.ts in every example. The definition is src/permissions.ts; the policy is src/policy.ts; generated definitions are src/permissions.generated.ts.
• Example apps are apps/examples/<adapter>; the docs page is /docs/adapters/<adapter>; the source folder is packages/permdock/src/<adapter>. The same short name is used in all three.
• Errors are PermDockDeniedError, PermDockApprovalRequiredError, PermDockValidationError and PermDockRevokedError. Any other error class is a domain error with an is<Name> guard: ApprovalError and isApprovalError, AccessReviewError and isAccessReviewError, DirectoryUniquenessError and isDirectoryUniquenessError, DirectoryNotFoundError and isDirectoryNotFoundError, CloudAuthError and isCloudAuthError, plus InvalidSignatureError. Every guard matches by name and code, so an error from another copy of the module still maps. Problem Details type URIs end in /denied, /approval-required and /validation. The first two carry digest (React's name for the property that survives the Server Component boundary): PERMDOCK_DENIED;<permission> and PERMDOCK_APPROVAL_REQUIRED;<permission>;<token>, read with parsePermDockDigest.

Renamed in 0.5.0Copy Anchor Link

permdock codemod 0.5 applies these renames to every file that imports permdock (codemod). Entries are the imports the old name came from. The codemod reports method rows, and option rows outside the calls it knows, for a manual edit. pnpm docs:drift keeps this section equal to packages/permdock/src/cli/codemod/renames-0.5.ts.

These changed their call shape; the codemod lists each call site:

The CLI changed these commands and flags. An old spelling exits 2 with command_moved or flag_renamed and the new one. permdock codemod 0.5 rewrites them in package.json scripts, CI workflows and shell scripts, and lists them in Markdown:

Renamed before 0.1.0Copy Anchor Link