@aventara/core 1.0.0-rc.10 → 1.0.0-rc.11

package/dist/protocol/operation-set.decoder.js

@@ -0,0 +1,185 @@
+import { validationIssue, } from "../operations/validation-code.js";
+import { operationFailure, } from "../runtime/operation-response.js";
+import { checkPostRoute } from "./absent-route.responder.js";
+import { isParsedByDecoder, markParsedByDecoder, readBody, transportOf, } from "./http-request.decoder.js";
+import { ALL_ROUTE, readRequest } from "./http-request.reader.js";
+import { encodeOperationResponse, } from "./http-response.encoder.js";
+const BODY_KEYS = ["operations"];
+const ENTRY_KEYS = ["resource", "family", "variant", "args"];
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+export function decodeAllRequest(contracts, received, origin = "client") {
+    const read = readRequest(received);
+    if (!read.ok) {
+        return read;
+    }
+    const { requestId } = read;
+    const refuse = (response) => ({ ok: false, response, requestId });
+    const route = checkPostRoute(ALL_ROUTE, contracts, read, origin);
+    if (!route.ok) {
+        return refuse(route.response);
+    }
+    const body = readBody(read, contracts, origin);
+    if (!body.ok) {
+        return refuse(body.response);
+    }
+    const entries = readEntries(body.value, contracts[origin].limits.maxAll, isParsedByDecoder(body.value));
+    if (!Array.isArray(entries)) {
+        return refuse(encodeOperationResponse(entries, requestId));
+    }
+    return {
+        ok: true,
+        request: {
+            origin,
+            requestId,
+            protocol: route.protocol,
+            transport: transportOf(read),
+            entries,
+            streamed: acceptsNdjson(read.headers.accept),
+        },
+        requestId,
+    };
+}
+function shapeFailure(issue) {
+    return operationFailure("A2004", {
+        message: "Operation Set failed framework validation.",
+        issues: [issue],
+    });
+}
+function readEntries(body, maxAll, parsedHere) {
+    const members = ownMembers(body, []);
+    if (!(members instanceof Map)) {
+        return shapeFailure(members);
+    }
+    const exact = exactMembers(members, BODY_KEYS, []);
+    if (exact !== undefined) {
+        return shapeFailure(exact);
+    }
+    const operations = members.get("operations");
+    const keyed = isRecord(operations)
+        ? ownMembers(operations, ["operations"])
+        : undefined;
+    if (keyed === undefined) {
+        return shapeFailure(validationIssue("V1001", ["operations"], "operations must be an object."));
+    }
+    if (!(keyed instanceof Map)) {
+        return shapeFailure(keyed);
+    }
+    if (keyed.size === 0) {
+        return shapeFailure(validationIssue("V1004", ["operations"], "Value outside accepted range."));
+    }
+    if (keyed.size > maxAll) {
+        return operationFailure("A2009", {
+            message: "Operation count exceeds the active Contract limit.",
+            issues: [
+                validationIssue("V1014", ["operations"], `Operation count exceeds maxAll (${maxAll}).`),
+            ],
+        });
+    }
+    for (const key of keyed.keys()) {
+        if (!IDENTIFIER.test(key)) {
+            return shapeFailure(validationIssue("V1001", ["operations"], "Every operation key must be an identifier."));
+        }
+    }
+    const entries = [];
+    for (const [key, value] of keyed) {
+        const entry = readEntry(key, value);
+        if (!("key" in entry)) {
+            return shapeFailure(entry);
+        }
+        if (parsedHere) {
+            markParsedByDecoder(entry.args);
+        }
+        entries.push(entry);
+    }
+    return entries;
+}
+function readEntry(key, value) {
+    const at = ["operations", key];
+    const members = isRecord(value) ? ownMembers(value, at) : undefined;
+    if (members === undefined) {
+        return validationIssue("V1001", at, "Operation entry must be an object.");
+    }
+    if (!(members instanceof Map)) {
+        return members;
+    }
+    const exact = exactMembers(members, ENTRY_KEYS, at);
+    if (exact !== undefined) {
+        return exact;
+    }
+    const strings = {};
+    for (const name of ["resource", "family", "variant"]) {
+        const member = members.get(name);
+        if (typeof member !== "string") {
+            return validationIssue("V1001", [...at, name], `${name} must be a string.`);
+        }
+        strings[name] = member;
+    }
+    const args = members.get("args");
+    if (!isRecord(args)) {
+        return validationIssue("V1001", [...at, "args"], "args must be an object.");
+    }
+    return {
+        key,
+        resource: strings.resource,
+        family: strings.family,
+        variant: strings.variant,
+        args,
+    };
+}
+function isRecord(value) {
+    try {
+        return typeof value === "object" && value !== null && !Array.isArray(value);
+    }
+    catch {
+        return false;
+    }
+}
+function ownMembers(value, at) {
+    const refused = (message) => validationIssue("V1001", at, message);
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return refused("Value must be a plain object.");
+        }
+        const members = new Map();
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key === "symbol") {
+                return refused("Symbol properties are not valid here.");
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor === undefined ||
+                !descriptor.enumerable ||
+                !("value" in descriptor)) {
+                return refused("Every property must be an own enumerable data property.");
+            }
+            members.set(key, descriptor.value);
+        }
+        return members;
+    }
+    catch {
+        return refused("Value could not be read.");
+    }
+}
+function exactMembers(members, names, at) {
+    for (const name of names) {
+        if (!members.has(name)) {
+            return validationIssue("V1000", [...at, name], `Required property "${name}" is missing.`);
+        }
+    }
+    for (const key of members.keys()) {
+        if (!names.includes(key)) {
+            return validationIssue("V1001", [...at, key], `Property "${key}" is not valid here.`);
+        }
+    }
+    return undefined;
+}
+function acceptsNdjson(accept) {
+    if (accept === undefined) {
+        return false;
+    }
+    return accept.split(",").some((range) => {
+        const [type, ...parameters] = range.split(";").map((part) => part.trim());
+        return (type?.toLowerCase() === "application/x-ndjson" &&
+            !parameters.some((parameter) => /^q\s*=\s*0(\.0{0,3})?$/i.test(parameter)));
+    });
+}

