@owlmeans/entrypoint 0.1.18-rc.8 → 0.1.18

package/README.md

@@ -1,98 +1,300 @@
 # @owlmeans/entrypoint
 
-Entrypoint system — the URL unit abstraction shared between server and client in OwlMeans apps.
-
-## Overview
-
-- An **entrypoint** is a URL unit: an alias + path + optional guards/gates/filters
-- On the server, entrypoints become API routes with attached handlers
-- On the client, entrypoints provide URL generation and navigation
-- All AJV validation schemas are defined at entrypoint level, keeping data contracts consistent fullstack
-- Most commonly used via re-exports in `@owlmeans/server-app` or `@owlmeans/client-entrypoint`
+Entrypoint protocol system — the typed route contract shared between server and client in OwlMeans
+apps. An application uses it in its shared (`common`) package to declare every addressable unit —
+an HTTP API route, a socket or a screen — once, as an immutable protocol with typed
+request sections, a response type, AJV schemas and access rules. Runtime behaviour is not added
+here: the server attaches handlers with `@owlmeans/server-entrypoint` / `@owlmeans/server-api`, the
+client binds calls and screens with `@owlmeans/client-entrypoint`, and route shapes themselves come
+from `@owlmeans/route`. Code that only calls or handles an already declared protocol imports it from
+the shared package rather than declaring anything here.
+
+The route declaration an entrypoint carries is immutable: its `path` always stays the segment this
+entrypoint contributes under its parent. Addresses are computed on demand against the context the
+entrypoint is registered in — `path()` walks the parent chain, `mount()` adds the service base,
+`address()` picks host, port and scheme — so one declaration answers correctly on both sides.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/entrypoint
+bun add @owlmeans/entrypoint@^0.1.18
 ```
 
-## Usage
+## Concepts
+
+- **Protocol** — one immutable URL unit: an alias + route + typed contract + access options, made by
+  `protocol(route, contract, options?)`. The frozen object is the only cross-layer reference;
+  runtime code passes it (`context.entrypoint(protocols.x)`), never its alias string.
+- **Contract** — the compile-time request/response pair plus the runtime AJV schemas, made by
+  `contract(...)` or `contract.request({ body, params, query, headers }, response)` from `typed<T>()`
+  and `schema<T>()` sources. All validation lives at protocol level, keeping data contracts
+  consistent fullstack.
+- **Protocol tree** — an exported `*Protocols` object whose property names describe the contract.
+  Aliases stay private to the declaring module; the tree is flattened with `protocols(tree)` only at
+  registration.
+- **Access options** — `guards`, `gate` and `sticky` in `EntrypointOptions`. Guards and gates are
+  inherited through the route parent when a runtime binds the protocol.
+- **Binding / materialization** — a side-specific package turns a declaration into a context-bound
+  `CommonEntrypoint` (`materializeEntrypoint`) and adds a handler, a call or a screen. The declaration
+  itself is never mutated.
+- **Transport** — the route's protocol picks a built-in or package-owned carrier through a service
+  registered under `transportAlias(protocol)`; callers write `call()` and never branch on it.
 
-Define an entrypoint with body validation and a guard:
+## Usage
 
-```typescript
-import { entrypoint, guard, filter, body, params } from '@owlmeans/server-app'
-import { route } from '@owlmeans/route'
+### 1. Declare a typed protocol tree
+
+```ts
+import { contract, protocol, schema, typed } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+import type { JSONSchemaType } from 'ajv'
+
+export interface Story { id: string, title: string }
+export interface CreateStory { title: string }
+
+export const CreateStorySchema = schema<CreateStory>({
+  type: 'object',
+  properties: { title: { type: 'string', minLength: 1 } },
+  required: ['title'],
+  additionalProperties: false,
+} as JSONSchemaType<CreateStory>)
+
+// Private wire names — never exported.
+const aliases = {
+  base: 'my-app:story:base',
+  create: 'my-app:story:create',
+  get: 'my-app:story:get',
+} as const
+
+const base = protocol(route(aliases.base, '/stories', backend()), contract(), {
+  guards: DEFAULT_GUARD,
+})
 
-const createStoryModule = entrypoint(
-  route('story-create', '/stories', { method: 'POST', parent: 'api' }),
-  filter(body({
-    type: 'object',
-    properties: { story: { type: 'string' }, projectId: { type: 'string' } },
-    required: ['story', 'projectId']
-  }), guard('authenticated'))
-)
+export const storyProtocols = {
+  base,
+  create: protocol(
+    route(aliases.create, '/', backend({ parent: base, method: RouteMethod.POST })),
+    contract(CreateStorySchema, typed<Story>()),
+  ),
+  get: protocol(
+    route(aliases.get, '/:id', backend({ parent: base })),
+    contract.request({ params: typed<{ id: string }>() }, typed<Story>()),
+  ),
+} as const
 ```
 
