@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.0

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

@@ -2,21 +2,25 @@ import type { FrameworkContracts } from "../compiler/contract.compiler.js";
 import type { Framework } from "../framework/framework.js";
 import { type FrameworkDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
 import type { ClientOperationRequest } from "../runtime/operation-request.js";
+import type { OwnedExecution } from "../runtime/owned-execution.registry.js";
 import { type AvProtocolRequest } from "./http-request.decoder.js";
 import { type AvProtocolResponse, type UnencodableReport } from "./http-response.encoder.js";
 /**
  * What the shortcuts read off the bound Framework: its compiled Contracts, its
- * execution entry points and its configured diagnostics sink.
+ * execution entry points — the public ones, and the owned ones that run a body this
+ * decoder parsed without copying it again (absent for anything but a
+ * constructed Framework) — and its configured diagnostics sink.
  */
 export type HandlerContext = {
     readonly contracts: FrameworkContracts;
     readonly execute: Framework["execute"];
     readonly executeTransaction: Framework["executeTransaction"];
+    readonly owned: OwnedExecution | undefined;
     readonly sink: FrameworkDiagnosticsSink | undefined;
 };
 /**
  * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a `"transaction"`
- * diagnostic — client scope, the request id the plan ran under, and the step the
+ * diagnostic — client origin, the request id the plan ran under, and the step the
  * encoder blames as `operation` when it blames one. One spelling for both
  * `protocol.encodeTransaction` and `protocol.handleTransaction`.
  */

package/dist/protocol/protocol.handler.js

@@ -1,10 +1,20 @@
 import { createDiagnosticsReporter, createReporter, } from "../runtime/diagnostics-reporter.js";
-import { decodeOperationRequest, decodeTransactionRequest, } from "./http-request.decoder.js";
+import { decodeOperationRequest, decodeTransactionRequest, isParsedByDecoder, } from "./http-request.decoder.js";
 import { encodeOperationResponse, encodeTransactionResponse, } from "./http-response.encoder.js";
+function operationEntry(context, request) {
+    return context.owned !== undefined && isParsedByDecoder(request.arguments)
+        ? context.owned.execute
+        : context.execute;
+}
+function transactionEntry(context, request) {
+    return context.owned !== undefined && isParsedByDecoder(request.plan)
+        ? context.owned.executeTransaction
+        : context.executeTransaction;
+}
 export function planUnencodableReport(sink, requestId) {
     return (error, operation) => createReporter(sink, {
         kind: "transaction",
-        scope: "client",
+        origin: "client",
         requestId,
         ...(operation === undefined ? {} : { operation }),
     })(error, "A3003");
@@ -17,7 +27,7 @@ export async function handleOperationRequest(context, request) {
     if (!decoded.ok) {
         return decoded.response;
     }
-    const response = await context.execute(decoded.request);
+    const response = await operationEntry(context, decoded.request)(decoded.request);
     return encodeOperationResponse(response, decoded.requestId, operationUnencodableReport(context.sink, decoded.request));
 }
 export async function handleTransactionRequest(context, request) {
@@ -25,6 +35,6 @@ export async function handleTransactionRequest(context, request) {
     if (!decoded.ok) {
         return decoded.response;
     }
-    const response = await context.executeTransaction(decoded.request);
+    const response = await transactionEntry(context, decoded.request)(decoded.request);
     return encodeTransactionResponse(response, decoded.requestId, planUnencodableReport(context.sink, decoded.requestId));
 }

package/dist/protocol/unmounted-route.error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What the diagnostics sink receives when `protocol.answerAbsent` is handed a
+ * request for a route the ClientContract advertises, with that route's own
+ * method: the host mounted only part of `protocol.surface()`. The caller's
+ * `500 A3000` is unchanged; this error names the route the host left out, so the
+ * server's diagnostics show it too. It is never sent to the caller.
+ */
+export declare class UnmountedRouteError extends Error {
+    /** What the ClientContract advertises: `resource.family.variant`, or `transactions`. */
+    readonly advertised: string;
+    /** The route as the request reached it: method and entrypoint-relative path. */
+    readonly route: string;
+    readonly name = "UnmountedRouteError";
+    constructor(
+    /** What the ClientContract advertises: `resource.family.variant`, or `transactions`. */
+    advertised: string, 
+    /** The route as the request reached it: method and entrypoint-relative path. */
+    route: string);
+}

package/dist/protocol/unmounted-route.error.js

@@ -0,0 +1,10 @@
+export class UnmountedRouteError extends Error {
+    advertised;
+    route;
+    name = "UnmountedRouteError";
+    constructor(advertised, route) {
+        super(`The ClientContract advertises ${advertised}, but the host mounted no route for ${route}, so protocol.answerAbsent answered it 500 A3000. Mount every protocol.surface() entry.`);
+        this.advertised = advertised;
+        this.route = route;
+    }
+}

package/dist/runtime/caller-data.copier.d.ts

@@ -0,0 +1,59 @@
+/** Why a caller value could not be copied. */
+export type CallerDataFailureKind = "unreadable-value" | "non-plain-value";
+/** A data location inside the copied value, from its root. */
+export type CallerDataPath = readonly (string | number)[];
+/**
+ * The curated failure of a door copy: what failed and where, relative to the copied
+ * root. Thrown by {@link copyCallerData} and caught by every door, which answers it as
+ * the caller's `A2004`/`V1001` at its own address. It never carries the value.
+ */
+export declare class CallerDataError extends Error {
+    readonly kind: CallerDataFailureKind;
+    readonly path: CallerDataPath;
+    /**
+     * The control mirror `path` starts from, when the failure is a mirror's
+     * tripwire read after the door; {@link locateCallerDataError} resolves it.
+     */
+    readonly within?: object | undefined;
+    readonly name = "CallerDataError";
+    constructor(kind: CallerDataFailureKind, path: CallerDataPath, 
+    /**
+     * The control mirror `path` starts from, when the failure is a mirror's
+     * tripwire read after the door; {@link locateCallerDataError} resolves it.
+     */
+    within?: object | undefined);
+}
+/**
+ * Objects a door keeps by identity rather than copying: values the framework built
+ * itself (a builder's `$ref` placeholder), or a request envelope's members, each
+ * copied by its own door. Never a caller's own object that a later reader reads.
+ * Asked about every object, arrays included, before anything else of it is read.
+ */
+export type CallerDataKeep = (value: object) => boolean;
+/**
+ * Objects a door mirrors by their descriptors rather than copying by value: a plan's
+ * `$ref` control objects (see {@link mirrorControlData}). Asked about every object
+ * the door does not keep, before anything else of it is read.
+ */
+export type CallerDataMirror = (value: object) => boolean;
+/** How a door treats the objects it meets; copying by value unless stated. */
+export type CallerDataPolicy = {
+    readonly keep?: CallerDataKeep;
+    readonly mirror?: CallerDataMirror;
+};
+/**
+ * Places a mirror tripwire's failure in the value the door copied: its path from the
+ * copy's root, where `error.path` started from the mirror. A failure that is not a
+ * tripwire's, or a mirror the copy does not hold, is returned as it is.
+ */
+export declare function locateCallerDataError(error: CallerDataError, copy: unknown): CallerDataError;
+/**
+ * Copies a caller's value into fresh plain data (see the module note), reading the
+ * caller's objects exactly once.
+ *
+ * @throws {@link CallerDataError} when a value cannot be read or is not plain data,
+ *   naming its path from `value`.
+ */
+export declare function copyCallerData(value: unknown, policy?: CallerDataPolicy): unknown;
+/** The `V1001` message a door answers a {@link CallerDataError} with. */
+export declare function callerDataFailureMessage(kind: CallerDataFailureKind): string;

package/dist/runtime/caller-data.copier.js

@@ -0,0 +1,470 @@
+import { Decimal } from "./decimal.js";
+const FAILURE_MESSAGES = {
+    "unreadable-value": "Value could not be read.",
+    "non-plain-value": "Value must be plain data.",
+};
+export class CallerDataError extends Error {
+    kind;
+    path;
+    within;
+    name = "CallerDataError";
+    constructor(kind, path, within) {
+        super(FAILURE_MESSAGES[kind]);
+        this.kind = kind;
+        this.path = path;
+        this.within = within;
+    }
+}
+const NO_POLICY = {};
+const OBJECT_PROTOTYPE = Object.prototype;
+const DATE_PROTOTYPE = Date.prototype;
+const dateValueOf = Date.prototype.getTime;
+const decimalValueOf = Decimal.prototype.toString;
+const FAST_WALK_DEPTH = 256;
+const SLOW_WALK = Symbol("slow walk");
+class FastWalkFailure {
+    at;
+    constructor(at) {
+        this.at = at;
+    }
+}
+const HOLE = Symbol("hole");
+function copyValueType(value, prototype) {
+    if (prototype === DATE_PROTOTYPE || value instanceof Date) {
+        return new Date(dateValueOf.call(value));
+    }
+    if (value instanceof Decimal) {
+        return new Decimal(decimalValueOf.call(value));
+    }
+    if (value instanceof Uint8Array) {
+        return new Uint8Array(value);
+    }
+    return undefined;
+}
+function isPlainPrototype(prototype) {
+    return prototype === OBJECT_PROTOTYPE || prototype === null;
+}
+function copyRecordShallow(value, prototype) {
+    const copy = prototype === null
+        ? Object.assign(Object.create(null), value)
+        : { ...value };
+    const symbols = Object.getOwnPropertySymbols(copy);
+    for (let index = 0; index < symbols.length; index += 1) {
+        delete copy[symbols[index]];
+    }
+    return copy;
+}
+function defineKey(record, key, value) {
+    if (key === "__proto__") {
+        Object.defineProperty(record, key, {
+            value,
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    else {
+        record[key] = value;
+    }
+}
+function copyFast(value, depth, policy) {
+    try {
+        return copyFastNode(value, depth, policy);
+    }
+    catch (error) {
+        if (error === SLOW_WALK || error instanceof FastWalkFailure) {
+            throw error;
+        }
+        throw new FastWalkFailure(value);
+    }
+}
+function copyFastNode(value, depth, policy) {
+    if (depth > FAST_WALK_DEPTH) {
+        throw SLOW_WALK;
+    }
+    if (policy.keep?.(value) === true) {
+        return value;
+    }
+    if (policy.mirror?.(value) === true) {
+        return mirrorControlData(value);
+    }
+    if (Array.isArray(value)) {
+        const length = value.length;
+        const copy = [];
+        for (let index = 0; index < length; index += 1) {
+            const entry = value[index];
+            if (entry === undefined && !(index in value)) {
+                throw SLOW_WALK;
+            }
+            copy.push(typeof entry === "object" && entry !== null
+                ? copyFast(entry, depth + 1, policy)
+                : entry);
+        }
+        return copy;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (isPlainPrototype(prototype)) {
+        const copy = copyRecordShallow(value, prototype);
+        for (const key in copy) {
+            const entry = copy[key];
+            if (typeof entry === "object" && entry !== null) {
+                copy[key] = copyFast(entry, depth + 1, policy);
+            }
+        }
+        return copy;
+    }
+    const copied = copyValueType(value, prototype);
+    if (copied === undefined) {
+        throw SLOW_WALK;
+    }
+    return copied;
+}
+function pathOf(link) {
+    const segments = [];
+    for (let current = link; current !== undefined; current = current.parent) {
+        segments.push(current.segment);
+    }
+    return segments.reverse();
+}
+function childLink(parent, segment) {
+    return { parent, segment };
+}
+function readAt(link, read) {
+    try {
+        return read();
+    }
+    catch {
+        throw new CallerDataError("unreadable-value", pathOf(link));
+    }
+}
+function copySlow(value, policy, failedAt) {
+    let root;
+    const ancestors = new Map();
+    const stack = [
+        {
+            kind: "visit",
+            read: () => value,
+            link: undefined,
+            assign: (copy) => {
+                root = copy;
+            },
+        },
+    ];
+    while (stack.length > 0) {
+        const task = stack.pop();
+        if (task.kind === "leave") {
+            if (task.refuse !== false) {
+                throw new CallerDataError("unreadable-value", pathOf(task.refuse));
+            }
+            ancestors.delete(task.container);
+            continue;
+        }
+        const { link } = task;
+        const current = readAt(link, task.read);
+        if (typeof current !== "object" || current === null) {
+            task.assign(current);
+            continue;
+        }
+        if (ancestors.has(current)) {
+            task.assign(ancestors.get(current));
+            continue;
+        }
+        const refuse = current === failedAt ? link : false;
+        const settle = (copy) => {
+            if (refuse !== false) {
+                throw new CallerDataError("unreadable-value", pathOf(refuse));
+            }
+            task.assign(copy);
+        };
+        if (readAt(link, () => policy.keep?.(current)) === true) {
+            settle(current);
+            continue;
+        }
+        if (readAt(link, () => policy.mirror?.(current)) === true) {
+            settle(readAt(link, () => mirrorControlData(current)));
+            continue;
+        }
+        if (readAt(link, () => Array.isArray(current))) {
+            const source = current;
+            const length = readAt(link, () => source.length);
+            const copy = new Array(length);
+            task.assign(copy);
+            ancestors.set(current, copy);
+            stack.push({ kind: "leave", container: current, refuse });
+            for (let index = length - 1; index >= 0; index -= 1) {
+                stack.push({
+                    kind: "visit",
+                    read: () => (index in source ? source[index] : HOLE),
+                    link: childLink(link, index),
+                    assign: (entry) => {
+                        if (entry !== HOLE) {
+                            copy[index] = entry;
+                        }
+                    },
+                });
+            }
+            continue;
+        }
+        const prototype = readAt(link, () => Object.getPrototypeOf(current));
+        if (!isPlainPrototype(prototype)) {
+            const copied = readAt(link, () => copyValueType(current, prototype));
+            if (copied === undefined) {
+                throw new CallerDataError("non-plain-value", pathOf(link));
+            }
+            settle(copied);
+            continue;
+        }
+        const source = current;
+        const copy = prototype === null ? Object.create(null) : {};
+        task.assign(copy);
+        ancestors.set(current, copy);
+        stack.push({ kind: "leave", container: current, refuse });
+        const keys = readAt(link, () => Object.keys(source));
+        for (const key of keys) {
+            defineKey(copy, key, undefined);
+        }
+        for (let index = keys.length - 1; index >= 0; index -= 1) {
+            const key = keys[index];
+            stack.push({
+                kind: "visit",
+                read: () => source[key],
+                link: childLink(link, key),
+                assign: (entry) => {
+                    defineKey(copy, key, entry);
+                },
+            });
+        }
+    }
+    return root;
+}
+const UNREADABLE = (() => {
+    const { proxy, revoke } = Proxy.revocable({}, {});
+    revoke();
+    return proxy;
+})();
+const NON_PLAIN_PROTOTYPE = Object.freeze(Object.create(null));
+function reflectNode(source) {
+    try {
+        const array = Array.isArray(source);
+        const prototype = Object.getPrototypeOf(source);
+        const keys = Reflect.ownKeys(source);
+        const descriptors = [];
+        for (let index = 0; index < keys.length; index += 1) {
+            descriptors.push(Object.getOwnPropertyDescriptor(source, keys[index]) ??
+                {});
+        }
+        return { array, prototype, keys, descriptors };
+    }
+    catch {
+        return undefined;
+    }
+}
+function pathSegment(array, key) {
+    if (array) {
+        const index = Number(key);
+        if (Number.isInteger(index) && index >= 0 && String(index) === key) {
+            return index;
+        }
+    }
+    return key;
+}
+function mirrorControlData(value) {
+    const shape = reflectNode(value);
+    if (shape === undefined) {
+        throw new CallerDataError("unreadable-value", []);
+    }
+    let root;
+    const refuse = (kind, path) => {
+        throw new CallerDataError(kind, path, root);
+    };
+    const mirrors = new Map();
+    const stack = [
+        {
+            source: value,
+            shape,
+            link: undefined,
+            assign: (mirror) => {
+                root = mirror;
+            },
+        },
+    ];
+    while (stack.length > 0) {
+        const { source, shape, link, assign } = stack.pop();
+        const known = mirrors.get(source);
+        if (known !== undefined) {
+            assign(known);
+            continue;
+        }
+        if (!shape.array && !isPlainPrototype(shape.prototype)) {
+            let copied;
+            try {
+                copied = copyValueType(source, shape.prototype);
+            }
+            catch {
+                copied = undefined;
+            }
+            if (copied !== undefined) {
+                mirrors.set(source, copied);
+                assign(copied);
+                continue;
+            }
+        }
+        const plain = shape.array
+            ? shape.prototype === Array.prototype || shape.prototype === null
+            : isPlainPrototype(shape.prototype);
+        const target = shape.array
+            ? []
+            : shape.prototype === null
+                ? Object.create(null)
+                : {};
+        if (!plain) {
+            Object.setPrototypeOf(target, NON_PLAIN_PROTOTYPE);
+        }
+        else if (shape.array && shape.prototype === null) {
+            Object.setPrototypeOf(target, null);
+        }
+        let unreadable;
+        for (let index = 0; index < shape.keys.length; index += 1) {
+            const key = shape.keys[index];
+            const descriptor = shape.descriptors[index];
+            const enumerable = descriptor.enumerable === true;
+            if (shape.array && key === "length") {
+                if (typeof descriptor.value === "number") {
+                    target.length = descriptor.value;
+                }
+                continue;
+            }
+            if (typeof key === "symbol") {
+                Object.defineProperty(target, key, {
+                    value: undefined,
+                    enumerable,
+                    configurable: true,
+                });
+                continue;
+            }
+            if (!("value" in descriptor)) {
+                const at = childLink(link, pathSegment(shape.array, key));
+                Object.defineProperty(target, key, {
+                    get: () => refuse("unreadable-value", pathOf(at)),
+                    enumerable,
+                    configurable: true,
+                });
+                continue;
+            }
+            const store = enumerable &&
+                descriptor.writable === true &&
+                descriptor.configurable === true
+                ? (member) => {
+                    defineKey(target, key, member);
+                }
+                : (member) => {
+                    Object.defineProperty(target, key, {
+                        value: member,
+                        writable: descriptor.writable === true,
+                        enumerable,
+                        configurable: true,
+                    });
+                };
+            const member = descriptor.value;
+            if (typeof member !== "object" || member === null) {
+                store(member);
+                continue;
+            }
+            if (mirrors.has(member)) {
+                store(mirrors.get(member));
+                continue;
+            }
+            const memberLink = childLink(link, pathSegment(shape.array, key));
+            const memberShape = reflectNode(member);
+            if (memberShape === undefined) {
+                store(UNREADABLE);
+                unreadable ??= new Map();
+                unreadable.set(key, memberLink);
+                continue;
+            }
+            store(undefined);
+            stack.push({
+                source: member,
+                shape: memberShape,
+                link: memberLink,
+                assign: store,
+            });
+        }
+        const node = plain && unreadable === undefined
+            ? target
+            : new Proxy(target, {
+                get: (into, key, receiver) => {
+                    if (!plain) {
+                        return refuse("non-plain-value", pathOf(link));
+                    }
+                    const at = typeof key === "string" ? unreadable?.get(key) : undefined;
+                    return at === undefined
+                        ? Reflect.get(into, key, receiver)
+                        : refuse("unreadable-value", pathOf(at));
+                },
+            });
+        mirrors.set(source, node);
+        assign(node);
+    }
+    return root;
+}
+export function locateCallerDataError(error, copy) {
+    const within = error.within;
+    if (within === undefined) {
+        return error;
+    }
+    const at = pathTo(copy, within);
+    return at === undefined
+        ? error
+        : new CallerDataError(error.kind, [...at, ...error.path]);
+}
+function pathTo(copy, target) {
+    const seen = new Set();
+    const stack = [
+        { value: copy, path: [] },
+    ];
+    while (stack.length > 0) {
+        const { value, path } = stack.pop();
+        if (value === target) {
+            return path;
+        }
+        if (typeof value !== "object" ||
+            value === null ||
+            value === UNREADABLE ||
+            seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        const array = Array.isArray(value);
+        for (const key of Object.getOwnPropertyNames(value)) {
+            if (array && key === "length") {
+                continue;
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor !== undefined && "value" in descriptor) {
+                stack.push({
+                    value: descriptor.value,
+                    path: [...path, pathSegment(array, key)],
+                });
+            }
+        }
+    }
+    return undefined;
+}
+function guardNative(operation, onFailure) {
+    try {
+        return operation();
+    }
+    catch (failure) {
+        return onFailure(failure);
+    }
+}
+export function copyCallerData(value, policy = NO_POLICY) {
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    return guardNative(() => copyFast(value, 0, policy), (failure) => copySlow(value, policy, failure instanceof FastWalkFailure ? failure.at : undefined));
+}
+export function callerDataFailureMessage(kind) {
+    return FAILURE_MESSAGES[kind];
+}

package/dist/runtime/caller-data.door.d.ts

@@ -0,0 +1,56 @@
+import type { ValidationIssue } from "../operations/validation-code.js";
+import { CallerDataError, type CallerDataPath, type CallerDataPolicy } from "./caller-data.copier.js";
+import type { FrameworkMisuseEvent, MisuseReporter } from "./misuse-reporter.js";
+/**
+ * Where the arguments an execution entry receives came from.
+ *
+ * - `"caller"`: a server-side caller's own objects — copied at the door.
+ * - `"owned"`: data no caller holds a reference to — a body the protocol decoder
+ *   parsed with `JSON.parse` for this request alone, or a plan the typed runner
+ *   assembled from copies its builders took. It is never copied again.
+ *
+ * Only core's own modules choose `"owned"`: the public `framework.execute` and
+ * `executeTransaction` always pass `"caller"`.
+ */
+export type ArgumentsSource = "caller" | "owned";
+/** The operation identity a misuse event may name, as far as it could be read. */
+export type MisuseIdentity = Omit<FrameworkMisuseEvent, "kind" | "path">;
+/**
+ * The identity of a request the framework holds a copy of, keeping only what is
+ * identity: an origin, a Resource name and a standard operation, each present only
+ * when it is one. Nothing the caller wrote anywhere else is carried.
+ */
+export declare function misuseIdentityOf(request: {
+    readonly origin?: unknown;
+    readonly resource?: unknown;
+    readonly family?: unknown;
+    readonly variant?: unknown;
+}): MisuseIdentity;
+/**
+ * The caller's `V1001` for a refused value at `address` (the door's own spelling of
+ * where the copied value stands), reported once to the misuse hook.
+ */
+export declare function refuseCallerData(error: CallerDataError, address: CallerDataPath, identity: MisuseIdentity, misuse: MisuseReporter): ValidationIssue;
+/**
+ * A door's copy of one caller value, or the failure it met. The door holds it until
+ * its answer is due — a plan answers its steps in order — so the failure is a value
+ * here, not yet a response.
+ */
+export type CallerDataCopy = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly error: CallerDataError;
+};
+/** Copies `value` at a door, keeping {@link copyCallerData}'s refusal as a value. */
+export declare function copyAtDoor(value: unknown, policy?: CallerDataPolicy): CallerDataCopy;
+/**
+ * A request envelope handed to `framework.execute` or `executeTransaction`, copied at
+ * the door: its own members read once (a revoked envelope or a throwing member getter
+ * is refused at `[]` or `[member]`), the `members` named here — the protocol identity,
+ * the transport context — copied whole, and every other member kept as it is for its
+ * own door: the arguments, copied after the availability check, and a plan, which the
+ * plan validator inspects and copies step by step.
+ */
+export declare function copyEnvelopeAtDoor(request: unknown, members: readonly string[]): CallerDataCopy;