package/dist/protocol/operation-set.handler.d.ts

@@ -0,0 +1,27 @@
+import { type AbortSignalShape } from "../framework/operation-set.runner.js";
+import type { AvProtocolRequest } from "./http-request.decoder.js";
+import { type AvProtocolResponse } from "./http-response.encoder.js";
+import { type HandlerContext, type ProtocolCallOptions } from "./protocol.handler.js";
+/** What a host passes beside an Operation Set request. */
+export type OperationSetCallOptions = ProtocolCallOptions & {
+    /** Aborted when the client disconnects: entries not yet started never start, and nothing more is written. */
+    readonly signal?: AbortSignalShape;
+};
+/** A streamed answer: status, headers, and the body as lines produced as entries settle. */
+type OperationSetStreamedResponse = {
+    readonly status: 200;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: AsyncIterable<string>;
+};
+/**
+ * `protocol.handleAll(request, options?)`: the `/_all` request decoded, its state
+ * seeded once, its principal derived once, and every entry run through the bound
+ * Framework's own `execute` concurrently, at most `limits.maxAllConcurrency` at once, each
+ * answered by the envelope its single route writes. The whole request is refused
+ * only for its transport, identity, body shape or `limits.maxAll`, or when its
+ * seed or principal fails; otherwise it is `200 A1000` with `data` keyed by the
+ * caller's keys, or, under `Accept: application/x-ndjson`, one line per entry as
+ * it settles. Total over any value, as `handleOperation` is.
+ */
+export declare function handleAllRequest(context: HandlerContext, request: AvProtocolRequest, options?: OperationSetCallOptions): Promise<AvProtocolResponse | OperationSetStreamedResponse>;
+export {};

package/dist/protocol/operation-set.handler.js