-Use `AbstractRequest` type in a handler:
+`contract(body, response)` is a body-only contract; `contract.request(...)` types each request
+section independently. The children inherit `DEFAULT_GUARD` from `base`.
 
-```typescript
-import type { AbstractRequest } from '@owlmeans/entrypoint'
+### 2. Bind handlers on the server
 
-export const create = handleBody(async (body, context, request) => {
-  const req = request as AbstractRequest<{ id: string }>
-  const projectId = req.params.id
-})
-```
-
-## API
+```ts
+import { handlers } from '@owlmeans/server-api'
+import { bind } from '@owlmeans/server-entrypoint'
+import { makeEntityScope } from '@owlmeans/auth-common'
+import { storyProtocols } from 'my-app-common'
+import type { Context } from 'my-app-backend'
 
-### `entrypoint(route, opts?): CommonEntrypoint`
+const api = handlers<Context>()
 
-Creates an entrypoint. `opts` is typically produced by `filter()`, `guard()`, or `gate()`.
+const create = api.body(storyProtocols.create, async (body, context, request) =>
+  context.story().create(makeEntityScope(request).requireEntityKey(), body))
 
-### `guard(guard, opts?): CommonEntrypointOptions`
+const get = api.params(storyProtocols.get, async ({ id }, context) =>
+  context.story().get(id))
 
-Adds an authentication guard requirement.
+export const serverBindings = [
+  bind(storyProtocols.base),
+  bind(storyProtocols.create, create),
+  bind(storyProtocols.get, get),
+]
+```
 
-### `gate(gate, params, opts?): CommonEntrypointOptions`
+`body`, `params` and `id` are inferred from the protocol; no generic is named. The organization
+record id comes from the request (`makeEntityScope(request).requireEntityKey()`), never from the payload.
 
-Adds an authorization gate with parameters.
+### 3. Call the protocol from a client or another service
 
-### `filter(filter, opts?): CommonEntrypointOptions`
+```ts
+import { bindAll } from '@owlmeans/client-entrypoint'
+import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import { storyProtocols } from 'my-app-common'
 
-Attaches validation schemas (AJV format) to the entrypoint.
+export const clientBindings = bindAll(storyProtocols)
 
-### `body(schema, filter?) / query(schema, filter?) / params(schema, filter?)`
+// Later, with a context the bindings were registered in:
+const story = await context.entrypoint(storyProtocols.create).call({ body: { title: 'Invoices' } })
 
-Build a `Filter` object with the given AJV schema applied to the corresponding request part.
+const { value, outcome } = await context.entrypoint(storyProtocols.get)
+  .invoke({ params: { id: story.id }, timeout: 5_000 })
+if (outcome !== EntrypointOutcome.Ok) {
+  throw new Error(`Story ${story.id} was not loaded`)
+}
 
-### `parent(entrypoint, parentAlias): CommonEntrypoint`
+const link = await context.entrypoint(storyProtocols.get).url({ params: { id: value.id } })
+```
 
-Sets a parent-child relationship so child entrypoints inherit guards/gates.
+`call()` resolves the value, `invoke()` also returns the `EntrypointOutcome`, `url()` builds the
+address. `CallOptions` (`auth`, `host`, `base`, `unsecure`, `timeout`, `signal`) ride alongside the
+request sections and are never part of the payload contract.
 
-### `provideResponse<T>(): AbstractResponse<T>`
+### 4. Gates, socket carriers, derived types
 
