@toa.io/extensions.exposition 1.0.0-alpha.34 → 1.0.0-alpha.340

package/transpiled/MCP/schema.js

@@ -0,0 +1,88 @@
+/**
+ * What a tool takes, which is what the procedure takes: a route variable by the name the
+ * template gives it, the querystring under a name of its own, and what is left is the body.
+ *
+ * A `map:headers` property is not here: a call carries no headers of its own, so there is
+ * nowhere for a model to put one.
+ */
+// eslint-disable-next-line max-params
+export function input(introspection, variables, selection) {
+    const properties = {};
+    const required = [];
+    /*
+     * By the name the template gives it, which is what the tool's own name states and what
+     * resolving it consumes. A `map:segments` renaming is the gateway's, as invisible here as
+     * it is to whoever writes the path; and a variable the operation does not declare has no
+     * schema of its own, being a segment.
+     */
+    for (const variable of variables) {
+        properties[variable] = introspection.route?.[variable] ?? { type: 'string' };
+        required.push(variable);
+    }
+    /*
+     * It is a querystring on the wire, which is nothing a model knows or needs to; what it is
+     * to a caller is the part of a call that picks what the call is about. What selects
+     * records is `selection` on the method, and is merged here because here it is something
+     * the caller sends.
+     */
+    const query = { ...introspection.query, ...selection };
+    if (Object.keys(query).length > 0)
+        properties.query = {
+            type: 'object',
+            description: 'Which records the call works on: what to match, in what order, ' +
+                'and how many at once.',
+            properties: query
+        };
+    const body = introspection.input;
+    if (body?.properties !== undefined) {
+        Object.assign(properties, body.properties);
+        required.push(...(body.required ?? []));
+    }
+    const schema = { type: 'object', properties };
+    if (required.length > 0)
+        schema.required = required;
+    // what a name does not state is not a parameter, and a model should not invent one
+    schema.additionalProperties = false;
+    return schema;
+}
+/**
+ * What a tool answers with, where that is worth stating. An operation's `output` is optional
+ * and normalizes to `{}`, which describes nothing — and a schema the revision would have the
+ * reply validated against is worse said emptily than left unsaid.
+ *
+ * The revision has it describe an object, which is all structured content may be: a reply of
+ * another type is the `result` of one, as `structured` answers it.
+ */
+export function output(introspection) {
+    const schema = introspection.output;
+    if (schema === undefined || schema === null)
+        return undefined;
+    if (Object.keys(schema).length === 0)
+        return undefined;
+    if (schema.type === 'object')
+        return schema;
+    return { type: 'object', properties: { [RESULT]: schema }, required: [RESULT] };
+}
+/** A reply as structured content, which is an object: one of another type is its `result`. */
+export function structured(body) {
+    return typeof body === 'object' && body !== null && !Array.isArray(body)
+        ? body
+        : { [RESULT]: body };
+}
+const RESULT = 'result';
+/**
+ * What the call is, which the revision has a client treat as a hint — and a client that reads
+ * `readOnlyHint` may call a tool without asking, so a route that says it writes is believed over
+ * the verb it is served under.
+ */
+export function annotations(verb, introspection) {
+    const value = {};
+    if (introspection.readonly ?? (verb === 'GET' || verb === 'HEAD'))
+        value.readOnlyHint = true;
+    if (verb === 'DELETE')
+        value.destructiveHint = true;
+    if (verb === 'PUT' || verb === 'DELETE')
+        value.idempotentHint = true;
+    return Object.keys(value).length === 0 ? undefined : value;
+}
+//# sourceMappingURL=schema.js.map

package/transpiled/MCP/schema.js.map

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

package/transpiled/MCP/tools.d.ts