@@ -0,0 +1,179 @@
+import { maxAllConcurrencyOf, } from "../framework/operation-set.runner.js";
+import { createDiagnosticsReporter, } from "../runtime/diagnostics-reporter.js";
+import { internalFailure } from "../runtime/operation-response.js";
+import { resolveOperationRoute } from "./absent-route.responder.js";
+import { encodeOperationResponse, encodeOperationSetResponse, operationSetLine, streamedHeaders, } from "./http-response.encoder.js";
+import { decodeAllRequest, } from "./operation-set.decoder.js";
+import { admitOperation, seededState, } from "./protocol.handler.js";
+export async function handleAllRequest(context, request, options) {
+    const decoded = decodeAllRequest(context.contracts, request, context.origin);
+    if (!decoded.ok) {
+        return decoded.response;
+    }
+    const set = decoded.request;
+    const signal = signalOf(options);
+    const entries = set.entries.map((entry) => admitEntry(context, set, entry));
+    const reportEach = (error, code, marks) => {
+        for (const entry of entries) {
+            if ("report" in entry) {
+                entry.report(error, code, marks);
+            }
+        }
+    };
+    const seeded = await seededState(options, reportEach, {
+        path: ["operations"],
+        arguments: undefined,
+    });
+    if (!seeded.ok) {
+        return encodeOperationResponse(seeded.response, set.requestId);
+    }
+    const state = seeded.state ?? {};
+    let caller;
+    try {
+        caller = await context.owned?.caller({ origin: set.origin, state });
+    }
+    catch (error) {
+        reportEach(error, "A3000");
+        return encodeOperationResponse(internalFailure(), set.requestId);
+    }
+    const run = (entry) => "answered" in entry
+        ? Promise.resolve(entry.answered)
+        : runEntry(entry, state, caller, set.requestId);
+    const cap = Math.min(maxAllConcurrencyOf(context.contracts[set.origin].limits), entries.length);
+    if (!set.streamed) {
+        const settled = new Map();
+        await runConcurrently(entries, cap, () => signal?.aborted === true, run, (entry, text) => {
+            settled.set(entry.key, text);
+        });
+        return encodeOperationSetResponse(entries.flatMap(({ key }) => {
+            const envelope = settled.get(key);
+            return envelope === undefined ? [] : [{ key, envelope }];
+        }), set.requestId);
+    }
+    return {
+        status: 200,
+        headers: streamedHeaders(set.requestId),
+        body: streamLines(entries, cap, signal, run),
+    };
+}
+function signalOf(options) {
+    const signal = options?.signal;
+    return typeof signal === "object" &&
+        signal !== null &&
+        typeof signal.aborted === "boolean" &&
+        typeof signal.addEventListener === "function"
+        ? signal
+        : undefined;
+}
+function admitEntry(context, set, entry) {
+    const route = resolveOperationRoute(context.contracts, set.protocol, entry, set.origin);
+    if (!route.ok) {
+        return {
+            key: entry.key,
+            answered: encodeOperationResponse(route.failure, set.requestId).body,
+        };
+    }
+    const request = {
+        origin: set.origin,
+        requestId: set.requestId,
+        resource: entry.resource,
+        ...route.operation,
+        protocol: set.protocol,
+        transport: set.transport,
+        arguments: entry.args,
+    };
+    return {
+        key: entry.key,
+        admitted: admitOperation(context, request),
+        report: createDiagnosticsReporter(context.sink, request, undefined, entry.key),
+    };
+}
+async function runEntry(entry, state, caller, requestId) {
+    const { admitted, key, report } = entry;
+    let response;
+    try {
+        response = await admitted.run({ ...admitted.request, state }, caller === undefined ? { key } : { caller, key });
+    }
+    catch (error) {
+        report(error, "A3000");
+        response = internalFailure();
+    }
+    return encodeOperationResponse(response, requestId, (error) => report(error, "A3003")).body;
+}
+function runConcurrently(entries, cap, stopped, run, settled) {
+    return new Promise((resolve) => {
+        let next = 0;
+        let running = 0;
+        const launch = () => {
+            while (running < cap && next < entries.length && !stopped()) {
+                const entry = entries[next];
+                next += 1;
+                running += 1;
+                run(entry).then((text) => {
+                    running -= 1;
+                    settled(entry, text);
+                    launch();
+                }, () => {
+                    running -= 1;
+                    launch();
+                });
+            }
+            if (running === 0) {
+                resolve();
+            }
+        };
+        launch();
+    });
+}
+function streamLines(entries, cap, signal, run) {
+    const queue = [];
+    let finished = false;
+    let halted = false;
+    const waiting = [];
+    const notify = () => {
+        for (const wake of waiting.splice(0)) {
+            wake();
+        }
+    };
+    const stopped = () => halted || signal?.aborted === true;
+    const halt = () => {
+        halted = true;
+        signal?.removeEventListener("abort", notify);
+        notify();
+    };
+    signal?.addEventListener("abort", notify, { once: true });
+    void runConcurrently(entries, cap, stopped, run, (entry, text) => {
+        if (!stopped()) {
+            queue.push(operationSetLine(entry.key, text));
+        }
+        notify();
+    }).then(() => {
+        finished = true;
+        signal?.removeEventListener("abort", notify);
+        notify();
+    });
+    const end = { done: true, value: undefined };
+    const iterator = {
+        async next() {
+            while (!stopped()) {
+                const line = queue.shift();
+                if (line !== undefined) {
+                    return { done: false, value: line };
+                }
+                if (finished) {
+                    break;
+                }
+                await new Promise((resolve) => {
+                    waiting.push(resolve);
+                });
+            }
+            halt();
+            return end;
+        },
+        async return() {
+            halt();
+            return end;
+        },
+    };
+    return { [Symbol.asyncIterator]: () => iterator };
+}