-Creates a response object for use in non-elevated handlers.
+```ts
+import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+import type { HandlerRequest, RequestOf, ResponseOf } from '@owlmeans/entrypoint'
+import { backend, route, socket } from '@owlmeans/route'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+import { PROJECT_GATE } from './consts.js'
 
-### `EntrypointOutcome`
+const aliases = {
+  base: 'my-app:project:base', update: 'my-app:project:update',
+  watch: 'my-app:project:watch',
+} as const
 
-```typescript
-enum EntrypointOutcome { Ok, Accepted, Created, Finished }
+const base = protocol(route(aliases.base, '/projects', backend()), contract(), {
+  guards: DEFAULT_GUARD,
+  gate: { alias: PROJECT_GATE, params: 'my-app-project-{entity}' },
+})
+const updates = openProtocol(route(aliases.update, '/update'))
+
+export const projectProtocols = {
+  base,
+  updates,
+  // Carried over a WebSocket: the handler receives a connection, not a single reply.
+  watch: protocol(
+    route(aliases.watch, '/project/:id', socket({ parent: updates })),
+    contract.request({ params: typed<{ id: string }>() }, typed<void>()),
+  ),
+} as const
+
+type WatchRequest = HandlerRequest<RequestOf<typeof projectProtocols.watch>>
 ```
 
-### Types
+### 5. Decorate a whole tree without flattening it
+
+```ts
+import { decorateEntrypoint, gatesOf, mapProtocols } from '@owlmeans/entrypoint'
+import { AUDIT_GUARD } from './consts.js'
+import { projectProtocols } from './protocols.js'
 
-- `AbstractRequest<T>` — request with `params`, `body`, `query`, `headers`, `auth`
-- `AbstractResponse<T>` — response with `resolve(value, outcome?)` and `reject(error)`
-- `CommonEntrypoint` — entrypoint with `getAlias()`, `getPath()`, `getGuards()`, `handle`
+// Add a guard to every declaration while keeping the tree paths consumers bind by.
+export const auditedProtocols = mapProtocols(projectProtocols, declaration =>
+  decorateEntrypoint(declaration, { guards: [...declaration.guards, AUDIT_GUARD] }))
 