@@ -0,0 +1,31 @@
+import * as http from '../HTTP/index.ts';
+import type { Tree } from '../RTD/index.ts';
+import type { Params, Result, Tool } from './types.ts';
+/**
+ * Every method this caller may reach that is published as a tool, named as the procedure
+ * it is.
+ *
+ * A method is a tool where it says so with `mcp:tool`, and a default denies: a tree holds
+ * what an application serves, and most of it is machinery a model has no business reading.
+ * What a caller may then do with one is what `auth` says. The tree is walked once and each
+ * method describes itself, which is where that is decided and where `io` and `map` say what
+ * may be sent.
+ *
+ * Sorted, because the revision asks for an order a client can cache on.
+ */
+export declare function list(tree: Tree, request: http.Context): Promise<Tool[]>;
+/**
+ * The call the tool is. Its arguments are the procedure's parameters, taken apart the way a
+ * request carries them, and what answers is the same `route` an ordinary request goes to.
+ *
+ * A name that is not a published tool is answered as no tool at all, whether or not a route
+ * would have taken it: what an application did not publish is not reachable here by guessing
+ * its name. What the caller may then do with one that is published is still `auth`'s to say.
+ */
+export declare function call(scope: Scope, named: string, args: Params): Promise<Result>;
+/** Everything a call needs that is not the call: the request it is of, and what answers it. */
+export interface Scope {
+    context: http.Context;
+    route: http.Processor;
+    tree: Tree;
+}

package/transpiled/MCP/tools.js

@@ -0,0 +1,144 @@
+import * as http from '../HTTP/index.js';
+import { fork } from '../RPC/Context.js';
+import { address, name, split } from '../RPC/names.js';
+import { METHOD_NOT_FOUND, failure, refusal, response } from './errors.js';
+import { annotations, input, output, structured } from './schema.js';
+import { FAMILY, MCP } from '../directives/mcp/index.js';
+import { describing } from '../Introspection.js';
+import { variables } from '../RTD/segment.js';
+/**
+ * Every method this caller may reach that is published as a tool, named as the procedure
+ * it is.
+ *
+ * A method is a tool where it says so with `mcp:tool`, and a default denies: a tree holds
+ * what an application serves, and most of it is machinery a model has no business reading.
+ * What a caller may then do with one is what `auth` says. The tree is walked once and each
+ * method describes itself, which is where that is decided and where `io` and `map` say what
+ * may be sent.
+ *
+ * Sorted, because the revision asks for an order a client can cache on.
+ */
+export async function list(tree, request) {
+    /*
+     * A description, not the request asking. What refuses a credentialed request at an
+     * `anonymous` route does not refuse the call a tool makes, and a list that says otherwise
+     * disagrees with what `tools/call` then does.
+     */
+    const context = describing(request);
+    const tools = [];
+    for (const { node, method, tool } of await published(tree)) {
+        // a branch that has expired is not walked, and what it published is not served either
+        if (Date.now() >= node.expiration)
+            continue;
+        if (await method.directives.admits(context))
+            tools.push(tool);
+    }
+    return tools;
+}
+/**
+ * What the tree publishes, in the order a client reads it, whoever is asking: what a tool is
+ * said to be is the route's and not the caller's, and the only thing a caller decides is
+ * whether it is told of one at all.
+ *
+ * Built once per tree — a merged branch drops it — so a `tools/list` describes the tree once
+ * and then answers from what it described.
+ */
+async function published(tree) {
+    return await tree.derived(TOOLS, async () => {
+        const tools = [];
+        for (const { segments, verb, method, node } of tree.walk()) {
+            if (!MCP.published(method.directives.declared(FAMILY)))
+                continue;
+            const named = name(segments, verb);
+            // a route a name cannot spell is a route nothing addresses, here or at `/.rpc`
+            if (named === null)
+                continue;
+            const params = variables(segments);
+            const introspection = await method.describe(params);
+            // a method hidden is hidden from every answer, this one included
+            if (introspection === null)
+                continue;
+            const described = introspection.description;
+            const schema = output(introspection);
+            const hints = annotations(verb, introspection);
+            // in the order the revision documents one, which is the order it is read in
+            const tool = {
+                name: named,
+                ...(introspection.title === undefined ? {} : { title: introspection.title }),
+                ...(described === undefined ? {} : { description: described }),
+                inputSchema: input(introspection, params.map((param) => param.name), method.endpoint?.selection() ?? null),
+                ...(schema === undefined ? {} : { outputSchema: schema }),
+                ...(hints === undefined ? {} : { annotations: hints })
+            };
+            tools.push({ node, method, tool });
+        }
+        // sorted, because the revision asks for an order a client can cache on
+        return tools.sort((one, other) => (one.tool.name < other.tool.name ? -1 : 1));
+    });
+}
+/**
+ * The call the tool is. Its arguments are the procedure's parameters, taken apart the way a
+ * request carries them, and what answers is the same `route` an ordinary request goes to.
+ *
+ * A name that is not a published tool is answered as no tool at all, whether or not a route
+ * would have taken it: what an application did not publish is not reachable here by guessing
+ * its name. What the caller may then do with one that is published is still `auth`'s to say.
+ */
+export async function call(scope, named, args) {
+    if (!serves(scope.tree, named))
+        throw new http.NotFound(response(null, failure(METHOD_NOT_FOUND, `'${named}' is not a tool this server publishes`)));
+    const { path, verb, variables } = address(named, args);
+    const { query, input: body } = split(args, variables);
+    const clone = fork(scope.context, path, verb, query, body);
+    try {
+        const message = await scope.route(clone);
+        // what `io:output` restricts, over this call's reply rather than the envelope
+        await http.shape(clone, message);
+        return result(message.body);
+    }
+    catch (exception) {
+        /*
+         * What the route made of this call is a value a model reads and may correct itself by:
+         * an operation that refused, an argument `io:input` would not take, a record that is
+         * not there, an identity `auth` would not let it act on. A credential is none of those
+         * — that is the client's to fix and not the model's, so it is answered as it is — and
+         * neither is a fault of this server, which is a protocol error and stays one.
+         */
+        if (exception instanceof http.ClientError &&
+            !(exception instanceof http.Unauthorized))
+            return { content: [{ type: 'text', text: refusal(exception) }], isError: true };
+        throw exception;
+    }
+}
+/**
+ * Whether the tree publishes this name as a tool. What `auth` makes of the caller is not
+ * asked here — the declaration is the route's and does not vary by who is calling, and the
+ * call that follows is authorized as any request to that route is.
+ */
+function serves(tree, named) {
+    const names = tree.derived(NAMES, () => {
+        const names = new Map();
+        for (const { segments, verb, method, node } of tree.walk()) {
+            const tool = name(segments, verb);
+            // the first mount of a name is the one a call would reach, as `match` tries them;
+            // one that publishes nothing takes the name all the same
+            if (tool !== null && !names.has(tool))
+                names.set(tool, MCP.published(method.directives.declared(FAMILY)) ? node : null);
+        }
+        return names;
+    });
+    const node = names.get(named);
+    // a branch that has expired publishes nothing, as it answers nothing
+    return node !== undefined && node !== null && Date.now() < node.expiration;
+}
+function result(body) {
+    if (body === undefined || body === null)
+        return { content: [] };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(body) }],
+        structuredContent: structured(body)
+    };
+}
+const TOOLS = 'mcp:tools';
+const NAMES = 'mcp:names';
+//# sourceMappingURL=tools.js.map