package/dist/protocol/protocol-headers.d.ts

@@ -27,6 +27,11 @@ export declare function headerValue(normalized: Readonly<Record<string, string>>
  * protocol and ClientContract it speaks, so there is nothing to compare.
  */
 export declare function protocolIdentityOf(normalized: Readonly<Record<string, string>>): AvRequestProtocol | undefined;
+/**
+ * The `Aventara-Protocol-Version` header as a number — `NaN` when it is not a
+ * decimal integer — or `undefined` when it is absent.
+ */
+export declare function protocolVersionOf(normalized: Readonly<Record<string, string>>): number | undefined;
 /**
  * The identity headers a request did not send, in the order the framework sends them —
  * what the `A2000` answering it names. Empty exactly when {@link protocolIdentityOf}
@@ -39,4 +44,8 @@ export type IdentityHeaderName = (typeof headers)["protocolVersion"] | (typeof h
  * A repeated header joins with `", "`, which holds a space, so it is never adopted.
  */
 export declare function adoptedRequestId(normalized: Readonly<Record<string, string>>): string | undefined;
+/** The header every answer to a GET carries: `X-Content-Type-Options: nosniff`. */
+export declare const NO_SNIFF: Readonly<{
+    readonly "X-Content-Type-Options": "nosniff";
+}>;
 export {};

package/dist/protocol/protocol-headers.js

@@ -24,15 +24,19 @@ export function headerValue(normalized, name) {
 }
 const PROTOCOL_VERSION_TEXT = /^(?:0|[1-9]\d*)$/;
 export function protocolIdentityOf(normalized) {
-    const version = headerValue(normalized, headers.protocolVersion);
+    const version = protocolVersionOf(normalized);
     const hash = headerValue(normalized, headers.contractHash);
     if (version === undefined || hash === undefined) {
         return undefined;
     }
-    return {
-        version: PROTOCOL_VERSION_TEXT.test(version) ? Number(version) : Number.NaN,
-        hash,
-    };
+    return { version, hash };
+}
+export function protocolVersionOf(normalized) {
+    const version = headerValue(normalized, headers.protocolVersion);
+    if (version === undefined) {
+        return undefined;
+    }
+    return PROTOCOL_VERSION_TEXT.test(version) ? Number(version) : Number.NaN;
 }
 export function missingIdentityHeaders(normalized) {
     return [headers.protocolVersion, headers.contractHash].filter((name) => headerValue(normalized, name) === undefined);
@@ -44,3 +48,6 @@ export function adoptedRequestId(normalized) {
         ? value
         : undefined;
 }
+export const NO_SNIFF = Object.freeze({
+    "X-Content-Type-Options": "nosniff",
+});

package/dist/protocol/protocol-surface.d.ts

@@ -6,7 +6,7 @@ import { type AvOperationIdentity } from "../operations/operation-identity.js";
  */
 export type SurfaceRoute = ({
     readonly kind: "operation";
-    readonly method: "POST";
+    readonly method: "POST" | "GET";
     readonly path: `/_resources/${string}`;
     readonly resource: string;
 } & AvOperationIdentity) | {
@@ -21,12 +21,20 @@ export type SurfaceRoute = ({
     readonly kind: "can";
     readonly method: "POST";
     readonly path: "/_access/can";
+} | {
+    readonly kind: "all";
+    readonly method: "POST";
+    readonly path: "/_all";
 };
+/** Whether `client` advertises at least one operation: exactly when `/_all` is a route. */
+export declare function advertisesAnyOperation(client: AvContractClient): boolean;
 /**
  * The route list of one ClientContract: every route a host mounts, from one list,
  * deep-frozen — exactly the advertised operation triples in the Contract's own key
- * order, then `GET /_contract`, then `POST /_transactions` when, and only when,
- * `transactions === "interactive"`, then `POST /_access/can` when, and only when,
- * the Contract has its `access` section.
+ * order (a `find` triple the Contract marks cacheable twice: `POST`, then `GET`),
+ * then `GET /_contract`, then `POST /_transactions` when, and only when,
+ * `transactions === "interactive"`, then `POST /_all` when, and only when, it
+ * advertises an operation, then `POST /_access/can` when, and only when, the
+ * Contract has its `access` section.
  */
 export declare function surfaceOf(client: AvContractClient): readonly SurfaceRoute[];

package/dist/protocol/protocol-surface.js

@@ -2,6 +2,21 @@ import { lookupOwn, lookupResource } from "../contracts/contract-lookup.js";
 import { isOperationVariantAvailable } from "../contracts/resource-operations.js";
 import { parseOperationIdentity, } from "../operations/operation-identity.js";
 const ownKeys = (record) => record === undefined ? [] : Object.keys(record);
+export function advertisesAnyOperation(client) {
+    for (const resourceName of ownKeys(client.resources)) {
+        const advertised = lookupResource(client, resourceName)?.operations;
+        for (const familyName of ownKeys(advertised)) {
+            const family = lookupOwn(advertised, familyName);
+            for (const variantName of ownKeys(family)) {
+                if (parseOperationIdentity(familyName, variantName) !== undefined &&
+                    isOperationVariantAvailable(lookupOwn(family, variantName))) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}
 export function surfaceOf(client) {
     const routes = [];
     for (const resourceName of ownKeys(client.resources)) {
@@ -15,13 +30,24 @@ export function surfaceOf(client) {
                     !isOperationVariantAvailable(lookupOwn(family, variantName))) {
                     continue;
                 }
+                const path = `/_resources/${[resourceName, identity.family, identity.variant].map(encodeURIComponent).join("/")}`;
                 routes.push(Object.freeze({
                     kind: "operation",
                     method: "POST",
-                    path: `/_resources/${[resourceName, identity.family, identity.variant].map(encodeURIComponent).join("/")}`,
+                    path,
                     resource: resourceName,
                     ...identity,
                 }));
+                if (identity.family === "find" &&
+                    lookupOwn(resource?.cache, identity.variant) !== undefined) {
+                    routes.push(Object.freeze({
+                        kind: "operation",
+                        method: "GET",
+                        path,
+                        resource: resourceName,
+                        ...identity,
+                    }));
+                }
             }
         }
     }
@@ -37,6 +63,13 @@ export function surfaceOf(client) {
             path: "/_transactions",
         }));
     }
+    if (advertisesAnyOperation(client)) {
+        routes.push(Object.freeze({
+            kind: "all",
+            method: "POST",
+            path: "/_all",
+        }));
+    }
     if (client.access !== undefined) {
         routes.push(Object.freeze({
             kind: "can",

package/dist/protocol/protocol.binder.d.ts

@@ -17,7 +17,8 @@ export type AvProtocolBinding = {
      * tagged by `kind`: one `POST` `operation` route per `(resource, family, variant)`
      * it advertises and no other, then the `contract` route `GET /_contract`
      * (always), then the `transactions` route `POST /_transactions` exactly when its
-     * `transactions` is `"interactive"`, then the `can` route `POST /_access/can`
+     * `transactions` is `"interactive"`, then the `all` route `POST /_all` exactly
+     * when it advertises an operation, then the `can` route `POST /_access/can`
      * exactly when it has its `access` section. Each path is relative to
      * `framework.api`. Read once at bind time: every call answers the same
      * deep-frozen list, which is passive data a host may serialize.
@@ -103,6 +104,41 @@ export type AvProtocolBinding = {
         /** Seeds the request's `ctx.$state`, as for `handleOperation`. */
         readonly state?: () => AvState | Promise<AvState>;
     }) => Promise<AvProtocolResponse>;
+    /**
+     * The `POST /_all` shortcut: one Operation Set — any mix of the operations the
+     * bound Contract advertises, under the caller's own identifier keys — decoded,
+     * its `ctx.$state` seeded once through `options.state` (one state every entry
+     * shares), its principal derived once, and every entry run concurrently,
+     * exactly as through its own route, at most `limits.maxAllConcurrency` at once.
+     * Answers `200 A1000` with `data` holding each key's own envelope, the one its
+     * single route writes. Under `Accept: application/x-ndjson` it answers `200`
+     * with `body` an async iterable of lines instead, one per entry as it settles:
+     * `{"key":…,"envelope":…}` and a newline. Refused whole only for its
+     * transport, identity, body shape or `limits.maxAll`, or when its seed or
+     * principal fails, as plain JSON at that code's status. When `options.signal`
+     * aborts (the client went away), entries not yet started never start and no
+     * more lines are written (a plain answer then holds only the entries that
+     * ran); so it is when the host stops reading. Absent (`404
+     * A2002`) on a Contract that advertises no operation. Total over any value, as
+     * `handleOperation` is.
+     */
+    readonly handleAll: (request: AvProtocolRequest, options?: {
+        /** Seeds the set's one `ctx.$state`, as for `handleOperation`. */
+        readonly state?: () => AvState | Promise<AvState>;
+        /** The client's disconnect: entries not yet started never start. Any platform's `AbortSignal` is one. */
+        readonly signal?: {
+            readonly aborted: boolean;
+            readonly reason: unknown;
+            addEventListener(type: "abort", listener: () => void, options?: {
+                readonly once?: boolean;
+            }): void;
+            removeEventListener(type: "abort", listener: () => void): void;
+        };
+    }) => Promise<AvProtocolResponse | {
+        readonly status: 200;
+        readonly headers: Readonly<Record<string, string>>;
+        readonly body: AsyncIterable<string>;
+    }>;
     /**
      * The `GET /_contract` responder: the bound ClientContract's JCS-canonical bytes,
      * `ETag` its quoted hash, `Cache-Control: no-cache`, and `304` with no body when

package/dist/protocol/protocol.binder.js

@@ -5,6 +5,7 @@ import { answerAbsentRequest } from "./absent-route.responder.js";
 import { contractDocumentOf, encodeContractRequest, } from "./contract-document.responder.js";
 import { decodeOperationRequest, decodeTransactionRequest, } from "./http-request.decoder.js";
 import { encodeOperationResponse, encodeTransactionResponse, } from "./http-response.encoder.js";
+import { handleAllRequest, } from "./operation-set.handler.js";
 import { handleCanRequest, handleOperationRequest, handleTransactionRequest, operationUnencodableReport, planUnencodableReport, } from "./protocol.handler.js";
 import { transportFailure } from "./protocol-failure.js";
 import { surfaceOf } from "./protocol-surface.js";
@@ -36,6 +37,7 @@ export function bind(framework, options) {
         handleOperation: (request, options) => handleOperationRequest(handler, request, options),
         handleTransaction: (request, options) => handleTransactionRequest(handler, request, options),
         handleCan: (request, options) => handleCanRequest(handler, request, options),
+        handleAll: (request, options) => handleAllRequest(handler, request, options),
         encodeContract: (request) => encodeContractRequest(document, request),
         answerAbsent: (request) => answerAbsentRequest(contracts, request, sink, origin),
     });

package/dist/protocol/protocol.handler.d.ts

@@ -2,8 +2,9 @@ import type { AvContracts } from "../compiler/contract.compiler.js";
 import type { RemoteRequestOrigin } from "../config/config-layer.js";
 import type { AvFramework } from "../framework/framework.js";
 import type { AccessQuestionsAnswerer } from "../policy/access-question.runtime.js";
-import { type AvDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
+import { type AvDiagnosticsSink, createReporter } from "../runtime/diagnostics-reporter.js";
 import type { RemoteOperationRequest } from "../runtime/operation-request.js";
+import { type AvOperationFailureResponse, type AvOperationResponse } from "../runtime/operation-response.js";
 import type { OwnedExecution } from "../runtime/owned-execution.registry.js";
 import type { AvState } from "../runtime/request-state.js";
 import { type AvProtocolRequest } from "./http-request.decoder.js";
@@ -14,7 +15,7 @@ import { type AvProtocolResponse, type UnencodableReport } from "./http-response
  * decoder parsed without copying it again (absent for anything but a
  * constructed Framework) — and its configured diagnostics sink.
  */
-type HandlerContext = {
+export type HandlerContext = {
     readonly contracts: AvContracts;
     /** The origin every request the binding decodes runs under. */
     readonly origin: RemoteRequestOrigin;
@@ -25,11 +26,43 @@ type HandlerContext = {
     /** The Framework's `can` answerer: absent for one without `access`, or anything `createFramework` did not return. */
     readonly can: AccessQuestionsAnswerer | undefined;
 };
+/** A decoded operation as the shortcut runs it: the arguments it reads, and its entry. */
+export type AdmittedOperation = {
+    readonly request: RemoteOperationRequest;
+    /**
+     * `member` is an Operation Set entry's (its principal, derived once for the
+     * set, and its key), which only a constructed Framework's owned entry reads.
+     */
+    readonly run: (request: RemoteOperationRequest, member?: OperationSetMember) => Promise<AvOperationResponse>;
+};
+/**
+ * The entry a decoded operation runs through, with the arguments it reads, settled
+ * at the call, before the shortcut's first await. A body parsed here from raw
+ * content is fresh and runs uncopied. A host's `{ kind: "parsed" }` body is the
+ * host's object, so it is copied here, as `framework.execute` copies a server-side
+ * caller's arguments when called: a change the host makes after the call changes
+ * nothing, and a body that cannot be copied is answered as that door answers it
+ * (`A2004`/`V1001` at its path), never read again.
+ */
+export declare function admitOperation(context: HandlerContext, request: RemoteOperationRequest): AdmittedOperation;
+/** What an Operation Set entry runs under besides its request: the set's principal, and its key. */
+type OperationSetMember = NonNullable<Parameters<OwnedExecution["execute"]>[2]>;
 /** What a host passes beside one protocol request. */
 export type ProtocolCallOptions = {
     /** Seeds the request's `ctx.$state`; called once, after decoding. Omitted, the state is `{}`. */
     readonly state?: () => AvState | Promise<AvState>;
 };
+/** The request's seeded state, or the failure the seed's throw answers. */
+export declare function seededState(options: ProtocolCallOptions | undefined, report: ReturnType<typeof createReporter>, view: {
+    readonly path: readonly (string | number)[];
+    readonly arguments: unknown;
+}): Promise<{
+    readonly ok: true;
+    readonly state: AvState | undefined;
+} | {
+    readonly ok: false;
+    readonly response: AvOperationFailureResponse;
+}>;
 /**
  * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a `"transaction"`
  * diagnostic — client origin, the request id the plan ran under, and the step the