-## Related Packages
+// Resolve inherited gates without materializing anything (e.g. to hide a menu item).
+const gates = gatesOf(auditedProtocols.build, auditedProtocols)
+```
+
+`decorateEntrypoint` returns a new frozen protocol with the same request/response pair; the input
+tree and its protocols are left untouched.
+
+## API
 
-- [`@owlmeans/route`](../route) — `route()` factory used in `entrypoint(route(...), ...)`
-- [`@owlmeans/server-entrypoint`](../server-entrypoint) — server-side `elevate()` to attach handlers
-- [`@owlmeans/client-entrypoint`](../client-entrypoint) — client-side entrypoint with API call support
-- [`@owlmeans/server-app`](../server-app) — re-exports everything from this package
+### Protocol declaration (`.`)
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `protocol(route, contract, options?)` | function | Create an immutable, typed `EntrypointProtocol` |
+| `openProtocol(route, options?)` | function | Create an intentionally untyped protocol (`OpenRequest` / `OpenValue`) for escape hatches |
+| `contract(...)` | function | Body-only contract: `contract()`, `contract(response)`, `contract(body, response)` |
+| `contract.request(sections, response)` | function | Contract with independently typed `body`, `params`, `query`, `headers` |
+| `typed<T>(schema?)` | function | Type-only source, optionally paired with an AJV schema |
+| `schema<T>(jsonSchema)` | function | Brand a reusable AJV schema with its model type (`EntrypointSchema<T>`) |
+| `protocols(tree)` | function | Flatten an `EntrypointTree` to a declaration array for registration |
+| `mapProtocols(tree, mapper)` | function | Rebuild a frozen tree, transforming each declaration in place of its path |
+| `decorateEntrypoint(protocol, options)` | function | Clone a protocol with replaced `guards` / `gate` / `sticky` |
+| `gatesOf(protocol, tree)` | function | Gates a protocol inherits through its route parents, without materializing |
+| `isEntrypointProtocol(value)` | function | Type guard for a protocol declaration |
+| `entrypointRef<Request, Response>(alias)` | function | Typed reference for a dynamic remote address whose declaration cannot be imported |
+| `aliasOf(reference)` | function | Alias of a reference or string, for registry/transport adapters |
+| `materializeEntrypoint(protocol)` | function | Make a context-bindable `CommonEntrypoint` from a declaration (used by binding packages) |
+| `provideResponse<T>(original?)` | function | Create an `AbstractResponse<T>` for invoking a handler or guard outside a transport |
+| `transportAlias(protocol = 'http')` | function | Service alias `transport:<protocol>` a transport registers under |
+| `EntrypointOutcome` | enum | `Ok`, `Accepted`, `Created`, `Finished` — returned by `invoke()` and `resolve()` |
+
+### Contract and protocol types
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `EntrypointProtocol<Request, Response>` | interface | Typed immutable declaration; also a context reference to its registered entrypoint |
+| `EntrypointProtocolDeclaration` | interface | Runtime fields common to every protocol (`alias`, `route`, `contract`, `sticky`, `guards`, `gate`) |
+| `EntrypointContract<Request, Response>` | interface | Runtime schemas plus the compile-time pair |
+| `EntrypointOptions` | interface | `sticky`, `guards`, `gate: { alias, params }` |
+| `EntrypointGate` | interface | A resolved `{ alias, params }` gate |
+| `EntrypointTree` | interface | Nested object of protocols |
+| `RequestShape`, `OpenRequest`, `OpenValue` | types | Request section shape; the untyped request and value |
+| `Typed<T>`, `EntrypointSchema<T>`, `ShapeSource<T>` | types | Contract sources |
+| `RequestSources`, `RuntimeRequestSchemas`, `RuntimeResponseSchemas` | interfaces | Contract internals |
+| `RequestOf`, `ResponseOf`, `BodyOf`, `ParamsOf`, `QueryOf`, `HeadersOf`, `CallRequestOf` | types | Derive contract types from a protocol |
+| `HandlerRequest<Request>` | type | Typed request at a handler boundary, including transport metadata |
+| `EntrypointRequestMeta` | interface | `alias`, `auth`, `entity`, `path`, `canceled`, `cancel` |
+| `RegisteredEntrypoint<Request, Response>` | interface | Context-bound entrypoint with `call`, `invoke`, `url`, `validate` |
+| `CallOptions`, `CallArguments`, `UrlArguments` | types | Addressing/transport controls and argument tuples of `call` / `url` |
+| `EntrypointResult<Response>` | interface | `{ value, outcome }` returned by `invoke()` |
+| `MaterializedEntrypoint<Protocol>` | type | `CommonEntrypoint` carrying its `protocol` |
+
+### Runtime types
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `CommonEntrypoint` | interface | Bound entrypoint: `alias`, `route`, `sticky`, `guards`, `gate`, `gateParams`, `filter`, `handle`, and context-computed `segment()`, `path()`, `mount()`, `service()`, `address()`, `isLocal()`, `parent()`, `getGuards()`, `getGates()` |
+| `CommonEntrypointOptions` | interface | Partial `CommonEntrypoint` options |
+| `AbstractRequest<T>` | interface | Request with `alias`, `auth`, `entity`, `params`, `body`, `query`, `headers`, `path`, `timeout`, `signal` |
+| `AbstractResponse<T>` | interface | Response with `value`, `outcome`, `error`, `resolve(value, outcome?)`, `reject(error)` |
+| `ResolvedEntity` | interface | Organization as handlers see it: `id` (stable key), `slug`, `iamKey` |
+| `EntrypointHandler`, `EntrypointMatch`, `EntrypointAssert` | interfaces | Handler, guard-match and gate-assert signatures |
+| `GuardService` | interface | Guard service: `match`, `handle`, and client-side `authenticated`, `token` |
+| `GateService` | interface | Lazy gate service with `assert(req, res, params)` |
+| `Filter` | interface | AJV schemas by section (`query`, `params`, `body`, `response`, `headers`) |
+| `EntrypointTransport` | interface | `{ protocol, handle }` — the service that carries a call for one route protocol |
+
+### `@owlmeans/entrypoint/utils`
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `isEntrypoint(obj)` | function | Type guard for a materialized `CommonEntrypoint` |
+| `CreateEntrypointSignature<M>` | interface | `(route, opts?) => M` factory signature |
+
+### Transport
+
+Register a service under `transportAlias(protocol)` implementing `EntrypointTransport` and every
+call to an entrypoint on that route protocol goes through it. The package defining a custom
+protocol owns its transport and option validation. Without a registered transport the call goes
+over HTTP.
+
+## Common pitfalls
+
+- Do not export or import alias strings as an API. Keep them private to the declaration module and
+  pass protocol objects; raw aliases belong only in dynamic registry or transport adapters.
+- Do not use `openProtocol` just to skip declaring input or output types — it is for intentionally
+  untyped boundaries.
+- Use `typed<Model>(schema)` or `schema<Model>(...)` rather than a bare `JSONSchemaType<Model>`; a bare
+  AJV generic can widen a section to `OpenValue`.
+- Never mutate guards, gates, schemas or a declaration collection, and never replace an item in an
+  entrypoint array. Derive with `decorateEntrypoint` / `mapProtocols` and bind that exact object.
+- Reference a parent by its protocol object (`backend({ parent: base })`), not by its alias.
+- Do not construct contextual compatibility entrypoints or look a protocol up by alias with a generic;
+  use `entrypointRef` only when the declaration truly cannot be imported.
+- Callers use `call` / `invoke` / `url` and do not branch on the carrier — the route protocol and its
+  transport decide.
+- Inherited gates are deduplicated by gate service: a child declaring a gate under the same service
+  replaces its ancestor's gate for that service rather than adding to it.
+- `request.entity` is set only where authentication ran `makeEntityScope(request).attachEntity(context)`; handlers key records by
+  `entity.id` (via `makeEntityScope(request).requireEntityKey()` / `.requireEntity()` from `@owlmeans/auth-common`), never by the
+  token's `entitySlug`.
+
+## Related packages
+
+- [`@owlmeans/route`](../route) — `route()`, `backend()`, `socket()`, `frontend()` used in `protocol(route(...), ...)`
+- [`@owlmeans/context`](../context) — `BasicEntrypoint`, `EntrypointReference` and `context.entrypoint(...)`
+- [`@owlmeans/server-entrypoint`](../server-entrypoint) — server-side `bind()` / `bindAll()` to attach handlers
+- [`@owlmeans/server-api`](../server-api) — `handlers<Context>()` with protocol-inferred `body` / `params` / `request`
+- [`@owlmeans/server-socket`](../server-socket) — `connection(protocol, handler)` for socket protocols
+- [`@owlmeans/client-entrypoint`](../client-entrypoint) — client `bind()`, `bindAll()`, `bindScreen()` with typed calls
+- [`@owlmeans/auth-common`](../auth-common) — guard aliases and entity helpers used in access options and handlers
+- [`@owlmeans/server-app`](../server-app) — re-exports `contract`, `protocol`, `typed`, `EntrypointOutcome` and the request/response types
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -102,7 +304,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/entrypoint",
-  "version": "0.1.18-rc.7",
-  "generatedAt": "2026-08-24T21:14:00.139Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.766Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/entrypoint/SKILL.md

@@ -1,76 +1,98 @@
 ---
 name: entrypoint
-description: How to use @owlmeans/entrypoint — declarative entrypoint/route definitions with entrypoint(), guard(), gate(), filter(), body(), params(), query() builders. Auto-invoked when importing from this package or defining a service entrypoint declaration. Also covers the deprecated @owlmeans/module reexport shim (module() → entrypoint()).
+description: How to declare immutable, typed @owlmeans/entrypoint protocols with protocol(), contract(), typed(), protocol trees, guards, gates, and route transports. Load before defining a shared API, socket, or screen contract.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
 # @owlmeans/entrypoint
 
+**Install:** `bun add @owlmeans/entrypoint@^0.1.18`
+
 **Layer:** Core
-**Install:** `"@owlmeans/entrypoint": "^0.1.18-rc.7"` in `dependencies`
-
-## Key Exports
-
-| Export | Description |
-|--------|-------------|
-| `entrypoint(route, opts?)` | Declare an entrypoint on a route |
-| `guard(alias, opts?)` | Require a guard; returns options, so it wraps rather than takes them |
-| `gate(alias, params, opts?)` | Require a gate; passed as the `opts` of `guard(...)` |
-| `filter(filter, opts?)` | Attach request validators |
-| `body(Schema)` | AJV body validator |
-| `params(Schema)` | URL params validator |
-| `query(Schema)` | Query string validator |
-| `ClientEntrypoint<T>` types | Resolved entrypoint type used for `ctx.entrypoint<...>(alias).call(...)` |
-| `EntrypointOutcome` | Enum: Ok, Accepted, Created, Finished |
-| Constants | Built-in entrypoint aliases |
-
-`guard`, `gate` and `filter` are **options-object combinators, not variadic composers**. Each
-returns a `CommonEntrypointOptions` and takes the next one as its final argument, so they nest:
-
-```typescript
-entrypoint(
-  route(app.api.item.remove, '/:id', { parent: app.api.item, method: RouteMethod.DELETE }),
-  guard(DEFAULT_GUARD, gate(OIDC_GATE, ['item--delete@id']))
-)
+
+An entrypoint protocol is the immutable shared contract for one addressable route. It owns the
+route, typed request sections, response type, schemas, guards, gate, and sticky flag. Server and
+client behaviour is added only by the corresponding binding package.
+
+## Declare a named tree
+
+```ts
+import { contract, protocol, typed } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
+
+const aliases = { base: 'project', create: 'project:create', get: 'project:get' } as const
+const projectBase = protocol(route(aliases.base, '/projects', backend()), contract(typed<void>()))
+
+export const projectProtocols = {
+  base: projectBase,
+  create: protocol(
+    route(aliases.create, '/', backend({ parent: projectBase, method: RouteMethod.POST })),
+    contract.request({ body: typed<CreateProject>(CreateProjectSchema) }, typed<Project>()),
+    { guards: DEFAULT_GUARD }
+  ),
+  get: protocol(
+    route(aliases.get, '/:id', backend({ parent: projectBase })),
+    contract.request({ params: typed<{ id: string }>() }, typed<Project>())
+  ),
+}
 ```
 
