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

package/dist/runtime/readonly-value.js

@@ -0,0 +1,141 @@
+import { AvDecimal } from "./decimal.js";
+function isContainer(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return true;
+    }
+    if (value instanceof AvDecimal) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const DEEP_FROZEN = new WeakSet();
+export function deepFreeze(value) {
+    if (!isContainer(value) || DEEP_FROZEN.has(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    DEEP_FROZEN.add(value);
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor !== undefined && "value" in descriptor) {
+            deepFreeze(descriptor.value);
+        }
+    }
+    return value;
+}
+function scalarCopy(value) {
+    if (value instanceof Date) {
+        return new Date(value.getTime());
+    }
+    if (value instanceof Uint8Array) {
+        return value.slice();
+    }
+    return undefined;
+}
+export function frozenCopy(value) {
+    const copies = new Map();
+    const copy = (current) => {
+        const scalar = scalarCopy(current);
+        if (scalar !== undefined) {
+            return scalar;
+        }
+        if (!isContainer(current)) {
+            return current;
+        }
+        if (copies.has(current)) {
+            return copies.get(current);
+        }
+        copies.set(current, current);
+        const entries = [];
+        let changed = !DEEP_FROZEN.has(current);
+        for (const key of Reflect.ownKeys(current)) {
+            const descriptor = Object.getOwnPropertyDescriptor(current, key);
+            if (descriptor === undefined ||
+                !("value" in descriptor) ||
+                (Array.isArray(current) && key === "length")) {
+                continue;
+            }
+            const next = copy(descriptor.value);
+            changed ||= next !== descriptor.value;
+            entries.push([key, descriptor, next]);
+        }
+        if (!changed) {
+            copies.set(current, current);
+            return current;
+        }
+        const target = Array.isArray(current)
+            ? new Array(current.length)
+            : Object.create(Object.getPrototypeOf(current));
+        for (const [key, descriptor, next] of entries) {
+            Object.defineProperty(target, key, {
+                value: next,
+                enumerable: descriptor.enumerable ?? false,
+                writable: true,
+                configurable: true,
+            });
+        }
+        const frozen = deepFreeze(target);
+        copies.set(current, frozen);
+        return frozen;
+    };
+    return copy(value);
+}
+function readOnlyWrite(subject) {
+    return new TypeError(`${subject} is read-only here.`);
+}
+const VIEWS = new WeakMap();
+export function readonlyView(value, subject) {
+    if (!isContainer(value)) {
+        return value;
+    }
+    const known = VIEWS.get(value);
+    if (known !== undefined) {
+        return known;
+    }
+    const real = value;
+    const standIn = Array.isArray(value)
+        ? []
+        : Object.create(Object.getPrototypeOf(value));
+    const refuse = () => {
+        throw readOnlyWrite(subject);
+    };
+    const view = new Proxy(standIn, {
+        get: (_target, key) => readonlyView(real[key], subject),
+        has: (_target, key) => key in real,
+        ownKeys: () => Reflect.ownKeys(real),
+        getOwnPropertyDescriptor: (target, key) => {
+            const descriptor = Reflect.getOwnPropertyDescriptor(real, key);
+            if (descriptor === undefined) {
+                return undefined;
+            }
+            if (Reflect.getOwnPropertyDescriptor(target, key)?.configurable === false) {
+                return {
+                    value: descriptor.value,
+                    enumerable: false,
+                    writable: true,
+                    configurable: false,
+                };
+            }
+            return "value" in descriptor
+                ? {
+                    value: readonlyView(descriptor.value, subject),
+                    enumerable: descriptor.enumerable ?? false,
+                    writable: false,
+                    configurable: true,
+                }
+                : { ...descriptor, configurable: true };
+        },
+        getPrototypeOf: () => Object.getPrototypeOf(real),
+        set: refuse,
+        defineProperty: refuse,
+        deleteProperty: refuse,
+        setPrototypeOf: refuse,
+        preventExtensions: refuse,
+    });
+    VIEWS.set(value, view);
+    return view;
+}

package/dist/runtime/referential-action.d.ts

@@ -23,6 +23,13 @@ export type ReferentialEdge = {
     readonly field: string;
     /** The Resource the edge points AT — the one whose deletion fires `onDelete`. */
     readonly target: string;
+    /**
+     * The scalar fields of the ENCLOSING Resource that hold the reference, in the
+     * order the store pairs them with the `target`'s key. A record that writes the
+     * relation `field` and any of these names the reference twice and is refused;
+     * a required relation may be written through all of them instead.
+     */
+    readonly references: readonly string[];
     /** What deleting a `target` row does to rows of the ENCLOSING Resource. */
     readonly onDelete: ReferentialDeleteEffect;
 };