package/transpiled/MCP/tools.js.map

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

package/transpiled/MCP/types.d.ts

@@ -0,0 +1,66 @@
+/** The revision this endpoint serves, where a request carries its own metadata. */
+export declare const MODERN = "2026-07-28";
+/** The newest revision reached by an `initialize` handshake, which is what clients still send. */
+export declare const LEGACY = "2025-11-25";
+export declare const VERSIONS: string[];
+/** The version every JSON-RPC message states, which is not the protocol's. */
+export declare const JSONRPC = "2.0";
+/** The prefix the revision reserves for itself in `_meta`. */
+export declare const RESERVED = "io.modelcontextprotocol/";
+export declare const PROTOCOL_VERSION: string;
+export declare const CLIENT_CAPABILITIES: string;
+export declare const SERVER_INFO: string;
+export type Params = Record<string, unknown>;
+export interface Message {
+    jsonrpc: string;
+    method: string;
+    params?: Params;
+    /** Absent makes this a notification, which is answered by not answering. */
+    id?: string | number;
+}
+export interface Failure {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface Response {
+    jsonrpc: string;
+    id: string | number | null;
+    result?: unknown;
+    error?: Failure;
+}
+/**
+ * How long a complete result may be held, and by whom. `private` is a result that is the
+ * caller's alone — a list `auth` filtered for their identity is not another caller's list.
+ */
+export interface Cache {
+    ttlMs: number;
+    cacheScope: 'public' | 'private';
+}
+/** What a tool answers with: what a model reads, and the reply itself. */
+export interface Result {
+    content: Content[];
+    structuredContent?: unknown;
+    /** The operation refused, which is something a model can read and correct. */
+    isError?: boolean;
+}
+export interface Content {
+    type: 'text';
+    text: string;
+}
+export interface Tool {
+    name: string;
+    /** what a person is shown where a client lists this tool; a name is an address */
+    title?: string;
+    /** what the route states this method is */
+    description?: string;
+    inputSchema: object;
+    outputSchema?: object;
+    annotations?: Annotations;
+}
+/** What the verb says about the call, which the revision asks a client to treat as a hint. */
+export interface Annotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+}

