@owlmeans/entrypoint 0.1.18-rc.11 → 0.1.18-rc.12

package/README.md

@@ -120,7 +120,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@^0.1.18-rc.12
+npx @owlmeans/agent-skills@^0.1.18-rc.13
 ```
 
 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,
   "package": "@owlmeans/entrypoint",
-  "version": "0.1.18-rc.11",
-  "generatedAt": "2026-09-04T22:43:25.452Z",
+  "version": "0.1.18-rc.12",
+  "generatedAt": "2026-09-10T18:54:42.506Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 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 use @owlmeans/entrypoint — immutable typed protocols, adapter references, legacy entrypoint declarations, guards/gates/schemas, address accessors, and the transport seam. Auto-invoked when importing from this package or defining a service entrypoint declaration.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,16 +8,22 @@ user-invocable: false
 # @owlmeans/entrypoint
 
 **Layer:** Core
-**Install:** `"@owlmeans/entrypoint": "^0.1.18-rc.11"` in `dependencies`
+**Install:** `"@owlmeans/entrypoint": "^0.1.18-rc.12"` 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.
+An entrypoint is an **addressable unit**. New code declares an immutable typed `protocol` once in a
+shared package, then binds that declaration on the client or server. The older mutable
+`entrypoint(...)` + `elevate(...)` form remains supported while applications migrate.
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
+| `protocol(route, contract, opts?)` / `openProtocol(route, opts?)` | Declare an immutable shared protocol |
+| `contract(...)` / `contract.request(...)` | Declare the request sections and response together |
+| `schema<T>(value)` / `typed<T>()` | Carry runtime validation plus type inference, or type information only |
+| `protocols(tree)` | Flatten a named protocol tree for a layer binding |
+| `entrypointRef<Request, Response>(alias)` | Typed adapter reference for dynamic registries |
+| `decorateEntrypoint(protocol, opts)` | Return an immutable protocol with added access/options |
 | `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(...)` |
@@ -34,6 +40,43 @@ elevates on either side.
 | `EntrypointTransport` | `{ protocol, handle }` — a carrier bound to a route protocol |
 | `transportAlias(protocol?)` | The service alias a transport registers under (`transport:<protocol>`) |
 
+## Typed protocol form
+
+Application contracts export protocol objects, not alias strings or already context-bound
+entrypoints. A protocol owns the route, request/response contract, guards, gate and sticky flag; it
+is frozen and never mutated by either runtime.
+
+```typescript
+import { contract, openProtocol, protocol, protocols, schema, typed } from '@owlmeans/entrypoint'
+import { frontend, route, RouteMethod } from '@owlmeans/route'
+
+const ItemParamsSchema = schema<{ id: string }>({
+  type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false,
+})
+
+const apiBase = protocol(route('api:item', '/items'), contract())
+export const item = {
+  base: apiBase,
+  get: protocol(
+    route('api:item:get', '/:id', { parent: apiBase, method: RouteMethod.GET }),
+    contract.request({ params: ItemParamsSchema }, typed<Item>()),
+  ),
+}
+export const web = {
+  items: openProtocol(route('web:items', '/items', frontend())),
+}
+export const itemEntrypoints = protocols(item)
+```
+
+`contract()` means no payload and an `undefined` reply. With one source it declares only the
+response; with two it declares body then response. Use `contract.request` when params, query,
+headers or several request sections participate. `schema<T>` is the preferred source when runtime
+validation exists; `typed<T>()` is only the compile-time half.
+
+`context.entrypoint(protocolOrRef)` infers the exact registered `call`/`invoke`/`url` signature.
+Use the protocol object inside an application. Use `entrypointRef` only in an adapter package that
+must address a dynamically registered surface without importing its declaration tree.
+
 `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:
 
@@ -144,9 +187,10 @@ context.registerService(transport)
 as a broker job. Nothing at the call site changes — which is the point of putting the protocol on
 the route rather than at the call.
 
-## Usage
+## Legacy declaration form
 
