@owlmeans/entrypoint 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -1,14 +1,13 @@
 # @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 + a route declaration + 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
@@ -18,99 +17,284 @@ entrypoint is registered in — `path()` walks the parent chain, `mount()` adds
 ## 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 createStoryEntrypoint = 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
-})
-```
+```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'
 
-## API
+const api = handlers<Context>()
 
-### `entrypoint(route, opts?): CommonEntrypoint`
+const create = api.body(storyProtocols.create, async (body, context, request) =>
+  context.story().create(makeEntityScope(request).requireEntityKey(), body))
 
-Creates an entrypoint. `opts` is typically produced by `filter()`, `guard()`, or `gate()`.
+const get = api.params(storyProtocols.get, async ({ id }, context) =>
+  context.story().get(id))
 
-### `guard(guard, opts?): CommonEntrypointOptions`
+export const serverBindings = [
+  bind(storyProtocols.base),
+  bind(storyProtocols.create, create),
+  bind(storyProtocols.get, get),
+]
+```
 
-Adds an authentication guard requirement.
+`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.
 
-### `gate(gate, params, opts?): CommonEntrypointOptions`
+### 3. Call the protocol from a client or another service
 
-Adds an authorization gate with parameters.
+```ts
+import { bindAll } from '@owlmeans/client-entrypoint'
+import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import { storyProtocols } from 'my-app-common'
 
-### `filter(filter, opts?): CommonEntrypointOptions`
+export const clientBindings = bindAll(storyProtocols)
 
-Attaches validation schemas (AJV format) to the entrypoint.
+// Later, with a context the bindings were registered in:
+const story = await context.entrypoint(storyProtocols.create).call({ body: { title: 'Invoices' } })
 
-### `body(schema, filter?) / query(schema, filter?) / params(schema, filter?)`
+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`)
+}
 
-Build a `Filter` object with the given AJV schema applied to the corresponding request part.
+const link = await context.entrypoint(storyProtocols.get).url({ params: { id: value.id } })
+```
 
-### Parentship
+`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.
 
-A child names its parent in the route declaration (`route('story-create', '/stories', { parent: 'api' })`).
-`path()` prefixes the parent's segments, and `getGuards()` / `getGates()` collect the parent's on
-every call — so a guard added to a parent later still applies.
+### 4. Gates, socket carriers, derived types
 
-### `provideResponse<T>(): AbstractResponse<T>`
+```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'
 
-Creates a response object for use in non-elevated handlers.
+const aliases = {
+  base: 'my-app:project:base', update: 'my-app:project:update',
+  watch: 'my-app:project:watch',
+} as const
 
-### Transport
+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>>
+```
 
-A route's protocol picks the carrier. Register a service under `transportAlias(protocol)` —
-`transport:<protocol>` — implementing `EntrypointTransport { protocol, handle }`, and every call to
-an entrypoint on that protocol goes through it. A consumer writes `ep.call(...)` and never learns
-whether that became an HTTP request, a socket message or a queued job. Without a registered
-transport the call goes over HTTP.
+### 5. Decorate a whole tree without flattening it
 
-### `EntrypointOutcome`
+```ts
+import { decorateEntrypoint, gatesOf, mapProtocols } from '@owlmeans/entrypoint'
+import { AUDIT_GUARD } from './consts.js'
+import { projectProtocols } from './protocols.js'
 
-```typescript
-enum EntrypointOutcome { Ok, Accepted, Created, Finished }
+// 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] }))
+
+// Resolve inherited gates without materializing anything (e.g. to hide a menu item).
+const gates = gatesOf(auditedProtocols.build, auditedProtocols)
 ```
 
-### Types
+`decorateEntrypoint` returns a new frozen protocol with the same request/response pair; the input
+tree and its protocols are left untouched.
+
+## API
 
-- `AbstractRequest<T>` — request with `params`, `body`, `query`, `headers`, `auth`
-- `AbstractResponse<T>` — response with `resolve(value, outcome?)` and `reject(error)`
-- `CommonEntrypoint` — entrypoint with `alias`, `route`, `handle`, and the context-computed
-  `segment()`, `path()`, `mount()`, `service()`, `address()`, `isLocal()`, `parent()`,
-  `getGuards()`, `getGates()`
-- `EntrypointTransport` — `{ protocol, handle }`, the service that carries a call for one protocol
+### 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 |
 
-## Related Packages
+### Transport
 
-- [`@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
+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
@@ -120,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.9",
-  "generatedAt": "2026-09-01T16:28:56.997Z",
+  "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,151 +1,98 @@
 ---
 name: entrypoint
-description: How to use @owlmeans/entrypoint — declarative entrypoint definitions over immutable route declarations, with entrypoint(), guard(), gate(), filter(), body(), params(), query() builders, the address accessors, and the transport seam. Auto-invoked when importing from this package or defining a service entrypoint declaration.
+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
 
