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

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

@@ -0,0 +1,470 @@
+import { AvDecimal } from "./decimal.js";
+const FAILURE_MESSAGES = {
+    "unreadable-value": "Value could not be read.",
+    "non-plain-value": "Value must be plain data.",
+};
+export class AvCallerDataError extends Error {
+    kind;
+    path;
+    within;
+    name = "AvCallerDataError";
+    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 = AvDecimal.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 AvDecimal) {
+        return new AvDecimal(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 AvCallerDataError("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 AvCallerDataError("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 AvCallerDataError("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 AvCallerDataError("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 AvCallerDataError("unreadable-value", []);
+    }
+    let root;
+    const refuse = (kind, path) => {
+        throw new AvCallerDataError(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 AvCallerDataError(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 { AvValidationIssue } from "../operations/validation-code.js";
+import { AvCallerDataError, type CallerDataPath, type CallerDataPolicy } from "./caller-data.copier.js";
+import type { AvMisuseEvent, 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<AvMisuseEvent, "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: AvCallerDataError, address: CallerDataPath, identity: MisuseIdentity, misuse: MisuseReporter): AvValidationIssue;
+/**
+ * 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: AvCallerDataError;
+};
+/** 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;

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

@@ -0,0 +1,67 @@
+import { parseOperationIdentity } from "../operations/operation-identity.js";
+import { validationIssue } from "../operations/validation-code.js";
+import { AvCallerDataError, copyCallerData, } from "./caller-data.copier.js";
+export function misuseIdentityOf(request) {
+    const origin = request.origin === "application" ||
+        request.origin === "client" ||
+        request.origin === "agent"
+        ? request.origin
+        : undefined;
+    const identity = typeof request.family === "string" && typeof request.variant === "string"
+        ? parseOperationIdentity(request.family, request.variant)
+        : undefined;
+    return {
+        ...(origin === undefined ? {} : { origin }),
+        ...(typeof request.resource === "string"
+            ? { resource: request.resource }
+            : {}),
+        ...(identity === undefined
+            ? {}
+            : { family: identity.family, variant: identity.variant }),
+    };
+}
+export function refuseCallerData(error, address, identity, misuse) {
+    const path = [...address, ...error.path];
+    misuse({ kind: error.kind, path, ...identity });
+    return validationIssue("V1001", path, error.message);
+}
+export function copyAtDoor(value, policy) {
+    try {
+        return { ok: true, value: copyCallerData(value, policy) };
+    }
+    catch (error) {
+        if (error instanceof AvCallerDataError) {
+            return { ok: false, error };
+        }
+        throw error;
+    }
+}
+export function copyEnvelopeAtDoor(request, members) {
+    const shallow = copyAtDoor(request, {
+        keep: (value) => value !== request,
+    });
+    if (!shallow.ok ||
+        typeof shallow.value !== "object" ||
+        shallow.value === null ||
+        Array.isArray(shallow.value)) {
+        return shallow;
+    }
+    const envelope = shallow.value;
+    for (const member of members) {
+        if (!Object.hasOwn(envelope, member)) {
+            continue;
+        }
+        const copy = copyAtDoor(envelope[member]);
+        if (!copy.ok) {
+            return {
+                ok: false,
+                error: new AvCallerDataError(copy.error.kind, [
+                    member,
+                    ...copy.error.path,
+                ]),
+            };
+        }
+        envelope[member] = copy.value;
+    }
+    return { ok: true, value: envelope };
+}

package/dist/runtime/computed-read-runtime.d.ts

@@ -1,8 +1,9 @@
-import type { FrameworkBehaviorsConfig } from "../config/framework-behaviors-config.js";
-import type { Contract, CoreContract } from "../contracts/contract.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { ResolvedComputeConfig } from "../config/field-compute.resolver.js";
+import type { AvContract, AvContractCore } from "../contracts/contract.js";
+import type { AvComputeContext } from "./field-compute.js";
 import type { OperationExecutionRequest } from "./operation-request.js";
-import type { PipelineContext } from "./pipeline.js";
-type ContextFactory = () => PipelineContext;
+type ContextFactory = () => AvComputeContext;
 export type RelationReadPlan = {
     readonly field: string;
     readonly cardinality: "one" | "many";
@@ -27,10 +28,10 @@ export type PlannedReadOperation = {
  * are never mutated and hidden dependencies are resolved through the Core
  * Contract.
  */
-export declare function planReadOperation(core: CoreContract, active: Contract, behaviors: FrameworkBehaviorsConfig | undefined, request: OperationExecutionRequest, args: unknown): PlannedReadOperation;
+export declare function planReadOperation(core: AvContractCore, model: AvAdapterModel, active: AvContract, compute: ResolvedComputeConfig | undefined, request: OperationExecutionRequest, args: unknown): PlannedReadOperation;
 /**
  * Materialize computed scalar reads and remove internal dependency fields,
  * against `active` — the Contract `planReadOperation` was given as `active`.
  */
-export declare function materializeReadOperation(active: Contract, behaviors: FrameworkBehaviorsConfig | undefined, request: OperationExecutionRequest, plan: PlannedReadOperation, value: unknown, contextFactory: ContextFactory): Promise<unknown>;
+export declare function materializeReadOperation(active: AvContract, compute: ResolvedComputeConfig | undefined, request: OperationExecutionRequest, plan: PlannedReadOperation, value: unknown, contextFactory: ContextFactory): Promise<unknown>;
 export {};