-Define entrypoints in a shared `common` package, then `elevate()` them with handlers in server/web packages:
+Existing applications may define entrypoints in a shared `common` package, then `elevate()` them
+with handlers in server/web packages. Do not introduce this form into a protocol-based surface.
 
 ```typescript
 import { entrypoint, guard, gate, filter, body } from '@owlmeans/entrypoint'

package/build/index.d.ts

@@ -3,4 +3,6 @@ export * from './entrypoint.js';
 export * from './filter.js';
 export * from './helper.js';
 export * from './consts.js';
+export * from './protocol.js';
+export * from './materialize.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA"}

package/build/index.js

@@ -2,4 +2,6 @@ export * from './entrypoint.js';
 export * from './filter.js';
 export * from './helper.js';
 export * from './consts.js';
+export * from './protocol.js';
+export * from './materialize.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA"}

package/build/materialize.d.ts

@@ -0,0 +1,12 @@
+import type { CommonEntrypoint } from './types.js';
+import type { EntrypointProtocolDeclaration } from './protocol.js';
+/** A context-bound entrypoint made from an immutable protocol declaration. */
+export type MaterializedEntrypoint<Protocol extends EntrypointProtocolDeclaration> = CommonEntrypoint & {
+    readonly protocol: Protocol;
+};
+/**
+ * Make a local, mutable registration from a shared declaration.  The protocol is never mutated;
+ * guards, route resolution and handlers belong exclusively to this materialized entrypoint.
+ */
+export declare const materializeEntrypoint: <Protocol extends EntrypointProtocolDeclaration>(protocol: Protocol) => MaterializedEntrypoint<Protocol>;
+//# sourceMappingURL=materialize.d.ts.map

package/build/materialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.d.ts","sourceRoot":"","sources":["../src/materialize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAmC,MAAM,YAAY,CAAA;AACnF,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAA;AAElE,8EAA8E;AAC9E,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,6BAA6B,IAAI,gBAAgB,GAAG;IACtG,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAC5B,CAAA;AAgCD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ,SAAS,6BAA6B,YACxE,QAAQ,KACjB,sBAAsB,CAAC,QAAQ,CAGjC,CAAA"}

package/build/materialize.js

@@ -0,0 +1,34 @@
+import { entrypoint } from './entrypoint.js';
+const filterOf = (protocol) => {
+    const request = protocol.contract?.requestSchemas;
+    const response = protocol.contract?.responseSchemas;
+    if (request == null && response == null)
+        return undefined;
+    return {
+        body: request?.body == null ? undefined : structuredClone(request.body),
+        params: request?.params == null ? undefined : structuredClone(request.params),
+        query: request?.query == null ? undefined : structuredClone(request.query),
+        headers: request?.headers == null ? undefined : structuredClone(request.headers),
+        response: response?.byStatus == null
+            ? response?.default == null ? undefined : structuredClone(response.default)
+            : {
+                ...(response.default == null ? {} : { default: structuredClone(response.default) }),
+                ...Object.fromEntries(Object.entries(response.byStatus).map(([status, schema]) => [
+                    status, structuredClone(schema),
+                ])),
+            },
+    };
+};
+const optionsOf = (protocol) => ({
+    sticky: protocol.sticky,
+    guards: [...protocol.guards],
+    gate: protocol.gate?.alias,
+    gateParams: protocol.gate == null ? undefined : [...protocol.gate.params],
+    filter: filterOf(protocol),
+});
+/**
+ * Make a local, mutable registration from a shared declaration.  The protocol is never mutated;
+ * guards, route resolution and handlers belong exclusively to this materialized entrypoint.
+ */
+export const materializeEntrypoint = (protocol) => Object.assign(entrypoint(protocol.route, optionsOf(protocol)), { protocol });
+//# sourceMappingURL=materialize.js.map

package/build/materialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize.js","sourceRoot":"","sources":["../src/materialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAS5C,MAAM,QAAQ,GAAG,CAAC,QAAuC,EAAsB,EAAE;IAC/E,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjD,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAEnD,IAAI,OAAO,IAAI,IAAI,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,SAAS,CAAA;IAEzD,OAAO;QACL,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC;QACvE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC;QAC7E,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC;QAC1E,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC;QAChF,QAAQ,EAAE,QAAQ,EAAE,QAAQ,IAAI,IAAI;YAClC,CAAC,CAAC,QAAQ,EAAE,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC;YAC3E,CAAC,CAAC;gBACA,GAAG,CAAC,QAAQ,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACnF,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC;oBAChF,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC;iBAChC,CAAC,CAAC;aACN;KACF,CAAA;AACH,CAAC,CAAA;AAED,MAAM,SAAS,GAAG,CAAC,QAAuC,EAA2B,EAAE,CAAC,CAAC;IACvF,MAAM,EAAE,QAAQ,CAAC,MAAM;IACvB,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;IAC5B,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAK;IAC1B,UAAU,EAAE,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;IACzE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC;CAC3B,CAAC,CAAA;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,QAAkB,EACgB,EAAE,CAAC,MAAM,CAAC,MAAM,CAClD,UAAU,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,EAC/C,EAAE,QAAQ,EAAE,CACb,CAAA"}

package/build/protocol.d.ts

@@ -0,0 +1,209 @@
+import type { Auth } from '@owlmeans/auth';
+import type { BasicEntrypoint, EntrypointReference } from '@owlmeans/context';
+import type { JSONSchemaType, AnySchemaObject } from 'ajv';
+import type { RouteModel } from '@owlmeans/route';
+import type { EntrypointOutcome } from './consts.js';
+import type { ResolvedEntity } from './types.js';
+/** A deliberately broad value used only by declarations without an I/O contract. */
+export type OpenValue = object | string | number | boolean | bigint | null | undefined;
+/** The request accepted by a declaration that intentionally supplies no contract. */
+export interface OpenRequest {
+    body?: object;
+    params?: object;
+    query?: object;
+    headers?: object;
+}
+/** The four independent request sections an entrypoint may declare. */
+export interface RequestShape {
+    body?: OpenValue;
+    params?: object;
+    query?: object;
+    headers?: object;
+}
+/** Addressing and transport controls are never part of an entrypoint's payload contract. */
+export interface CallOptions {
+    auth?: Auth;
+    host?: string;
+    base?: string | boolean;
+    unsecure?: boolean;
+    timeout?: number;
+    signal?: AbortSignal;
+}
+interface TypeToken {
+    readonly kind: 'entrypoint-type';
+    readonly schema?: AnySchemaObject;
+}
+/** A type-only contract source, optionally paired with an AJV schema. */
+export type Typed<T> = TypeToken & {
+    readonly value?: T;
+};
+declare const entrypointSchemaType: unique symbol;
+/**
+ * A JSON schema carrying the model type it validates.  Use `schema<Model>(...)` once beside the
+ * model; every protocol that consumes it then infers the model without another generic.
+ */
+export type EntrypointSchema<T> = JSONSchemaType<T> & {
+    readonly [entrypointSchemaType]: T;
+};
+export declare const schema: <T>(value: JSONSchemaType<T>) => EntrypointSchema<T>;
+/** A schema or an explicit type-only source for one request/response value. */
+export type ShapeSource<T> = EntrypointSchema<T> | JSONSchemaType<T> | Typed<T>;
+type AnyShapeSource = AnySchemaObject | TypeToken;
+/**
+ * Supplies type information where a response has no runtime schema, or attaches a type to an
+ * otherwise untyped schema literal at the declaration boundary.
+ */
+export declare function typed<T>(): Typed<T>;
+export declare function typed<T>(schema: JSONSchemaType<T>): Typed<T>;
+export interface RequestSources {
+    body?: AnyShapeSource;
+    params?: AnyShapeSource;
+    query?: AnyShapeSource;
+    headers?: AnyShapeSource;
+}
+export interface RuntimeRequestSchemas {
+    body?: AnySchemaObject;
+    params?: AnySchemaObject;
+    query?: AnySchemaObject;
+    headers?: AnySchemaObject;
+}
+export interface RuntimeResponseSchemas {
+    default?: AnySchemaObject;
+    byStatus?: Readonly<Record<number, AnySchemaObject>>;
+}
+/** The runtime schemas and compile-time request/response pair attached to one protocol. */
+export interface EntrypointContract<Request extends RequestShape, Response> {
+    readonly kind: 'entrypoint-contract';
+    readonly requestSchemas: RuntimeRequestSchemas;
+    readonly responseSchemas?: RuntimeResponseSchemas;
+    readonly requestType?: Request;
+    readonly responseType?: Response;
+}
+/** Runtime fields common to every protocol, regardless of its compile-time request/reply pair. */
+export interface EntrypointProtocolDeclaration {
+    readonly kind: 'entrypoint-protocol';
+    readonly alias: string;
+    readonly route: RouteModel;
+    readonly contract?: Pick<EntrypointContract<RequestShape, OpenValue>, 'kind' | 'requestSchemas' | 'responseSchemas'>;
+    readonly sticky: boolean;
+    readonly guards: readonly string[];
+    readonly gate?: {
+        readonly alias: string;
+        readonly params: readonly string[];
+    };
+}
+type SourceValue<Source> = Source extends Typed<infer Value> ? Value : Source extends EntrypointSchema<infer Value> ? Value : Source extends JSONSchemaType<infer Value> ? Value extends OpenValue ? Value : OpenValue : OpenValue;
+type RequestFromSources<Sources extends RequestSources> = (Sources extends {
+    body: infer Source;
+} ? {
+    body: SourceValue<Source>;
+} : {}) & (Sources extends {
+    params: infer Source;
+} ? {
+    params: SourceValue<Source>;
+} : {}) & (Sources extends {
+    query: infer Source;
+} ? {
+    query: SourceValue<Source>;
+} : {}) & (Sources extends {
+    headers: infer Source;
+} ? {
+    headers: SourceValue<Source>;
+} : {});
+/**
+ * Declare an exact request and response.  The primary overload means a body request; use
+ * `contract.request` for independently-shaped request sections.
+ */
+export declare function contract(): EntrypointContract<{}, undefined>;
+export declare function contract<Response>(response: ShapeSource<Response>): EntrypointContract<{}, Response>;
+export declare function contract<Body extends OpenValue, Response>(body: ShapeSource<Body>, response: ShapeSource<Response>): EntrypointContract<{
+    body: Body;
+}, Response>;
+export declare namespace contract {
+    function request<Sources extends RequestSources, Response>(request: Sources, response: ShapeSource<Response>): EntrypointContract<RequestFromSources<Sources>, Response>;
+}
+export interface EntrypointOptions {
+    sticky?: boolean;
+    guards?: string | readonly string[];
+    gate?: {
+        alias: string;
+        params?: string | readonly string[];
+    };
+}
+export interface EntrypointResult<Response> {
+    value: Response;
+    outcome: EntrypointOutcome;
+}
+export type CallArguments<Request extends RequestShape> = {} extends Request ? [request?: Request & CallOptions] : [request: Request & CallOptions];
+type UrlRequest<Request extends RequestShape> = (Request extends {
+    params: infer Params;
+} ? {
+    params: Params;
+} : Request extends {
+    params?: infer Params;
+} ? {
+    params?: Params;
+} : {}) & (Request extends {
+    query: infer Query;
+} ? {
+    query: Query;
+} : Request extends {
+    query?: infer Query;
+} ? {
+    query?: Query;
+} : {});
+export type UrlArguments<Request extends RequestShape> = {} extends UrlRequest<Request> ? [request?: UrlRequest<Request> & CallOptions] : [request: UrlRequest<Request> & CallOptions];
+export interface EntrypointRequestMeta {
+    alias: string;
+    auth?: Auth;
+    entity?: ResolvedEntity;
+    path: string;
+    canceled?: boolean;
+    cancel?: () => void;
+}
+export type HandlerRequest<Request extends RequestShape> = Request & EntrypointRequestMeta;
+/** The context-bound counterpart of an immutable protocol declaration. */
+export interface RegisteredEntrypoint<Request extends RequestShape, Response> extends BasicEntrypoint {
+    readonly protocol: EntrypointProtocol<Request, Response>;
+    call: (...args: CallArguments<Request>) => Promise<Response>;
+    invoke: (...args: CallArguments<Request>) => Promise<EntrypointResult<Response>>;
+    url: (...args: UrlArguments<Request>) => Promise<string>;
+    validate: (...args: CallArguments<Request>) => Promise<boolean>;
+}
+/**
+ * An immutable shared declaration.  Its inherited reference type is what gives a context lookup
+ * the exact registered entrypoint type without a consumer-supplied generic.
+ */
+export interface EntrypointProtocol<Request extends RequestShape = RequestShape, Response = OpenValue> extends EntrypointProtocolDeclaration, EntrypointReference<RegisteredEntrypoint<Request, Response>> {
+    readonly contract?: EntrypointContract<Request, Response>;
+}
+export type RequestOf<Protocol extends EntrypointProtocolDeclaration> = Protocol extends EntrypointProtocol<infer Request, infer _Response> ? Request : OpenRequest;
+export type ResponseOf<Protocol extends EntrypointProtocolDeclaration> = Protocol extends EntrypointProtocol<infer _Request, infer Response> ? Response : OpenValue;
+export type BodyOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends {
+    body: infer Body;
+} ? Body : OpenValue;
+export type ParamsOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends {
+    params: infer Params;
+} ? Params : object;
+export type QueryOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends {
+    query: infer Query;
+} ? Query : object;
+export type HeadersOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends {
+    headers: infer Headers;
+} ? Headers : object;
+export type CallRequestOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> & CallOptions;
+/** Create the immutable protocol form while legacy contextual entrypoints are migrated. */
+export declare const protocol: <Request extends RequestShape, Response>(route: RouteModel, entrypointContract: EntrypointContract<Request, Response>, options?: EntrypointOptions) => EntrypointProtocol<Request, Response>;
+export declare const openProtocol: (route: RouteModel, options?: EntrypointOptions) => EntrypointProtocol<OpenRequest, OpenValue>;
+export declare const entrypointRef: <Request extends RequestShape = OpenRequest, Response = OpenValue>(alias: string) => EntrypointReference<RegisteredEntrypoint<Request, Response>>;
+export declare const aliasOf: (reference: EntrypointReference | string) => string;
+export declare const isEntrypointProtocol: (value: object) => value is EntrypointProtocolDeclaration;
+export interface EntrypointTree {
+    readonly [key: string]: EntrypointProtocolDeclaration | EntrypointTree;
+}
+/** Flatten an exported protocol tree for a layer-specific materializer. */
+export declare const protocols: (tree: EntrypointTree) => EntrypointProtocolDeclaration[];
+/** Clone an immutable protocol while preserving its request/response pair. */
+export declare const decorateEntrypoint: <Protocol extends EntrypointProtocolDeclaration>(protocol: Protocol, options: EntrypointOptions) => Protocol;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/build/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/build/protocol.js

@@ -0,0 +1,96 @@
+export const schema = (value) => value;
+export function typed(schema) {
+    return schema == null
+        ? { kind: 'entrypoint-type' }
+        : { kind: 'entrypoint-type', schema };
+}
+const schemaOf = (source) => {
+    if (source == null)
+        return undefined;
+    const schema = 'kind' in source && source.kind === 'entrypoint-type'
+        ? source.schema
+        : source;
+    return schema == null ? undefined : structuredClone(schema);
+};
+const responseSchemasOf = (source) => {
+    const schema = schemaOf(source);
+    return schema == null ? undefined : { default: schema };
+};
+export function contract(first, second) {
+    const body = second == null ? undefined : first;
+    const response = second ?? first;
+    return {
+        kind: 'entrypoint-contract',
+        requestSchemas: { body: schemaOf(body) },
+        responseSchemas: responseSchemasOf(response),
+    };
+}
+(function (contract) {
+    function request(request, response) {
+        return {
+            kind: 'entrypoint-contract',
+            requestSchemas: {
+                body: schemaOf(request.body),
+                params: schemaOf(request.params),
+                query: schemaOf(request.query),
+                headers: schemaOf(request.headers),
+            },
+            responseSchemas: responseSchemasOf(response),
+        };
+    }
+    contract.request = request;
+})(contract || (contract = {}));
+const guardsOf = (guards) => guards == null
+    ? []
+    : typeof guards === 'string' ? [guards] : [...guards];
+const gateOf = (gate) => gate == null
+    ? undefined
+    : {
+        alias: gate.alias,
+        params: gate.params == null ? [] : typeof gate.params === 'string' ? [gate.params] : [...gate.params],
+    };
+/** Create the immutable protocol form while legacy contextual entrypoints are migrated. */
+export const protocol = (route, entrypointContract, options) => Object.freeze({
+    kind: 'entrypoint-protocol',
+    alias: route.route.alias,
+    route: Object.freeze({ route: Object.freeze({ ...route.route }) }),
+    contract: entrypointContract,
+    sticky: options?.sticky ?? false,
+    guards: Object.freeze(guardsOf(options?.guards)),
+    gate: gateOf(options?.gate),
+});
+export const openProtocol = (route, options) => Object.freeze({
+    kind: 'entrypoint-protocol',
+    alias: route.route.alias,
+    route: Object.freeze({ route: Object.freeze({ ...route.route }) }),
+    sticky: options?.sticky ?? false,
+    guards: Object.freeze(guardsOf(options?.guards)),
+    gate: gateOf(options?.gate),
+});
+export const entrypointRef = (alias) => ({ alias });
+export const aliasOf = (reference) => typeof reference === 'string' ? reference : reference.alias;
+export const isEntrypointProtocol = (value) => 'kind' in value && value.kind === 'entrypoint-protocol';
+/** Flatten an exported protocol tree for a layer-specific materializer. */
+export const protocols = (tree) => {
+    const result = [];
+    const visit = (node) => {
+        Object.values(node).forEach((entry) => {
+            if (isEntrypointProtocol(entry)) {
+                result.push(entry);
+            }
+            else {
+                visit(entry);
+            }
+        });
+    };
+    visit(tree);
+    return result;
+};
+/** Clone an immutable protocol while preserving its request/response pair. */
+export const decorateEntrypoint = (protocol, options) => Object.freeze({
+    ...protocol,
+    sticky: options.sticky ?? protocol.sticky,
+    guards: options.guards == null ? protocol.guards : guardsOf(options.guards),
+    gate: options.gate == null ? protocol.gate : gateOf(options.gate),
+});
+//# sourceMappingURL=protocol.js.map

package/build/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/entrypoint",
-  "version": "0.1.18-rc.11",
+  "version": "0.1.18-rc.12",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -28,9 +28,9 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.9",
-    "@owlmeans/context": "^0.1.18-rc.8",
-    "@owlmeans/route": "^0.1.18-rc.9",
+    "@owlmeans/auth": "^0.1.18-rc.10",
+    "@owlmeans/context": "^0.1.18-rc.9",
+    "@owlmeans/route": "^0.1.18-rc.10",
     "ajv": "^8.17.1"
   },
   "devDependencies": {

package/src/index.ts

@@ -4,3 +4,5 @@ export * from './entrypoint.js'
 export * from './filter.js'
 export * from './helper.js'
 export * from './consts.js'
+export * from './protocol.js'
+export * from './materialize.js'

package/src/materialize.ts

@@ -0,0 +1,49 @@
+import { entrypoint } from './entrypoint.js'
+import type { CommonEntrypoint, CommonEntrypointOptions, Filter } from './types.js'
+import type { EntrypointProtocolDeclaration } from './protocol.js'
+
+/** A context-bound entrypoint made from an immutable protocol declaration. */
+export type MaterializedEntrypoint<Protocol extends EntrypointProtocolDeclaration> = CommonEntrypoint & {
+  readonly protocol: Protocol
+}
+
+const filterOf = (protocol: EntrypointProtocolDeclaration): Filter | undefined => {
+  const request = protocol.contract?.requestSchemas
+  const response = protocol.contract?.responseSchemas
+
+  if (request == null && response == null) return undefined
+
+  return {
+    body: request?.body == null ? undefined : structuredClone(request.body),
+    params: request?.params == null ? undefined : structuredClone(request.params),
+    query: request?.query == null ? undefined : structuredClone(request.query),
+    headers: request?.headers == null ? undefined : structuredClone(request.headers),
+    response: response?.byStatus == null
+      ? response?.default == null ? undefined : structuredClone(response.default)
+      : {
+        ...(response.default == null ? {} : { default: structuredClone(response.default) }),
+        ...Object.fromEntries(Object.entries(response.byStatus).map(([status, schema]) => [
+          status, structuredClone(schema),
+        ])),
+    },
+  }
+}
+
+const optionsOf = (protocol: EntrypointProtocolDeclaration): CommonEntrypointOptions => ({
+  sticky: protocol.sticky,
+  guards: [...protocol.guards],
+  gate: protocol.gate?.alias,
+  gateParams: protocol.gate == null ? undefined : [...protocol.gate.params],
+  filter: filterOf(protocol),
+})
+
+/**
+ * Make a local, mutable registration from a shared declaration.  The protocol is never mutated;
+ * guards, route resolution and handlers belong exclusively to this materialized entrypoint.
+ */
+export const materializeEntrypoint = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol,
+): MaterializedEntrypoint<Protocol> => Object.assign(
+  entrypoint(protocol.route, optionsOf(protocol)),
+  { protocol },
+)

package/src/protocol.ts

@@ -0,0 +1,349 @@
+import type { Auth } from '@owlmeans/auth'
+import type { BasicEntrypoint, EntrypointReference } from '@owlmeans/context'
+import type { JSONSchemaType, AnySchemaObject } from 'ajv'
+import type { RouteModel } from '@owlmeans/route'
+import type { EntrypointOutcome } from './consts.js'
+import type { ResolvedEntity } from './types.js'
+
+/** A deliberately broad value used only by declarations without an I/O contract. */
+export type OpenValue = object | string | number | boolean | bigint | null | undefined
+
+/** The request accepted by a declaration that intentionally supplies no contract. */
+export interface OpenRequest {
+  body?: object
+  params?: object
+  query?: object
+  headers?: object
+}
+
+/** The four independent request sections an entrypoint may declare. */
+export interface RequestShape {
+  body?: OpenValue
+  params?: object
+  query?: object
+  headers?: object
+}
+
+/** Addressing and transport controls are never part of an entrypoint's payload contract. */
+export interface CallOptions {
+  auth?: Auth
+  host?: string
+  base?: string | boolean
+  unsecure?: boolean
+  timeout?: number
+  signal?: AbortSignal
+}
+
+interface TypeToken {
+  readonly kind: 'entrypoint-type'
+  readonly schema?: AnySchemaObject
+}
+
+/** A type-only contract source, optionally paired with an AJV schema. */
+export type Typed<T> = TypeToken & { readonly value?: T }
+
+declare const entrypointSchemaType: unique symbol
+
+/**
+ * A JSON schema carrying the model type it validates.  Use `schema<Model>(...)` once beside the
+ * model; every protocol that consumes it then infers the model without another generic.
+ */
+export type EntrypointSchema<T> = JSONSchemaType<T> & {
+  readonly [entrypointSchemaType]: T
+}
+
+export const schema = <T>(value: JSONSchemaType<T>): EntrypointSchema<T> =>
+  value as EntrypointSchema<T>
+
+/** A schema or an explicit type-only source for one request/response value. */
+export type ShapeSource<T> = EntrypointSchema<T> | JSONSchemaType<T> | Typed<T>
+
+type AnyShapeSource = AnySchemaObject | TypeToken
+
+/**
+ * Supplies type information where a response has no runtime schema, or attaches a type to an
+ * otherwise untyped schema literal at the declaration boundary.
+ */
+export function typed<T>(): Typed<T>
+export function typed<T>(schema: JSONSchemaType<T>): Typed<T>
+export function typed<T>(schema?: JSONSchemaType<T>): Typed<T> {
+  return schema == null
+    ? { kind: 'entrypoint-type' }
+    : { kind: 'entrypoint-type', schema }
+}
+
+export interface RequestSources {
+  body?: AnyShapeSource
+  params?: AnyShapeSource
+  query?: AnyShapeSource
+  headers?: AnyShapeSource
+}
+
+export interface RuntimeRequestSchemas {
+  body?: AnySchemaObject
+  params?: AnySchemaObject
+  query?: AnySchemaObject
+  headers?: AnySchemaObject
+}
+
+export interface RuntimeResponseSchemas {
+  default?: AnySchemaObject
+  byStatus?: Readonly<Record<number, AnySchemaObject>>
+}
+
+/** The runtime schemas and compile-time request/response pair attached to one protocol. */
+export interface EntrypointContract<Request extends RequestShape, Response> {
+  readonly kind: 'entrypoint-contract'
+  readonly requestSchemas: RuntimeRequestSchemas
+  readonly responseSchemas?: RuntimeResponseSchemas
+  readonly requestType?: Request
+  readonly responseType?: Response
+}
+
+/** Runtime fields common to every protocol, regardless of its compile-time request/reply pair. */
+export interface EntrypointProtocolDeclaration {
+  readonly kind: 'entrypoint-protocol'
+  readonly alias: string
+  readonly route: RouteModel
+  readonly contract?: Pick<EntrypointContract<RequestShape, OpenValue>,
+    'kind' | 'requestSchemas' | 'responseSchemas'>
+  readonly sticky: boolean
+  readonly guards: readonly string[]
+  readonly gate?: {
+    readonly alias: string
+    readonly params: readonly string[]
+  }
+}
+
+type SourceValue<Source> =
+  Source extends Typed<infer Value> ? Value
+    : Source extends EntrypointSchema<infer Value> ? Value
+      : Source extends JSONSchemaType<infer Value>
+        ? Value extends OpenValue ? Value : OpenValue
+        : OpenValue
+
+type RequestFromSources<Sources extends RequestSources> =
+  (Sources extends { body: infer Source } ? { body: SourceValue<Source> } : {})
+  & (Sources extends { params: infer Source } ? { params: SourceValue<Source> } : {})
+  & (Sources extends { query: infer Source } ? { query: SourceValue<Source> } : {})
+  & (Sources extends { headers: infer Source } ? { headers: SourceValue<Source> } : {})
+
+const schemaOf = (source: AnyShapeSource | undefined): AnySchemaObject | undefined => {
+  if (source == null) return undefined
+  const schema = 'kind' in source && source.kind === 'entrypoint-type'
+    ? source.schema
+    : source
+
+  return schema == null ? undefined : structuredClone(schema)
+}
+
+const responseSchemasOf = (source: AnyShapeSource | undefined): RuntimeResponseSchemas | undefined => {
+  const schema = schemaOf(source)
+  return schema == null ? undefined : { default: schema }
+}
+
+/**
+ * Declare an exact request and response.  The primary overload means a body request; use
+ * `contract.request` for independently-shaped request sections.
+ */
+export function contract(): EntrypointContract<{}, undefined>
+export function contract<Response>(response: ShapeSource<Response>): EntrypointContract<{}, Response>
+export function contract<Body extends OpenValue, Response>(
+  body: ShapeSource<Body>, response: ShapeSource<Response>
+): EntrypointContract<{ body: Body }, Response>
+export function contract(
+  first?: AnyShapeSource, second?: AnyShapeSource
+): EntrypointContract<RequestShape, OpenValue> {
+  const body = second == null ? undefined : first
+  const response = second ?? first
+
+  return {
+    kind: 'entrypoint-contract',
+    requestSchemas: { body: schemaOf(body) },
+    responseSchemas: responseSchemasOf(response),
+  }
+}
+
+export namespace contract {
+  export function request<Sources extends RequestSources, Response>(
+    request: Sources,
+    response: ShapeSource<Response>
+  ): EntrypointContract<RequestFromSources<Sources>, Response> {
+    return {
+      kind: 'entrypoint-contract',
+      requestSchemas: {
+        body: schemaOf(request.body),
+        params: schemaOf(request.params),
+        query: schemaOf(request.query),
+        headers: schemaOf(request.headers),
+      },
+      responseSchemas: responseSchemasOf(response),
+    }
+  }
+}
+
+export interface EntrypointOptions {
+  sticky?: boolean
+  guards?: string | readonly string[]
+  gate?: {
+    alias: string
+    params?: string | readonly string[]
+  }
+}
+
+export interface EntrypointResult<Response> {
+  value: Response
+  outcome: EntrypointOutcome
+}
+
+export type CallArguments<Request extends RequestShape> = {} extends Request
+  ? [request?: Request & CallOptions]
+  : [request: Request & CallOptions]
+
+type UrlRequest<Request extends RequestShape> =
+  (Request extends { params: infer Params } ? { params: Params }
+    : Request extends { params?: infer Params } ? { params?: Params } : {})
+  & (Request extends { query: infer Query } ? { query: Query }
+    : Request extends { query?: infer Query } ? { query?: Query } : {})
+
+export type UrlArguments<Request extends RequestShape> = {} extends UrlRequest<Request>
+  ? [request?: UrlRequest<Request> & CallOptions]
+  : [request: UrlRequest<Request> & CallOptions]
+
+export interface EntrypointRequestMeta {
+  alias: string
+  auth?: Auth
+  entity?: ResolvedEntity
+  path: string
+  canceled?: boolean
+  cancel?: () => void
+}
+
+export type HandlerRequest<Request extends RequestShape> = Request & EntrypointRequestMeta
+
+/** The context-bound counterpart of an immutable protocol declaration. */
+export interface RegisteredEntrypoint<Request extends RequestShape, Response> extends BasicEntrypoint {
+  readonly protocol: EntrypointProtocol<Request, Response>
+  call: (...args: CallArguments<Request>) => Promise<Response>
+  invoke: (...args: CallArguments<Request>) => Promise<EntrypointResult<Response>>
+  url: (...args: UrlArguments<Request>) => Promise<string>
+  validate: (...args: CallArguments<Request>) => Promise<boolean>
+}
+
+/**
+ * An immutable shared declaration.  Its inherited reference type is what gives a context lookup
+ * the exact registered entrypoint type without a consumer-supplied generic.
+ */
+export interface EntrypointProtocol<
+  Request extends RequestShape = RequestShape,
+  Response = OpenValue,
+> extends EntrypointProtocolDeclaration, EntrypointReference<RegisteredEntrypoint<Request, Response>> {
+  readonly contract?: EntrypointContract<Request, Response>
+}
+
+export type RequestOf<Protocol extends EntrypointProtocolDeclaration> = Protocol extends EntrypointProtocol<infer Request, infer _Response>
+  ? Request
+  : OpenRequest
+
+export type ResponseOf<Protocol extends EntrypointProtocolDeclaration> = Protocol extends EntrypointProtocol<infer _Request, infer Response>
+  ? Response
+  : OpenValue
+
+export type BodyOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { body: infer Body }
+  ? Body
+  : OpenValue
+
+export type ParamsOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { params: infer Params }
+  ? Params
+  : object
+
+export type QueryOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { query: infer Query }
+  ? Query
+  : object
+
+export type HeadersOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { headers: infer Headers }
+  ? Headers
+  : object
+
+export type CallRequestOf<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> & CallOptions
+
+const guardsOf = (guards: EntrypointOptions['guards']): readonly string[] => guards == null
+  ? []
+  : typeof guards === 'string' ? [guards] : [...guards]
+
+const gateOf = (gate: EntrypointOptions['gate']): EntrypointProtocol['gate'] => gate == null
+  ? undefined
+  : {
+      alias: gate.alias,
+      params: gate.params == null ? [] : typeof gate.params === 'string' ? [gate.params] : [...gate.params],
+    }
+
+/** Create the immutable protocol form while legacy contextual entrypoints are migrated. */
+export const protocol = <Request extends RequestShape, Response>(
+  route: RouteModel,
+  entrypointContract: EntrypointContract<Request, Response>,
+  options?: EntrypointOptions
+): EntrypointProtocol<Request, Response> => Object.freeze({
+  kind: 'entrypoint-protocol' as const,
+  alias: route.route.alias,
+  route: Object.freeze({ route: Object.freeze({ ...route.route }) }),
+  contract: entrypointContract,
+  sticky: options?.sticky ?? false,
+  guards: Object.freeze(guardsOf(options?.guards)),
+  gate: gateOf(options?.gate),
+})
+
+export const openProtocol = (
+  route: RouteModel,
+  options?: EntrypointOptions
+): EntrypointProtocol<OpenRequest, OpenValue> => Object.freeze({
+  kind: 'entrypoint-protocol' as const,
+  alias: route.route.alias,
+  route: Object.freeze({ route: Object.freeze({ ...route.route }) }),
+  sticky: options?.sticky ?? false,
+  guards: Object.freeze(guardsOf(options?.guards)),
+  gate: gateOf(options?.gate),
+})
+
+export const entrypointRef = <Request extends RequestShape = OpenRequest, Response = OpenValue>(
+  alias: string
+): EntrypointReference<RegisteredEntrypoint<Request, Response>> => ({ alias })
+
+export const aliasOf = (reference: EntrypointReference | string): string =>
+  typeof reference === 'string' ? reference : reference.alias
+
+export const isEntrypointProtocol = (value: object): value is EntrypointProtocolDeclaration =>
+  'kind' in value && value.kind === 'entrypoint-protocol'
+
+export interface EntrypointTree {
+  readonly [key: string]: EntrypointProtocolDeclaration | EntrypointTree
+}
+
+/** Flatten an exported protocol tree for a layer-specific materializer. */
+export const protocols = (tree: EntrypointTree): EntrypointProtocolDeclaration[] => {
+  const result: EntrypointProtocolDeclaration[] = []
+
+  const visit = (node: EntrypointTree): void => {
+    Object.values(node).forEach((entry) => {
+      if (isEntrypointProtocol(entry)) {
+        result.push(entry)
+      } else {
+        visit(entry)
+      }
+    })
+  }
+
+  visit(tree)
+  return result
+}
+
+/** Clone an immutable protocol while preserving its request/response pair. */
+export const decorateEntrypoint = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol,
+  options: EntrypointOptions
+): Protocol => Object.freeze({
+  ...protocol,
+  sticky: options.sticky ?? protocol.sticky,
+  guards: options.guards == null ? protocol.guards : guardsOf(options.guards),
+  gate: options.gate == null ? protocol.gate : gateOf(options.gate),
+})