package/dist/runtime/request-envelope.validator.d.ts

@@ -0,0 +1,5 @@
+import type { AvValidationIssue } from "../operations/validation-code.js";
+/** The issues of one malformed operation request envelope; empty when well formed. */
+export declare function validateOperationEnvelope(request: unknown): readonly AvValidationIssue[];
+/** The issues of one malformed transaction request envelope; empty when well formed. */
+export declare function validateTransactionEnvelope(request: unknown): readonly AvValidationIssue[];

package/dist/runtime/request-envelope.validator.js

@@ -0,0 +1,123 @@
+const ORIGINS = ["application", "client", "agent"];
+const OPERATION_IDENTITY_MEMBERS = ["resource", "family", "variant"];
+export function validateOperationEnvelope(request) {
+    if (!isRecord(request)) {
+        return [issue([], "V1001", "Operation request must be an object.")];
+    }
+    const issues = [...originAndIdentityIssues(request)];
+    for (const member of OPERATION_IDENTITY_MEMBERS) {
+        const failure = requiredStringIssue(request, member);
+        if (failure !== undefined) {
+            issues.push(failure);
+        }
+    }
+    return issues;
+}
+export function validateTransactionEnvelope(request) {
+    if (!isRecord(request)) {
+        return [issue([], "V1001", "Transaction request must be an object.")];
+    }
+    return originAndIdentityIssues(request);
+}
+function originAndIdentityIssues(request) {
+    const issues = [];
+    const origin = request.origin;
+    if (origin === undefined) {
+        issues.push(issue(["origin"], "V1000", 'Required property "origin" is missing.'));
+    }
+    else if (typeof origin !== "string") {
+        issues.push(issue(["origin"], "V1001", "Request origin must be a string."));
+    }
+    else if (!ORIGINS.includes(origin)) {
+        issues.push(issue(["origin"], "V1002", 'Request origin must be "application", "client" or "agent".'));
+    }
+    const requestId = request.requestId;
+    if (requestId === undefined || requestId === "") {
+        issues.push(issue(["requestId"], "V1000", 'Required property "requestId" is missing or empty.'));
+    }
+    else if (typeof requestId !== "string") {
+        issues.push(issue(["requestId"], "V1001", "Request id must be a string."));
+    }
+    const state = request.state;
+    if (state !== undefined &&
+        (typeof state !== "object" || state === null || Array.isArray(state))) {
+        issues.push(issue(["state"], "V1001", "Request state must be an object."));
+    }
+    if (origin === "client" || origin === "agent") {
+        issues.push(...protocolIssues(request.protocol, origin));
+        if (request.transport !== undefined) {
+            issues.push(...transportIssues(request.transport));
+        }
+    }
+    else if (origin === "application") {
+        for (const member of ["protocol", "transport"]) {
+            if (request[member] !== undefined) {
+                issues.push(issue([member], "V1005", `Property "${member}" belongs to a client or agent request, not an application one.`));
+            }
+        }
+    }
+    return issues;
+}
+function protocolIssues(protocol, origin) {
+    if (protocol === undefined) {
+        return [
+            issue(["protocol"], "V1000", `Required property "protocol" is missing from ${origin === "client" ? "a client" : "an agent"} request.`),
+        ];
+    }
+    if (!isRecord(protocol)) {
+        return [
+            issue(["protocol"], "V1001", "Protocol identity must be an object."),
+        ];
+    }
+    const issues = [];
+    if (protocol.version === undefined) {
+        issues.push(issue(["protocol", "version"], "V1000", 'Required property "version" is missing.'));
+    }
+    else if (!Number.isInteger(protocol.version)) {
+        issues.push(issue(["protocol", "version"], "V1001", "Protocol version must be an integer."));
+    }
+    if (protocol.hash === undefined) {
+        issues.push(issue(["protocol", "hash"], "V1000", 'Required property "hash" is missing.'));
+    }
+    else if (typeof protocol.hash !== "string") {
+        issues.push(issue(["protocol", "hash"], "V1001", "Protocol hash must be a string."));
+    }
+    return issues;
+}
+function transportIssues(transport) {
+    if (!isRecord(transport)) {
+        return [
+            issue(["transport"], "V1001", "Transport metadata must be an object."),
+        ];
+    }
+    const issues = [];
+    if (transport.method !== "POST") {
+        issues.push(issue(["transport", "method"], "V1001", 'Transport method must be "POST".'));
+    }
+    const headers = transport.headers;
+    if (!isRecord(headers)) {
+        issues.push(issue(["transport", "headers"], "V1001", "Transport headers must be an object."));
+        return issues;
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        if (typeof value !== "string") {
+            issues.push(issue(["transport", "headers", name], "V1001", "A transport header value must be a string."));
+        }
+    }
+    return issues;
+}
+function requiredStringIssue(request, member) {
+    const value = request[member];
+    if (value === undefined) {
+        return issue([member], "V1000", `Required property "${member}" is missing.`);
+    }
+    return typeof value === "string"
+        ? undefined
+        : issue([member], "V1001", `Property "${member}" must be a string.`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function issue(path, code, message) {
+    return { path, code, message };
+}

package/dist/runtime/request-id.d.ts

@@ -1,6 +1,6 @@
 /**
  * The request id of one call or transaction run: the caller's
- * `ExecutionOptions.requestId` when it is a non-empty string, otherwise a new
+ * `AvExecutionOptions.requestId` when it is a non-empty string, otherwise a new
  * one. Any other value is ignored.
  */
 export declare function requestIdOf(options: unknown): string;

package/dist/runtime/request-state.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The per-request state every stage reads and writes as `ctx.$state`. Empty
+ * until the application declares its members by module augmentation:
+ *
+ * ```ts
+ * declare module "@aventara/core" {
+ *   interface AvState {
+ *     user?: { id: string; roles: string[] };
+ *   }
+ * }
+ * ```
+ */
+export interface AvState {
+}

package/dist/runtime/request-state.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/request-state.resolver.d.ts

@@ -0,0 +1,12 @@
+import type { AvState } from "./request-state.js";
+/**
+ * The state of one request: the seed when it is an object, otherwise a fresh
+ * `{}`. A seed that is not an object is ignored, as an unusable request id is.
+ */
+export declare function requestStateOf(seed: unknown): AvState;
+/**
+ * The state an in-process call's `AvExecutionOptions` seeds, or `undefined`.
+ * Read as `unknown`, like the request id: a façade is total for untyped
+ * callers, so a getter that throws or a value that is not an object is ignored.
+ */
+export declare function stateOptionOf(options: unknown): AvState | undefined;

package/dist/runtime/request-state.resolver.js

@@ -0,0 +1,20 @@
+export function requestStateOf(seed) {
+    return typeof seed === "object" && seed !== null && !Array.isArray(seed)
+        ? seed
+        : {};
+}
+export function stateOptionOf(options) {
+    if (typeof options !== "object" || options === null) {
+        return undefined;
+    }
+    let state;
+    try {
+        state = options.state;
+    }
+    catch {
+        return undefined;
+    }
+    return typeof state === "object" && state !== null && !Array.isArray(state)
+        ? state
+        : undefined;
+}

package/dist/runtime/scalar-runtime.d.ts

@@ -1,55 +1,98 @@
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { Contract } from "../contracts/contract.js";
-import type { ScalarField } from "../contracts/field.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvScalarFilterOperator } from "../contracts/capability.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { OperationValidationOptions, SemanticOperationArguments } from "../operations/operation-validator.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import { type TransactionSlotShape } from "../transactions/transaction-reference.js";
 export type ScalarNormalizationResult = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
 } | {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
 export type ScalarValueNormalizationResult = {
     readonly ok: true;
     readonly value: unknown;
 } | {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
 type Path = readonly (string | number)[];
 /**
  * The one discriminant between an argument OBJECT and a VALUE wherever a position
  * admits both — a filter position above all: a **plain** record is an operator object,
- * and anything else — a `Date`, a core `Decimal`, a `Uint8Array` — is a value, which
+ * and anything else — a `Date`, a core `AvDecimal`, a `Uint8Array` — is a value, which
  * equality shorthand then holds to the field's scalar. The validator (`operation-
  * validator-core.ts`) reads a filter position through this same answer, and an
  * adapter's filter translation is expected to, so a position cannot be operators to
  * one reader and a value to another.
  */
 export declare function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown>>;
+/**
+ * An operation argument's JSON value is bounded by `maxJsonDepth`, which the
+ * structural walk enforces before this runs; a `$sql` step's parameter is not
+ * bounded by it. The traversal therefore carries its own stack on the heap: a
+ * payload deep enough to exhaust the call stack must still normalize rather
+ * than become an internal failure.
+ *
+ * `seen` holds the ancestors of the value being visited, so a repeated
+ * sibling reference is legal and only a genuine cycle is rejected.
+ *
+ * Every node it emits is typed {@link AvJsonValue}, so the public type and what
+ * this traversal produces are one fact: a branch that emitted anything else
+ * would not compile.
+ */
+export declare function normalizeJsonValue(value: unknown, path: Path, seen: Set<object>): ScalarValueNormalizationResult;
 /**
  * Normalizes one field value to Aventara's provider-neutral runtime form.
  * `runtime` is used for framework-produced values regardless of request origin.
  */
-export declare function normalizeScalarFieldValue(contract: Contract, field: ScalarField<Contract>, value: unknown, scope: RequestOrigin | "runtime", path: Path): ScalarValueNormalizationResult;
+export declare function normalizeScalarFieldValue(contract: AvContract, field: AvScalarField<AvContract>, value: unknown, origin: AvRequestOrigin | "runtime", path: Path): ScalarValueNormalizationResult;
+/**
+ * Every way a normalized value written to `field` does not conform to the field's
+ * Json Shape, each at its full path; none for an unshaped field or a `null`.
+ * `position` says whether `value` is the field's whole value or one entry of a
+ * list field (a `$push` operand).
+ *
+ * @throws Error when the field carries a shape no checker is bound to — a Contract
+ *   the Framework did not compile.
+ */
+export declare function jsonShapeIssues(field: AvScalarField<AvContract>, value: unknown, path: Path, position?: "value" | "entry"): readonly AvValidationIssue[];
 /**
  * Copies one validated runtime value of a scalar field into a value the framework
  * owns, per scalar codec: `datetime` → a new `Date`, `bytes` → a sliced `Uint8Array`,
  * `json` → a structured deep copy, and a list → a new array of copied items. `decimal`
  * keeps its identity, and strings, numbers, booleans, bigints, enum members and `null`
  * are immutable and returned unchanged. {@link SCALAR_ATOM_COPIERS} is exhaustive over
- * {@link BuiltInScalar}, so a new codec cannot reach this function without declaring
+ * {@link AvBuiltInScalar}, so a new codec cannot reach this function without declaring
  * its copy.
  */
-export declare function copyScalarFieldValue(field: ScalarField<Contract>, value: unknown): unknown;
+export declare function copyScalarFieldValue(field: AvScalarField<AvContract>, value: unknown): unknown;
+/**
+ * The operators of a step's own filter whose operand is a reference position, and
+ * the shape each holds — the one table the normalization below and the reference
+ * collector (`transaction-reference-collector.ts`) both read. `not` also takes a
+ * nested operator object. Not here, so never a reference: `mode`, `isEmpty`, `path`
+ * and a `json` field's `string*`/`array*` operators, which take no field value.
+ */
+export declare const REFERENCE_OPERANDS: Readonly<Partial<Record<AvScalarFilterOperator, TransactionSlotShape>>>;
+/** The shape of `operator`'s operand when it is a reference position. */
+export declare function referenceOperandShape(operator: string): TransactionSlotShape | undefined;
+/**
+ * Where a normalization writes: `"copy"` leaves the arguments it reads untouched,
+ * `"in-place"` writes into them — only for arguments the framework owns and reads
+ * nowhere else afterwards: a door's copy, or a body the protocol decoder parsed.
+ */
+export type NormalizationWrite = "copy" | "in-place";
 /**
  * Normalizes every scalar leaf in one structurally valid standard operation.
  * Client wire values are decoded; application values are validated in runtime form.
  */
-export declare function normalizeOperationScalarValues(contract: Contract, request: OperationIdentity & {
+export declare function normalizeOperationScalarValues(contract: AvContract, request: AvOperationIdentity & {
     readonly resource: string;
     readonly arguments: SemanticOperationArguments;
-}, scope: RequestOrigin, options?: OperationValidationOptions): ScalarNormalizationResult;
+}, origin: AvRequestOrigin, options?: OperationValidationOptions, write?: NormalizationWrite): ScalarNormalizationResult;
 export {};