-Guards and gates are **inherited by child entrypoints** and enforced by the framework before a
-handler runs — a handler that re-checks them is duplicating an enforced rule, and is wrong even
-when it agrees.
+- Export a `*Protocols` object whose property names describe the contract. Its protocol values are
+  the only cross-layer references. Flatten it with `protocols(projectProtocols)` only at registration.
+- Use `protocol(route, contract, options?)` for every typed boundary.
+- `openProtocol(route, options?)` is an intentional untyped escape hatch; do not use it merely to
+  avoid declaring an input or output type.
+- Use `decorateEntrypoint(protocol, options)` only when deriving an immutable decoration; never
+  mutate guards, gates, schemas, or a declaration collection.
 
-## Subpath Exports
+Keep aliases private to this module. A child should use its parent protocol object
+(`backend({ parent: projectBase })`); route creation stores its alias. Normal application code
+imports protocol objects, while raw aliases are limited to dynamic registry or transport adapters.
 
-- `./utils` — entrypoint construction helpers (`isEntrypoint`, `CreateEntrypointSignature`)
+## Contract sources
 
-## Usage
+| Source | Use |
+|---|---|
+| `typed<Model>(schema)` | A type paired with its AJV runtime validator. Prefer at declaration boundaries. |
+| `typed<Model>()` | A type-only request section or response. |
+| `schema<Model>(schema)` | A reusable named typed AJV schema. |
+| `contract(body, response)` | A body-only contract. |
+| `contract.request({ body, params, query, headers }, response)` | Independently typed request sections. |
 