-**Layer:** Core
-**Install:** `"@owlmeans/entrypoint": "^0.1.18-rc.9"` in `dependencies`
-
-An entrypoint is a **URL unit**: an immutable route declaration plus the guards, gates and schemas
-it answers under. It is the single concept an application declares once in a shared package and
-elevates on either side.
-
-## Key Exports
-
-| Export | Description |
-|--------|-------------|
-| `entrypoint(route, opts?)` | Declare an entrypoint on a route model |
-| `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)` / `params(Schema)` / `query(Schema)` / `headers(Schema)` / `response(Schema, code?)` | AJV validators composed into a `Filter` |
-| `CommonEntrypoint` | The entrypoint interface — declaration, guards/gates, address accessors |
-| `AbstractRequest` / `AbstractResponse` | The request and reply shapes every handler sees |
-| `provideResponse(original?)` | Build a reply object a handler resolves or rejects |
-| `GuardService` / `GateService` | What a guard and a gate implement |
-| `EntrypointOutcome` | Enum: Ok, Accepted, Created, Finished |
-| `EntrypointTransport` | `{ protocol, handle }` — a carrier bound to a route protocol |
-| `transportAlias(protocol?)` | The service alias a transport registers under (`transport:<protocol>`) |
-
-`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']))
-)
-```
-
-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.
-
-## Subpath Exports
-
-- `./utils` — entrypoint construction helpers (`isEntrypoint`, `CreateEntrypointSignature`)
-
-## Declaration and model
+**Install:** `bun add @owlmeans/entrypoint@^0.1.18`
 
-The `RouteDeclaration` an entrypoint carries is plain, immutable data: its `path` is the **segment**
-this entrypoint contributes under its parent, and nothing rewrites it. `RouteModel` only wraps that
-declaration. Every address question is therefore a question about the declaration asked **against
-the context that asks it** — computed on demand, never stored — so the same declaration answers one
-way in a server and another in a client without being touched.
+**Layer:** Core
 
-| Accessor | Answers |
-|----------|---------|
-| `segment()` | The segment declared under the parent |
-| `path()` | Every ancestor's segment, then this one |
-| `mount()` | `base` + `path()` — what a server registers and a client requests |
-| `service()` | The resolved service route this entrypoint answers on |
-| `address()` | `{ host, port, base, secure, protocol }` — where it actually answers |
-| `isLocal()` | Does it belong to the service the asking context IS? |
-| `parent()` | The parent entrypoint, or `null` |
-| `getGuards()` | Own guards plus every ancestor's, deduped |
-| `getGates()` | Own gate plus every ancestor's, as `[gate, params]` |
+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.
 
-`getGuards()` and `getGates()` walk the chain afresh on every call and are never memoised: a guard
-attached to an ancestor after this entrypoint was first asked still has to count.
+## Declare a named tree
 
-## Calling an entrypoint
+```ts
+import { contract, protocol, typed } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
 
-Three explicit verbs, so the caller says which answer it wants:
+const aliases = { base: 'project', create: 'project:create', get: 'project:get' } as const
+const projectBase = protocol(route(aliases.base, '/projects', backend()), contract(typed<void>()))
 
-```typescript
-const project = await ep.call({ params: { id } })            // the VALUE; the reply error is thrown
-const { value, outcome } = await ep.invoke({ body })         // value AND outcome
-const href = await ep.url({ params: { id } }, { absolute: true })   // the URL string
+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>())
+  ),
+}
 ```
 
-Use `invoke` only where the outcome decides what happens next; `call` covers everything else. An
-entrypoint that **renders a screen** is addressed by URL and never over the wire — it throws from
-`call()`/`invoke()` telling the caller to use `url()`.
-
-The three verbs sit on the callable entrypoint that `@owlmeans/client-entrypoint` produces; the
-declaration built here is what they address.
-
-## Elevation
-
-`elevate` replaces the declaration in the entrypoint list with its elevated counterpart, so it is
-**idempotent**: elevating the same alias again simply replaces the element once more. Guards passed
-at elevation are **unioned** with the ones the entrypoint declared — elevating adds guards, it never
-swaps them. Server-side elevation lives in `@owlmeans/server-entrypoint`, client-side callability is
-an explicit opt-in through `@owlmeans/client-entrypoint`.
-
-## Transport seam
-
-A route names the protocol it answers on, and a protocol may be carried by something other than
-HTTP. A service registered under `transportAlias(protocol)` implementing `EntrypointTransport` takes
-the call, so a consumer writes `ep.call(...)` and never learns whether that became an HTTP request,
-a socket message or a queued job. Bind nothing and the call goes over HTTP.
-
-```typescript
-import { transportAlias } from '@owlmeans/entrypoint'
-import type { EntrypointTransport } from '@owlmeans/entrypoint'
-import { RouteProtocols } from '@owlmeans/route'
-import { createService } from '@owlmeans/context'
-
-const transport = createService<EntrypointTransport>(transportAlias(RouteProtocols.SOCKET), {
-  protocol: RouteProtocols.SOCKET,
-  handle: async (req, res) => { /* carry the call, resolve or reject res */ }
-}, service => async () => { service.initialized = true })
-
-context.registerService(transport)
+- 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.
+
+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.
+
+## Contract sources
+
+| 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. |
+
+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`.
+
+`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.
+
+## 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,
+})
 ```
 
-## Usage
+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.
 
-Define entrypoints in a shared `common` package, then `elevate()` them with handlers in server/web packages:
-
-```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'
-
-export const managerEntrypoints = [
-  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))
-  ),
-]
-```
+## Bind, never replace
 
-## Depends On
+- 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`, `RouteProtocols`, and the address helpers under `/utils`
-- `@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/consts.d.ts

@@ -4,9 +4,4 @@ export declare enum EntrypointOutcome {
     Created = "created",
     Finished = "finished"
 }
-/**
- * Service alias a transport registers under. The default protocol is the web one, so an application
- * that binds nothing keeps talking HTTP.
- */
-export declare const transportAlias: (protocol?: string) => string;
 //# sourceMappingURL=consts.d.ts.map