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

package/dist/runtime/field-check.evaluator.js

@@ -0,0 +1,521 @@
+export const FIELD_CHECK_SUBJECTS = {
+    string: "string",
+    int: "number",
+    float: "number",
+    bigint: "bigint",
+    decimal: "decimal",
+    datetime: "datetime",
+    bytes: "bytes",
+};
+const DATE_SOURCE = "(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))";
+const HHMM = "(?:[01]\\d|2[0-3]):[0-5]\\d";
+const IPV6_ALPHABET = /^[0-9a-fA-F:.]+$/;
+const CREDIT_CARD = /^\d(?:[ -]?\d){11,18}$/;
+const IBAN = /^[A-Z]{2}(?!00|01|99)\d{2}[A-Z0-9]{11,30}$/;
+const FORMAT_PATTERNS = {
+    email: /^(?:[A-Za-z0-9_'+-]+\.)*[A-Za-z0-9_'+-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9-]*\.)+[A-Za-z]{2,}$/,
+    emoji: new RegExp("^(?=[\\s\\S]*[\\p{Extended_Pictographic}\\p{Regional_Indicator}\\u20E3])[\\p{Extended_Pictographic}\\p{Emoji_Component}]+$", "u"),
+    uuid: /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/,
+    guid: /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/,
+    nanoid: /^[a-zA-Z0-9_-]{21}$/,
+    cuid: /^[cC][0-9a-z]{6,}$/,
+    cuid2: /^[0-9a-z]+$/,
+    ulid: /^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$/,
+    xid: /^[0-9a-vA-V]{20}$/,
+    ksuid: /^[A-Za-z0-9]{27}$/,
+    datetime: new RegExp(`^${DATE_SOURCE}T(?:${HHMM}:[0-5]\\d(?:\\.\\d+)?(?:Z))$`),
+    date: new RegExp(`^${DATE_SOURCE}$`),
+    time: new RegExp(`^${HHMM}(?::[0-5]\\d(?:\\.\\d+)?)?$`),
+    duration: /^P(?:(\d+W)|(?!.*W)(?=\d|T\d)(\d+Y)?(\d+M)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+([.,]\d+)?S)?)?)$/,
+    ipv4: /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$/,
+    cidrv4: /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/,
+    e164: /^\+[1-9]\d{6,14}$/,
+};
+const platform = globalThis;
+function canParseUrl(input) {
+    const Url = platform.URL;
+    if (Url === undefined) {
+        return false;
+    }
+    try {
+        if (typeof Url.canParse === "function") {
+            return Url.canParse(input);
+        }
+        new Url(input);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function decodeBase64(value) {
+    if (platform.atob === undefined) {
+        throw new TypeError("No atob is available here.");
+    }
+    return platform.atob(value);
+}
+function isIpv6(value) {
+    return IPV6_ALPHABET.test(value) && canParseUrl(`http://[${value}]`);
+}
+function isCidrv6(value) {
+    const parts = value.split("/");
+    if (parts.length !== 2) {
+        return false;
+    }
+    const [address, prefix] = parts;
+    const bits = Number(prefix);
+    return (prefix !== "" &&
+        `${bits}` === prefix &&
+        bits >= 0 &&
+        bits <= 128 &&
+        isIpv6(address));
+}
+function isBase64(value) {
+    if (value === "") {
+        return true;
+    }
+    if (/\s/.test(value) || value.length % 4 !== 0) {
+        return false;
+    }
+    try {
+        decodeBase64(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isBase64Url(value) {
+    if (!/^[A-Za-z0-9_-]*$/.test(value)) {
+        return false;
+    }
+    const base64 = value.replace(/[-_]/g, (char) => (char === "-" ? "+" : "/"));
+    return isBase64(base64.padEnd(Math.ceil(base64.length / 4) * 4, "="));
+}
+function isLuhn(digits) {
+    let length = digits.length;
+    let bit = 1;
+    let sum = 0;
+    while (length) {
+        const value = digits.charCodeAt(--length) - 48;
+        bit ^= 1;
+        sum += bit ? ([0, 2, 4, 6, 8, 1, 3, 5, 7, 9][value] ?? 0) : value;
+    }
+    return sum % 10 === 0;
+}
+function isIbanChecksum(iban) {
+    let remainder = 0;
+    const step = (code) => {
+        remainder =
+            (code >= 65
+                ? remainder * 100 + (code - 55)
+                : remainder * 10 + (code - 48)) % 97;
+    };
+    for (let index = 4; index < iban.length; index += 1) {
+        step(iban.charCodeAt(index));
+    }
+    for (let index = 0; index < 4; index += 1) {
+        step(iban.charCodeAt(index));
+    }
+    return remainder === 1;
+}
+function isJwt(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 3 || !parts[0]) {
+            return false;
+        }
+        const header = JSON.parse(decodeBase64(parts[0]));
+        if ("typ" in header && header.typ !== "JWT") {
+            return false;
+        }
+        return Boolean(header.alg);
+    }
+    catch {
+        return false;
+    }
+}
+function isJsonString(value) {
+    try {
+        JSON.parse(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function matchesFormat(format, value) {
+    switch (format) {
+        case "url":
+            return canParseUrl(value.trim());
+        case "ipv6":
+            return isIpv6(value);
+        case "cidrv6":
+            return isCidrv6(value);
+        case "base64":
+            return isBase64(value);
+        case "base64url":
+            return isBase64Url(value);
+        case "credit_card":
+            return CREDIT_CARD.test(value) && isLuhn(value.replace(/[- ]/g, ""));
+        case "iban":
+            return IBAN.test(value) && isIbanChecksum(value);
+        case "jwt":
+            return isJwt(value);
+        case "json_string":
+            return isJsonString(value);
+        default: {
+            return FORMAT_PATTERNS[format]?.test(value) === true;
+        }
+    }
+}
+const DECIMAL = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/;
+function decimalParts(text) {
+    const match = DECIMAL.exec(text);
+    if (match === null) {
+        return undefined;
+    }
+    const [, sign, whole = "", fraction = "", power = "0"] = match;
+    const all = `${whole}${fraction}`;
+    const leading = all.length - all.replace(/^0+/, "").length;
+    const digits = all.slice(leading).replace(/0+$/, "");
+    if (digits === "") {
+        return { negative: false, digits: "", exponent: 0 };
+    }
+    return {
+        negative: sign === "-",
+        digits,
+        exponent: whole.length - 1 - leading + Number(power),
+    };
+}
+function compareDecimals(a, b) {
+    const signOf = (parts) => parts.digits === "" ? 0 : parts.negative ? -1 : 1;
+    if (signOf(a) !== signOf(b)) {
+        return Math.sign(signOf(a) - signOf(b));
+    }
+    if (signOf(a) === 0) {
+        return 0;
+    }
+    let magnitude = 0;
+    if (a.exponent !== b.exponent) {
+        magnitude = a.exponent > b.exponent ? 1 : -1;
+    }
+    else {
+        const width = Math.max(a.digits.length, b.digits.length);
+        const left = a.digits.padEnd(width, "0");
+        const right = b.digits.padEnd(width, "0");
+        magnitude = left === right ? 0 : left > right ? 1 : -1;
+    }
+    return a.negative ? -magnitude : magnitude;
+}
+function modPow(base, power, modulus) {
+    let result = BigInt(1) % modulus;
+    let factor = base % modulus;
+    let remaining = power;
+    while (remaining > 0) {
+        if (remaining % 2 === 1) {
+            result = (result * factor) % modulus;
+        }
+        factor = (factor * factor) % modulus;
+        remaining = Math.floor(remaining / 2);
+    }
+    return result;
+}
+function isDecimalMultiple(a, b) {
+    if (b.digits === "") {
+        return false;
+    }
+    if (a.digits === "") {
+        return true;
+    }
+    const scaleA = a.exponent - (a.digits.length - 1);
+    const scaleB = b.exponent - (b.digits.length - 1);
+    if (!Number.isSafeInteger(scaleA) || !Number.isSafeInteger(scaleB)) {
+        return false;
+    }
+    const mantissaA = BigInt(a.digits);
+    const mantissaB = BigInt(b.digits);
+    if (scaleA >= scaleB) {
+        return (((mantissaA % mantissaB) *
+            modPow(BigInt(10), scaleA - scaleB, mantissaB)) %
+            mantissaB ===
+            BigInt(0));
+    }
+    return false;
+}
+function floatRemainder(value, step) {
+    const ratio = value / step;
+    const rounded = Math.round(ratio);
+    const tolerance = 4 * Number.EPSILON * Math.max(Math.abs(ratio), 1);
+    return Math.abs(ratio - rounded) < tolerance ? 0 : ratio - rounded;
+}
+function codePoints(value) {
+    let count = value.length;
+    for (let index = 0; index < value.length - 1; index += 1) {
+        if ((value.charCodeAt(index) & 0xfc00) === 0xd800 &&
+            (value.charCodeAt(index + 1) & 0xfc00) === 0xdc00) {
+            count -= 1;
+            index += 1;
+        }
+    }
+    return count;
+}
+const patterns = new WeakMap();
+function patternOf(check) {
+    let pattern = patterns.get(check);
+    if (pattern === undefined) {
+        pattern = new RegExp(check.pattern.source, check.pattern.flags);
+        patterns.set(check, pattern);
+    }
+    pattern.lastIndex = 0;
+    return pattern;
+}
+function passesFormat(check, value) {
+    switch (check.format) {
+        case "regex":
+            return patternOf(check).test(value);
+        case "includes":
+            return value.includes(check.includes);
+        case "starts_with":
+            return value.startsWith(check.prefix);
+        case "ends_with":
+            return value.endsWith(check.suffix);
+        case "lowercase":
+            return /^[^A-Z]*$/.test(value);
+        case "uppercase":
+            return /^[^a-z]*$/.test(value);
+        default:
+            return matchesFormat(check.format, value);
+    }
+}
+function compareToBound(value, bound, subject) {
+    switch (subject) {
+        case "number":
+            return typeof value === "number" && typeof bound === "number"
+                ? Math.sign(value - bound)
+                : undefined;
+        case "bigint": {
+            if (typeof value !== "bigint") {
+                return undefined;
+            }
+            const limit = BigInt(bound);
+            return value === limit ? 0 : value > limit ? 1 : -1;
+        }
+        case "decimal": {
+            const left = decimalParts(String(value));
+            const right = decimalParts(String(bound));
+            return left === undefined || right === undefined
+                ? undefined
+                : compareDecimals(left, right);
+        }
+        case "datetime":
+            return value instanceof Date
+                ? Math.sign(value.getTime() - Date.parse(String(bound)))
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+function isMultiple(value, step, subject) {
+    switch (subject) {
+        case "number":
+            return typeof value === "number" && typeof step === "number"
+                ? floatRemainder(value, step) === 0
+                : undefined;
+        case "bigint": {
+            if (typeof value !== "bigint") {
+                return undefined;
+            }
+            const divisor = BigInt(step);
+            return divisor !== BigInt(0) && value % divisor === BigInt(0);
+        }
+        case "decimal": {
+            const left = decimalParts(String(value));
+            const right = decimalParts(String(step));
+            return left === undefined || right === undefined
+                ? undefined
+                : isDecimalMultiple(left, right);
+        }
+        default:
+            return undefined;
+    }
+}
+export function passesFieldCheck(check, value, subject) {
+    switch (check.check) {
+        case "less_than":
+        case "greater_than": {
+            const order = compareToBound(value, check.value, subject);
+            if (order === undefined) {
+                return true;
+            }
+            const signed = check.check === "less_than" ? -order : order;
+            return signed > 0 || (check.inclusive && signed === 0);
+        }
+        case "multiple_of":
+            return isMultiple(value, check.value, subject) ?? true;
+        case "max_length":
+        case "min_length":
+        case "length_equals": {
+            const length = Array.isArray(value)
+                ? value.length
+                : typeof value === "string"
+                    ? codePoints(value)
+                    : undefined;
+            if (length === undefined) {
+                return true;
+            }
+            return check.check === "max_length"
+                ? length <= check.maximum
+                : check.check === "min_length"
+                    ? length >= check.minimum
+                    : length === check.length;
+        }
+        case "string_format":
+            return typeof value === "string" ? passesFormat(check, value) : true;
+        case "max_size":
+        case "min_size":
+        case "size_equals": {
+            if (!(value instanceof Uint8Array)) {
+                return true;
+            }
+            const size = value.byteLength;
+            return check.check === "max_size"
+                ? size <= check.maximum
+                : check.check === "min_size"
+                    ? size >= check.minimum
+                    : size === check.size;
+        }
+    }
+}
+const FORMAT_LABELS = {
+    email: "an email address",
+    url: "a URL",
+    emoji: "emoji",
+    uuid: "a UUID",
+    guid: "a GUID",
+    nanoid: "a Nano ID",
+    cuid: "a CUID",
+    cuid2: "a CUID2",
+    ulid: "a ULID",
+    xid: "an XID",
+    ksuid: "a KSUID",
+    datetime: "an ISO 8601 date-time in UTC",
+    date: "an ISO 8601 date",
+    time: "an ISO 8601 time",
+    duration: "an ISO 8601 duration",
+    ipv4: "an IPv4 address",
+    ipv6: "an IPv6 address",
+    cidrv4: "an IPv4 CIDR block",
+    cidrv6: "an IPv6 CIDR block",
+    base64: "base64",
+    base64url: "base64url",
+    json_string: "a JSON string",
+    e164: "an E.164 phone number",
+    credit_card: "a credit card number",
+    iban: "an IBAN",
+    jwt: "a JWT",
+};
+function plural(count, one, many) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+function formatMessage(check) {
+    switch (check.format) {
+        case "regex":
+            return `Value must match the pattern /${check.pattern.source}/${check.pattern.flags}.`;
+        case "includes":
+            return `Value must include ${JSON.stringify(check.includes)}.`;
+        case "starts_with":
+            return `Value must start with ${JSON.stringify(check.prefix)}.`;
+        case "ends_with":
+            return `Value must end with ${JSON.stringify(check.suffix)}.`;
+        case "lowercase":
+            return "Value must be lowercase.";
+        case "uppercase":
+            return "Value must be uppercase.";
+        default:
+            return `Value must be ${FORMAT_LABELS[check.format]}.`;
+    }
+}
+function boundMessage(check, subject) {
+    const bound = String(check.value);
+    if (subject === "datetime") {
+        return check.check === "less_than"
+            ? `Value must be ${check.inclusive ? "on or before" : "before"} ${bound}.`
+            : `Value must be ${check.inclusive ? "on or after" : "after"} ${bound}.`;
+    }
+    return check.check === "less_than"
+        ? `Value must be ${check.inclusive ? "at most" : "less than"} ${bound}.`
+        : `Value must be ${check.inclusive ? "at least" : "greater than"} ${bound}.`;
+}
+function messageOf(check, subject) {
+    switch (check.check) {
+        case "less_than":
+        case "greater_than":
+            return boundMessage(check, subject);
+        case "multiple_of":
+            return `Value must be a multiple of ${check.value}.`;
+        case "max_length":
+            return check.list === true
+                ? `List must have at most ${plural(check.maximum, "entry", "entries")}.`
+                : `Value must be at most ${plural(check.maximum, "character", "characters")} long.`;
+        case "min_length":
+            return check.list === true
+                ? `List must have at least ${plural(check.minimum, "entry", "entries")}.`
+                : `Value must be at least ${plural(check.minimum, "character", "characters")} long.`;
+        case "length_equals":
+            return `Value must be exactly ${plural(check.length, "character", "characters")} long.`;
+        case "string_format":
+            return formatMessage(check);
+        case "max_size":
+            return `Value must be at most ${plural(check.maximum, "byte", "bytes")}.`;
+        case "min_size":
+            return `Value must be at least ${plural(check.minimum, "byte", "bytes")}.`;
+        case "size_equals":
+            return `Value must be exactly ${plural(check.size, "byte", "bytes")}.`;
+    }
+}
+export function fieldCheckIssue(check, subject, path) {
+    const { check: name, ...params } = check;
+    const code = name === "string_format" ? "V1003" : "V1004";
+    return {
+        code,
+        path,
+        message: messageOf(check, subject),
+        check: name,
+        params,
+    };
+}
+export function fieldCheckIssues(checks, value, subject, path, list) {
+    if (checks.length === 0 || value === null || value === undefined) {
+        return [];
+    }
+    const issues = [];
+    if (list && Array.isArray(value)) {
+        for (const check of checks) {
+            if (isListCheck(check) && !passesFieldCheck(check, value, subject)) {
+                issues.push(fieldCheckIssue(check, subject, path));
+            }
+        }
+        for (const [index, entry] of value.entries()) {
+            issues.push(...entryCheckIssues(checks, entry, subject, [...path, index]));
+        }
+        return issues;
+    }
+    return entryCheckIssues(checks, value, subject, path);
+}
+export function entryCheckIssues(checks, value, subject, path) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    const issues = [];
+    for (const check of checks) {
+        if (!isListCheck(check) && !passesFieldCheck(check, value, subject)) {
+            issues.push(fieldCheckIssue(check, subject, path));
+        }
+    }
+    return issues;
+}
+function isListCheck(check) {
+    return ((check.check === "max_length" || check.check === "min_length") &&
+        check.list === true);
+}

package/dist/runtime/field-compute.d.ts

@@ -0,0 +1,65 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterFieldKey } from "../adapters/adapter-resource.js";
+import type { AvConfigAny } from "../config/any-framework-config.js";
+import type { AvEffectiveFieldKey } from "../config/effective-fields.js";
+import type { AvConfigResourceKey } from "../config/framework-field-definition.js";
+import type { AvComputeReads } from "../framework/operation-facade.js";
+import type { AvContext } from "./pipeline.js";
+import type { AvDeepReadonly } from "./readonly-value.js";
+import type { AvState } from "./request-state.js";
+/**
+ * The ctx a compute stage is told: the operation's `$` facts, a read-only view
+ * of the request's `$state`, and reads only (`ctx.<Resource>.find.<variant>(args)`,
+ * `find.count` included).
+ */
+export type AvComputeContext<M extends AvAdapterModel = AvAdapterModel> = AvComputeReads<M> & Pick<AvContext<M>, "$operation" | "$args" | "$origin" | "$requestId" | "$transport" | "$contract"> & {
+    /** The request's state, read-only: a write throws a `TypeError`. */
+    readonly $state: AvDeepReadonly<AvState>;
+};
+/**
+ * Computes a field's value when a row is created, whether or not the caller sent
+ * it. It receives the incoming `data` and returns the value to store; returning
+ * `undefined` keeps the current value.
+ */
+export type AvComputeCreate<M extends AvAdapterModel = AvAdapterModel> = (context: {
+    readonly field: string;
+    readonly value: unknown;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly ctx: AvComputeContext<M>;
+}) => unknown | Promise<unknown>;
+/**
+ * Computes a field's value when a row is updated, whether or not the caller sent
+ * it. It receives the incoming `data` and returns the value to store; returning
+ * `undefined` keeps the current value.
+ */
+export type AvComputeUpdate<M extends AvAdapterModel = AvAdapterModel> = (context: {
+    readonly field: string;
+    readonly value: unknown;
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly ctx: AvComputeContext<M>;
+}) => unknown | Promise<unknown>;
+/**
+ * Computes a field's value when a row is read. It receives the stored `record`
+ * and returns the value to return; returning `undefined` keeps the current value.
+ */
+export type ComputeReadFunction<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = (context: {
+    readonly field: AvEffectiveFieldKey<M, Cfg, R>;
+    readonly value: unknown;
+    readonly record: Readonly<Record<AvEffectiveFieldKey<M, Cfg, R>, unknown>>;
+    readonly ctx: AvComputeContext<M>;
+}) => unknown | Promise<unknown>;
+/** The fields of Resource `R` the adapter stores as scalars: what `dependsOn` may name. */
+type StoredScalarKey<M extends AvAdapterModel, R extends AvConfigResourceKey<M>> = string extends AvAdapterFieldKey<M, R> ? string : {
+    [F in AvAdapterFieldKey<M, R>]: M["resources"][R]["fields"][F] extends {
+        readonly kind: "scalar";
+    } ? F : never;
+}[AvAdapterFieldKey<M, R>];
+/**
+ * A read compute stage: a compute function, or `{ compute, dependsOn }` naming
+ * the fields it reads.
+ */
+export type AvComputeRead<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAny, R extends AvConfigResourceKey<M> = AvConfigResourceKey<M>> = ComputeReadFunction<M, Cfg, R> | {
+    readonly dependsOn?: readonly StoredScalarKey<M, R>[];
+    readonly compute: ComputeReadFunction<M, Cfg, R>;
+};
+export {};

package/dist/runtime/field-compute.js

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

package/dist/runtime/field-stage.plan.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedPipelineTree } from "../config/pipeline-tree.resolver.js";
+import type { AvContract } from "../contracts/contract.js";
+/** One origin's field-stage dispatch, planned at startup. */
+export type FieldStagePlan = {
+    /** Whether any Resource registers a field pipe. */
+    readonly anyPipes: boolean;
+    /** Whether any Resource registers a guard a nested target runs: its own, its family's or a field write guard. */
+    readonly nestedGuards: boolean;
+    /** `resource`'s fields with write guards, in the Resource's field order. */
+    readonly guarded: (resource: string) => readonly string[];
+    /** `resource`'s fields with field pipes, in the Resource's field order. */
+    readonly piped: (resource: string) => readonly string[];
+};
+/** Plans the field-stage dispatch of `tree` under `contract`. */
+export declare function planFieldStages(tree: ResolvedPipelineTree, contract: AvContract): FieldStagePlan;

package/dist/runtime/field-stage.plan.js

@@ -0,0 +1,27 @@
+import { stagedFieldsOf } from "./field-stage.runtime.js";
+const NONE = Object.freeze([]);
+export function planFieldStages(tree, contract) {
+    const guarded = new Map();
+    const piped = new Map();
+    let nestedGuards = false;
+    for (const [resource, pipelines] of Object.entries(tree.resources)) {
+        const guards = stagedFieldsOf(contract, resource, pipelines.fields, "guards");
+        const pipes = stagedFieldsOf(contract, resource, pipelines.fields, "pipes");
+        if (guards.length > 0) {
+            guarded.set(resource, Object.freeze([...guards]));
+        }
+        if (pipes.length > 0) {
+            piped.set(resource, Object.freeze([...pipes]));
+        }
+        nestedGuards ||=
+            guards.length > 0 ||
+                pipelines.pipelines.some((level) => level.guards.length > 0) ||
+                Object.values(pipelines.families).some((family) => family.pipelines.some((level) => level.guards.length > 0));
+    }
+    return Object.freeze({
+        anyPipes: piped.size > 0,
+        nestedGuards,
+        guarded: (resource) => guarded.get(resource) ?? NONE,
+        piped: (resource) => piped.get(resource) ?? NONE,
+    });
+}

package/dist/runtime/field-stage.runtime.d.ts

@@ -0,0 +1,37 @@
+import type { ResolvedFieldStages } from "../config/pipeline-tree.resolver.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationFamily } from "../operations/operation-identity.js";
+import type { AvContext } from "./pipeline.js";
+export type Path = readonly (string | number)[];
+type UnknownRecord = Readonly<Record<string, unknown>>;
+/** A plain object: what a write record, or a directive's operand, is. */
+export declare function isPlainRecord(value: unknown): value is UnknownRecord;
+/** The containers a family writes, by argument key. */
+export declare const WRITE_KEYS: Readonly<Partial<Record<AvOperationFamily, readonly string[]>>>;
+/** The fields of `resource` with stages, in the Resource's field order. */
+export declare function stagedFieldsOf(contract: AvContract, resource: string, stages: Readonly<Record<string, ResolvedFieldStages>>, kind: "pipes" | "guards"): readonly string[];
+/** The value at `path` in `args`, or `undefined` when nothing is there. */
+export declare function valueAt(args: unknown, path: Path): unknown;
+/** `args` with the record at `path` replaced, every container on the way copied. */
+export declare function replaceAt(args: unknown, path: Path, record: UnknownRecord): unknown;
+type PipedFields = {
+    readonly args: unknown;
+    /** Whether a field pipe returned a value: the arguments must be held to the server's rules again. */
+    readonly changed: boolean;
+};
+/** The paths of the top-level data records of a create, update or upsert. */
+export declare function writeRecordPathsOf(family: AvOperationFamily, args: unknown): readonly Path[];
+/**
+ * Runs the field pipes of every sent field `select` admits, in the records at
+ * `records`, field by field in the Resource's order, root's pipes then
+ * overlay's. A pipe returning `undefined` keeps the value. The arguments are
+ * copied where a value changes, never written.
+ */
+export declare function pipeSentFields(stages: Readonly<Record<string, ResolvedFieldStages>>, fields: readonly string[], records: readonly Path[], args: unknown, select: (path: Path) => boolean): Promise<PipedFields>;
+/**
+ * Runs the write guards of every sent field in the records at `records`, field
+ * by field in the Resource's order and, for several records, record by record;
+ * `false` as soon as one refuses.
+ */
+export declare function guardSentFields(stages: Readonly<Record<string, ResolvedFieldStages>>, fields: readonly string[], records: readonly Path[], args: unknown, context: () => AvContext): Promise<boolean>;
+export {};