-Define entrypoints in a shared `common` package, then `elevate()` them with handlers in server/web packages:
+Use `typed<Model>(schema)` rather than a bare `JSONSchemaType<Model>` when the model must remain
+exact. A bare AJV generic can widen a protocol section to `OpenValue`.
 
-```typescript
-import { entrypoint, guard, gate, filter, body } from '@owlmeans/entrypoint'
-import { route, RouteMethod } from '@owlmeans/route'
-import { DEFAULT_GUARD } from '@owlmeans/auth-common'
-import { OIDC_GATE } from '@owlmeans/oidc'
-import { CreateProjectSchema } from './schemas.js'
+`RequestOf<Protocol>`, `ResponseOf<Protocol>`, `BodyOf<Protocol>`, `ParamsOf<Protocol>`,
+`QueryOf<Protocol>`, and `HeadersOf<Protocol>` derive the contract types. A handler receives
+`HandlerRequest<RequestOf<Protocol>>`, which includes the transport metadata as well as the typed
+sections. Use `entrypointRef<Request, Response>(alias)` only for a dynamic remote address whose
+declaration is unavailable to import.
 
-export const managerModules = [
-  entrypoint(
-    route(manager.back.account.base, '/account'),
-    guard(DEFAULT_GUARD, gate(OIDC_GATE, [`my-service-account-{entity}`]))
-  ),
-  entrypoint(
-    route(manager.back.project.create, '/create', {
-      parent: manager.back.project.base,
-      method: RouteMethod.POST,
-    }),
-    filter(body(CreateProjectSchema))
-  ),
-]
+## Authorization and addressing
+
+Add `guards`, `gate`, and `sticky` directly in `EntrypointOptions`:
+
+```ts
+protocol(route(...), contract(...), {
+  guards: [DEFAULT_GUARD, AUDIT_GUARD],
+  gate: { alias: PROJECT_GATE, params: ['project--read@id'] },
+  sticky: true,
+})
 ```
 
-## Depends On
+Guards and gates are inherited through the parent route by the bound runtime entrypoint. A route's
+protocol chooses the built-in or package-owned carrier; callers only use `call`, `invoke`, or `url`
+on the client-bound protocol and do not branch on a transport.
+
+## Bind, never replace
+
+- Server: `bind(protocol, handlers<Context>().body|params|request(...))` from
+  `@owlmeans/server-entrypoint` / `@owlmeans/server-api`.
+- Socket: `bind(protocol, connection(protocol, handler))`.
+- Client API route: `bind(protocol)` or `bindAll(tree)` from `@owlmeans/client-entrypoint`.
+- Client screen: `bindScreen(protocol, componentHandler)`.
 
-- `@owlmeans/route` — `route()`, `RouteMethod`
-- `@owlmeans/auth-common` — guard aliases (`DEFAULT_GUARD`)
-- `@owlmeans/error`, `@owlmeans/i18n`
+Do not construct contextual compatibility entrypoints, look a protocol up by alias with a generic,
+or replace an item in an entrypoint array. Import the declaration and bind that exact object. This
+keeps declarations immutable and lets TypeScript infer requests and replies end to end.

package/build/entrypoint.d.ts

@@ -1,5 +1,4 @@
 import type { CommonEntrypoint } from './types.js';
 import type { CreateEntrypointSignature } from './utils/types.js';
 export declare const entrypoint: CreateEntrypointSignature<CommonEntrypoint>;
-export declare const parent: <T extends CommonEntrypoint | CommonEntrypoint[]>(ep: T, aliasOrParent: string, _parent?: string) => T;
 //# sourceMappingURL=entrypoint.d.ts.map

package/build/entrypoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entrypoint.d.ts","sourceRoot":"","sources":["../src/entrypoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAA;AAEjE,eAAO,MAAM,UAAU,EAAE,yBAAyB,CAAC,gBAAgB,CAqFlE,CAAA;AAED,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,gBAAgB,GAAG,gBAAgB,EAAE,MAAM,CAAC,iBAAiB,MAAM,YAAY,MAAM,KAAG,CAcxH,CAAA"}
+{"version":3,"file":"entrypoint.d.ts","sourceRoot":"","sources":["../src/entrypoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGlD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAA;AAEjE,eAAO,MAAM,UAAU,EAAE,yBAAyB,CAAC,gBAAgB,CAkElE,CAAA"}