package/transpiled/MCP/types.js

@@ -0,0 +1,13 @@
+/** The revision this endpoint serves, where a request carries its own metadata. */
+export const MODERN = '2026-07-28';
+/** The newest revision reached by an `initialize` handshake, which is what clients still send. */
+export const LEGACY = '2025-11-25';
+export const VERSIONS = [MODERN, LEGACY];
+/** The version every JSON-RPC message states, which is not the protocol's. */
+export const JSONRPC = '2.0';
+/** The prefix the revision reserves for itself in `_meta`. */
+export const RESERVED = 'io.modelcontextprotocol/';
+export const PROTOCOL_VERSION = RESERVED + 'protocolVersion';
+export const CLIENT_CAPABILITIES = RESERVED + 'clientCapabilities';
+export const SERVER_INFO = RESERVED + 'serverInfo';
+//# sourceMappingURL=types.js.map

package/transpiled/MCP/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../source/MCP/types.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,CAAC,MAAM,MAAM,GAAG,YAAY,CAAA;AAElC,kGAAkG;AAClG,MAAM,CAAC,MAAM,MAAM,GAAG,YAAY,CAAA;AAElC,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAExC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,CAAA;AAE5B,8DAA8D;AAC9D,MAAM,CAAC,MAAM,QAAQ,GAAG,0BAA0B,CAAA;AAElD,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,GAAG,iBAAiB,CAAA;AAC5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,GAAG,oBAAoB,CAAA;AAClE,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAA"}

package/transpiled/Mapping.d.ts

@@ -1,8 +1,19 @@
-import { type Parameter } from './RTD';
-import type * as http from './HTTP';
-import type * as syntax from './RTD/syntax';
-import type * as core from '@toa.io/core';
+import { type Parameter } from './RTD/index.ts';
+import { Query } from './Query.ts';
+import type { Introspection, Schema } from './Introspection.ts';
+import type { QueryString } from './Query.ts';
+import type * as http from './HTTP/index.ts';
+import type * as syntax from './RTD/syntax/index.ts';
+import type * as core from '@toa.io/core/types';
 export declare abstract class Mapping {
-    static create(query?: syntax.Query): Mapping;
-    abstract fit(input: any, qs: http.Query, parameters: Parameter[]): core.Request;
+    protected readonly query: Query;
+    abstract readonly queryable: boolean;
+    constructor(query: Query);
+    static create(query?: syntax.Query | null, paged?: boolean, streamed?: boolean): Mapping;
+    explain(introspection: Introspection): Record<string, Schema> | null;
+    /** What picks the records a call is about; see `Query.selection`. */
+    selection(): Record<string, Schema> | null;
+    protected assign(input: any, qs: QueryString): void;
+    abstract fit(input: any, query: http.Query, parameters: Parameter[]): core.Request;
 }
+export declare function queryable(query?: syntax.Query | null): boolean;

package/transpiled/Mapping.js

@@ -1,41 +1,67 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Mapping = void 0;
-const Query_1 = require("./Query");
-class Mapping {
-    static create(query) {
-        if (query === undefined || query === null)
-            return new InputMapping();
-        const q = new Query_1.Query(query);
-        return new QueryableMapping(q);
-    }
-}
-exports.Mapping = Mapping;
-class QueryableMapping extends Mapping {
+import { Query } from './Query.js';
+export class Mapping {
     query;
     constructor(query) {
-        super();
         this.query = query;
     }
-    fit(input, qs, parameters) {
-        const query = this.query.fit(qs, parameters);
-        return {
-            input,
-            query
-        };
+    static create(query, paged, streamed) {
+        const q = new Query(query, paged, streamed);
+        return queryable(query) ? new QueryableMapping(q) : new InputMapping(q);
+    }
+    explain(introspection) {
+        return this.query.explain(introspection);
+    }
+    /** What picks the records a call is about; see `Query.selection`. */
+    selection() {
+        return this.query.selection();
+    }
+    assign(input, qs) {
+        if (qs.parameters !== null) {
+            if (typeof input !== 'object' || input === null)
+                throw new Error('Input must be an object to embed query parameters');
+            Object.assign(input, qs.parameters);
+        }
+    }
+}
+class QueryableMapping extends Mapping {
+    queryable = true;
+    fit(input, query, parameters) {
+        const request = {};
+        const qs = this.query.fit(query, parameters);
+        if (input === undefined && qs.parameters !== null)
+            input = {};
+        this.assign(input, qs);
+        if (input !== undefined)
+            request.input = input;
+        if (qs.query !== null)
+            request.query = qs.query;
+        return request;
     }
 }
 class InputMapping extends Mapping {
-    fit(input, _, parameters) {
+    queryable = false;
+    fit(input, query, parameters) {
         const request = {};
-        if (input === undefined && parameters.length > 0)
+        const qs = this.query.fit(query, parameters);
+        if (input === undefined &&
+            (this.query.parameterized || parameters.length > 0 || qs.parameters !== null))
             input = {};
-        if (typeof input === 'object' && input !== null)
+        if (parameters.length > 0) {
+            if (typeof input !== 'object' || input === null)
+                throw new Error('Input must be an object to embed parameters');
             for (const parameter of parameters)
                 input[parameter.name] = parameter.value;
+        }
+        this.assign(input, qs);
         if (input !== undefined)
             request.input = input;
         return request;
     }
 }
+export function queryable(query) {
+    if (query === undefined || query === null)
+        return false;
+    const keys = Object.keys(query);
+    return !(keys.length === 1 && keys[0] === 'parameters');
+}
 //# sourceMappingURL=Mapping.js.map

package/transpiled/Mapping.js.map

@@ -1 +1 @@
-{"version":3,"file":"Mapping.js","sourceRoot":"","sources":["../source/Mapping.ts"],"names":[],"mappings":";;;AACA,mCAA+B;AAK/B,MAAsB,OAAO;IACpB,MAAM,CAAC,MAAM,CAAE,KAAoB;QACxC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YACvC,OAAO,IAAI,YAAY,EAAE,CAAA;QAE3B,MAAM,CAAC,GAAG,IAAI,aAAK,CAAC,KAAK,CAAC,CAAA;QAE1B,OAAO,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAA;IAChC,CAAC;CAGF;AAXD,0BAWC;AAED,MAAM,gBAAiB,SAAQ,OAAO;IACnB,KAAK,CAAO;IAE7B,YAAoB,KAAY;QAC9B,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAEM,GAAG,CAAE,KAAU,EAAE,EAAc,EAAE,UAAuB;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;QAE5C,OAAO;YACL,KAAK;YACL,KAAK;SACN,CAAA;IACH,CAAC;CACF;AAED,MAAM,YAAa,SAAQ,OAAO;IACzB,GAAG,CAAE,KAAU,EAAE,CAAU,EAAE,UAAuB;QACzD,MAAM,OAAO,GAAiB,EAAE,CAAA;QAEhC,IAAI,KAAK,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAC9C,KAAK,GAAG,EAAE,CAAA;QAEZ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAC7C,KAAK,MAAM,SAAS,IAAI,UAAU;gBAChC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAA;QAE3C,IAAI,KAAK,KAAK,SAAS;YACrB,OAAO,CAAC,KAAK,GAAG,KAAK,CAAA;QAEvB,OAAO,OAAO,CAAA;IAChB,CAAC;CACF"}
+{"version":3,"file":"Mapping.js","sourceRoot":"","sources":["../source/Mapping.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAOlC,MAAM,OAAgB,OAAO;IACR,KAAK,CAAO;IAG/B,YAAmB,KAAY;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAEM,MAAM,CAAC,MAAM,CAClB,KAA2B,EAC3B,KAAe,EACf,QAAkB;QAElB,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,KAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAA;QAE5C,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,CAAA;IACzE,CAAC;IAEM,OAAO,CAAC,aAA4B;QACzC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAA;IAC1C,CAAC;IAED,qEAAqE;IAC9D,SAAS;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAA;IAC/B,CAAC;IAES,MAAM,CAAC,KAAU,EAAE,EAAe;QAC1C,IAAI,EAAE,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;YAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAC7C,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAA;YAEtE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,CAAA;QACrC,CAAC;IACH,CAAC;CAOF;AAED,MAAM,gBAAiB,SAAQ,OAAO;IACX,SAAS,GAAG,IAAI,CAAA;IAElC,GAAG,CAAC,KAAU,EAAE,KAAiB,EAAE,UAAuB;QAC/D,MAAM,OAAO,GAAiB,EAAE,CAAA;QAChC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;QAE5C,IAAI,KAAK,KAAK,SAAS,IAAI,EAAE,CAAC,UAAU,KAAK,IAAI;YAAE,KAAK,GAAG,EAAE,CAAA;QAE7D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;QAEtB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,GAAG,KAAK,CAAA;QAE9C,IAAI,EAAE,CAAC,KAAK,KAAK,IAAI;YAAE,OAAO,CAAC,KAAK,GAAG,EAAE,CAAC,KAAK,CAAA;QAE/C,OAAO,OAAO,CAAA;IAChB,CAAC;CACF;AAED,MAAM,YAAa,SAAQ,OAAO;IACP,SAAS,GAAG,KAAK,CAAA;IAEnC,GAAG,CAAC,KAAU,EAAE,KAAiB,EAAE,UAAuB;QAC/D,MAAM,OAAO,GAAiB,EAAE,CAAA;QAChC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;QAE5C,IACE,KAAK,KAAK,SAAS;YACnB,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,UAAU,KAAK,IAAI,CAAC;YAE7E,KAAK,GAAG,EAAE,CAAA;QAEZ,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAC7C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;YAEhE,KAAK,MAAM,SAAS,IAAI,UAAU;gBAAE,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAA;QAC7E,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;QAEtB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,GAAG,KAAK,CAAA;QAE9C,OAAO,OAAO,CAAA;IAChB,CAAC;CACF;AAED,MAAM,UAAU,SAAS,CAAC,KAA2B;IACnD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAEvD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAE/B,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,YAAY,CAAC,CAAA;AACzD,CAAC"}

package/transpiled/Query.d.ts

@@ -1,14 +1,45 @@
-import * as http from './HTTP';
-import { type Parameter } from './RTD';
-import type * as syntax from './RTD/syntax';
-import type * as core from '@toa.io/core';
+import * as http from './HTTP/index.ts';
+import { type Parameter } from './RTD/index.ts';
+import type { Introspection, Schema } from './Introspection.ts';
+import type * as syntax from './RTD/syntax/index.ts';
+import type * as core from '@toa.io/core/types';
 export declare class Query {
+    readonly parameterized: boolean;
     private readonly query;
     private readonly closed;
     private readonly prepend;
-    constructor(query: syntax.Query);
-    fit(query: http.Query, parameters: Parameter[]): core.Query;
+    private readonly queryable;
+    private readonly searchable;
+    /** whether a page is taken of what this answers, and so whether `omit` and `limit` apply */
+    private readonly paged;
+    /** whether this answers a stream of a collection, read in windows of `limit` and continued by `token` */
+    private readonly streamed;
+    constructor(query: syntax.Query, paged?: boolean, streamed?: boolean);
+    fit(query: http.Query, parameters: Parameter[]): QueryString;
+    /**
+     * The querystring parameters this resource declares, which are properties of its own
+     * taken out of the input. What selects records is not among them: that is `selection`.
+     */
+    explain(introspection: Introspection): Record<string, Schema> | null;
+    /**
+     * What picks the records a call is about, which is the querystring the gateway reads
+     * rather than anything the resource declares.
+     */
+    selection(): Record<string, Schema> | null;
+    private split;
     private fitCriteria;
+    /** A route that answers one object is not paged, so a request that pages it is a mistake. */
+    private refuseRanges;
+    /**
+     * A stream of a collection is read a window after the one before it, which the token says, so
+     * it takes a `limit` where the route declares one and never an `omit`. One that declares no
+     * `limit` answers the whole collection at once.
+     */
+    private fitWindow;
     private fitRanges;
     private fitSort;
 }
+export interface QueryString {
+    query: core.Query | null;
+    parameters: Record<string, string> | null;
+}