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

package/dist/compiler/contract.compiler.js

@@ -7,6 +7,7 @@ import { DEFAULT_CONTRACT_LIMITS, } from "../contracts/contract-limits.js";
 import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
 import { advertisedDirectives, advertisedReducers, holdsInAnyScope, } from "../contracts/field.js";
 import { isOperationVariantAvailable, } from "../contracts/resource-operations.js";
+import { isRecord } from "../runtime/record.guard.js";
 import { checkCreateRequirements, checkHiddenRequirements, projectCreateRequirements, } from "./create-requirements.projector.js";
 import { applyValidators, bindFieldValidators, checkLayerValidators, compileValidatorTable, } from "./field-validator.compiler.js";
 import { explainManagedRefusals, hideManagedElsewhere, managedElsewhereOf, managedWriteReason, markCoreResources, pruneManagedEnums, withholdManagedWrites, } from "./managed-elsewhere.projector.js";
@@ -24,9 +25,6 @@ const COMPUTED_TRAITS = new Set([
 function diagnostic(code, path, message) {
     return { code, path, message };
 }
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function cloneValue(value) {
     if (Array.isArray(value)) {
         return value.map((entry) => cloneValue(entry));
@@ -438,7 +436,8 @@ function checkResourceTree(model, baseline, scope, tree, definitions, managed, d
                 diagnostics.push(diagnostic("COMPILER_UNKNOWN_FIELD", `${resourcePath}.fields.${fieldName}`, `field "${fieldName}" is neither discovered by the adapter nor defined at the root`));
                 continue;
             }
-            if (!isRecord(fieldEntry) || !isRecord(fieldEntry.pipelines)) {
+            if (!isRecord(fieldEntry) ||
+                !isRecord(fieldEntry.pipelines)) {
                 continue;
             }
             const pipelinesPath = `${resourcePath}.fields.${fieldName}.pipelines`;
@@ -764,7 +763,9 @@ function exemptOperations(walk, resourceName, universe, parent, entry, path) {
         if (value === false || value === undefined) {
             continue;
         }
-        if (value !== true && !Array.isArray(value) && !isRecord(value)) {
+        if (value !== true &&
+            !Array.isArray(value) &&
+            !isRecord(value)) {
             walk.diagnostics.push(diagnostic("COMPILER_UNAVAILABLE_OPERATION", familyPath, "an operation family takes true, false, a list of its variants or an object of them"));
             continue;
         }
@@ -811,7 +812,8 @@ function exemptResource(walk, resourceName, universe, parent, entry, path) {
 }
 function projectExposure(walk, universe, parent, exemptions) {
     const path = `${walk.layer}.exemptions.resources`;
-    const entries = isRecord(exemptions) && isRecord(exemptions.resources)
+    const entries = isRecord(exemptions) &&
+        isRecord(exemptions.resources)
         ? exemptions.resources
         : {};
     const resources = {};
@@ -855,7 +857,8 @@ function projectExposure(walk, universe, parent, exemptions) {
 }
 function pruneEmptyOperationFamilies(operations) {
     for (const [family, variants] of Object.entries(operations)) {
-        if (isRecord(variants) && Object.keys(variants).length === 0) {
+        if (isRecord(variants) &&
+            Object.keys(variants).length === 0) {
             delete operations[family];
         }
     }
@@ -1151,9 +1154,10 @@ export async function compileContracts(model, config) {
     }
     const core = semanticObject(coreCompilation.projection);
     const application = semanticObject(applicationProjection.projection);
+    const clientMarked = withReadCache(clientProjection.projection, compilerConfig.client.pipelines);
     const client = await identifiedContract(compilerConfig.access === undefined
-        ? clientProjection.projection
-        : { ...clientProjection.projection, access: compilerConfig.access });
+        ? clientMarked
+        : { ...clientMarked, access: compilerConfig.access });
     const agent = await identifiedContract(agentProjection.projection);
     for (const [layer, contract] of [
         ["client", client],
@@ -1180,6 +1184,49 @@ export async function compileContracts(model, config) {
     });
     return { ok: true, contracts };
 }
+function lastCacheOf(levels) {
+    for (let index = (levels?.length ?? 0) - 1; index >= 0; index -= 1) {
+        const stage = levels?.[index]?.cache;
+        if (stage !== undefined) {
+            return { for: stage.for ?? "user", maxAge: stage.maxAge };
+        }
+    }
+    return undefined;
+}
+function withReadCache(projection, tree) {
+    const layer = lastCacheOf(tree.layer);
+    const resources = {};
+    for (const [name, resource] of Object.entries(projection.resources)) {
+        const pipelines = Object.hasOwn(tree.resources, name)
+            ? tree.resources[name]
+            : undefined;
+        const find = Object.hasOwn(pipelines?.families ?? {}, "find")
+            ? pipelines?.families.find
+            : undefined;
+        const fallback = lastCacheOf(find?.pipelines) ??
+            lastCacheOf(pipelines?.pipelines) ??
+            layer;
+        const advertised = (resource.operations.find ?? {});
+        const marks = {};
+        for (const variant of Object.keys(advertised)) {
+            if (!isOperationVariantAvailable(advertised[variant])) {
+                continue;
+            }
+            const own = Object.hasOwn(find?.variants ?? {}, variant)
+                ? find?.variants[variant]?.pipelines
+                : undefined;
+            const mark = lastCacheOf(own) ?? fallback;
+            if (mark !== undefined) {
+                marks[variant] = mark;
+            }
+        }
+        resources[name] =
+            Object.keys(marks).length === 0
+                ? resource
+                : { ...resource, cache: marks };
+    }
+    return { ...projection, resources };
+}
 function bindRuntimePieces(contracts, definitions, validators) {
     for (const origin of ["core", "application", "client", "agent"]) {
         bindShapedFields(contracts[origin], definitions);

package/dist/compiler/create-requirements.projector.js

@@ -1,8 +1,6 @@
 import { advertisedDirectives, advertisedDirectivesAt, } from "../contracts/field.js";
 import { isOperationVariantAvailable, writeScopeOf, } from "../contracts/resource-operations.js";
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
+import { isRecord } from "../runtime/record.guard.js";
 function own(record, key) {
     return Object.hasOwn(record, key) ? record[key] : undefined;
 }

package/dist/compiler/field-validator.compiler.js

@@ -1,8 +1,6 @@
 import { avzCheckOf, } from "../avz/avz-check.registry.js";
 import { FIELD_CHECK_SUBJECTS, } from "../runtime/field-check.evaluator.js";
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
+import { isRecord } from "../runtime/record.guard.js";
 function own(record, key) {
     return Object.hasOwn(record, key) ? record[key] : undefined;
 }

package/dist/compiler/managed-elsewhere.projector.js

@@ -1,3 +1,4 @@
+import { isRecord } from "../runtime/record.guard.js";
 const WRITE_FAMILIES = [
     "create",
     "update",
@@ -8,16 +9,14 @@ const SOURCE_ROW_DIRECTIVES = [
     "$connect",
     "$disconnect",
 ];
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 export function managedElsewhereOf(rootTree) {
     const managed = new Set();
     if (!isRecord(rootTree)) {
         return managed;
     }
     for (const [name, entry] of Object.entries(rootTree)) {
-        if (isRecord(entry) && entry.managedElsewhere === true) {
+        if (isRecord(entry) &&
+            entry.managedElsewhere === true) {
             managed.add(name);
         }
     }
@@ -28,7 +27,8 @@ function keptDirectives(capability, kept) {
         const left = capability.filter((directive) => kept.includes(directive));
         return left.length > 0 ? left : undefined;
     }
-    if (isRecord(capability) && Array.isArray(capability.directives)) {
+    if (isRecord(capability) &&
+        Array.isArray(capability.directives)) {
         const left = capability.directives.filter((directive) => kept.includes(directive));
         return left.length > 0 ? { ...capability, directives: left } : undefined;
     }

package/dist/config/cache-stage.factory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A read's cache stage, for `pipelines.cache` at the root or client layer, a
+ * Resource, the `find` family or one of its variants:
+ * `pipelines: { cache: cache({ for: "user", maxAge: 60 }) }`. The read is then
+ * also served as a GET a browser or a CDN may keep for `maxAge` seconds.
+ *
+ * Always write `for`, even for the default `"user"`: the audience is the
+ * promise this read makes, and it should be visible in the code.
+ */
+export declare function cache(stage: {
+    /**
+     * Who may share one answer: `"user"` (the default; each caller's own
+     * browser keeps its own), `"anonymous"` (anonymous callers share one answer a
+     * CDN may keep; a signed-in caller's stays private) or `"everyone"` (one
+     * answer for every caller, which a CDN may hand to anyone). Always write it,
+     * even for `"user"`: the audience is the promise this read makes.
+     */
+    readonly for?: "user" | "anonymous" | "everyone";
+    /** How long an answer may be kept, in whole seconds (`max-age`). */
+    readonly maxAge: number;
+}): {
+    readonly for: "user" | "anonymous" | "everyone";
+    readonly maxAge: number;
+};

package/dist/config/cache-stage.factory.js

@@ -0,0 +1,3 @@
+export function cache(stage) {
+    return Object.freeze({ for: stage.for ?? "user", maxAge: stage.maxAge });
+}

package/dist/config/config.resolver.js

@@ -1,17 +1,11 @@
 import { AvConstructionError } from "../framework/framework-construction.error.js";
 import { ACCESS_VERB_NAMES, providerVerb, } from "../policy/access-verb.table.js";
+import { isPlainRecord } from "../runtime/record.guard.js";
 import { mountPathRefusalDiagnostic } from "./config.validator.js";
 import { normalizeEntrypoint } from "./entrypoint.normalizer.js";
 import { chainCompute, computeOfLayer, } from "./field-compute.resolver.js";
 import { resolvePipelineTree, } from "./pipeline-tree.resolver.js";
 const hasOwn = (value, key) => Object.hasOwn(value, key);
-function isPlainRecord(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
 function cloneConfigValue(value) {
     if (Array.isArray(value)) {
         return [...value];

package/dist/config/config.validator.js

@@ -1,6 +1,7 @@
 import { isAccessPath, isAccessUrl } from "../contracts/access-route.rules.js";
 import { TRANSACTION_CAPABILITIES } from "../contracts/transaction-capability.js";
 import { ACCESS_VERB_NAMES, isAccessVerbName, providerVerb, } from "../policy/access-verb.table.js";
+import { isPlainRecord } from "../runtime/record.guard.js";
 import { normalizeEntrypoint } from "./entrypoint.normalizer.js";
 import { AVZ_FORMATS } from "./framework-field-definition.js";
 const ROOT_ONLY_PROPERTIES = new Set([
@@ -77,6 +78,8 @@ const LIMIT_PROPERTIES = new Set([
     "maxTransactionOperations",
     "maxBooleanNodes",
     "maxJsonDepth",
+    "maxAll",
+    "maxAllConcurrency",
 ]);
 const PIPELINE_PROPERTIES = new Set([
     "guards",
@@ -86,13 +89,6 @@ const PIPELINE_PROPERTIES = new Set([
     "filters",
 ]);
 const PIPELINE_HOOK_PROPERTIES = new Set(["before", "after"]);
-function isPlainRecord(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
 function diagnostic(code, path, message) {
     return { code, path, message };
 }
@@ -119,6 +115,14 @@ function validateLimits(value, path, diagnostics) {
             diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", limitPath, `unknown limit property: ${key}`));
             continue;
         }
+        if (key === "maxAllConcurrency") {
+            if (typeof limit !== "number" ||
+                !Number.isSafeInteger(limit) ||
+                limit < 1) {
+                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", limitPath, `${limitPath} must be a whole number of at least 1`));
+            }
+            continue;
+        }
         if (typeof limit !== "number" ||
             !Number.isFinite(limit) ||
             !Number.isInteger(limit) ||
@@ -127,6 +131,33 @@ function validateLimits(value, path, diagnostics) {
         }
     }
 }
+const CACHE_PROPERTIES = new Set(["for", "maxAge"]);
+const CACHE_AUDIENCES = new Set(["user", "anonymous", "everyone"]);
+function validateCache(value, path, diagnostics) {
+    if (!requireRecord(value, path, diagnostics)) {
+        return;
+    }
+    for (const key of Object.keys(value)) {
+        if (!CACHE_PROPERTIES.has(key)) {
+            diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `${path}.${key}`, `unknown cache property: ${key}; cache takes for and maxAge`));
+        }
+    }
+    const maxAgePath = `${path}.maxAge`;
+    if (!Object.hasOwn(value, "maxAge")) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", maxAgePath, `${maxAgePath} is required`));
+    }
+    else if (typeof value.maxAge !== "number" ||
+        !Number.isInteger(value.maxAge) ||
+        value.maxAge < 0 ||
+        value.maxAge > MAX_CACHE_AGE) {
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", maxAgePath, `${maxAgePath} must be a whole number of seconds from 0 to ${MAX_CACHE_AGE}`));
+    }
+    if (Object.hasOwn(value, "for") && !CACHE_AUDIENCES.has(value.for)) {
+        const forPath = `${path}.for`;
+        diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", forPath, `${forPath} must be "user", "anonymous" or "everyone"`));
+    }
+}
+const MAX_CACHE_AGE = 2_147_483_647;
 function validateArray(value, key, path, diagnostics) {
     if (!Object.hasOwn(value, key)) {
         return;
@@ -148,7 +179,7 @@ function validatePipelineHooks(value, path, diagnostics) {
     validateArray(value, "before", path, diagnostics);
     validateArray(value, "after", path, diagnostics);
 }
-function validatePipelines(value, path, diagnostics) {
+function validatePipelines(value, path, diagnostics, cacheRefusal) {
     if (!requireRecord(value, path, diagnostics)) {
         return;
     }
@@ -157,6 +188,16 @@ function validatePipelines(value, path, diagnostics) {
             diagnostics.push(diagnostic("CONFIG_MOVED_PROPERTY", `${path}.${key}`, `${path}.${key} moved in rc.1: hooks are ${path}.hooks.${key}`));
             continue;
         }
+        if (key === "cache") {
+            const refusal = cacheRefusal ?? layerCacheRefusal(path);
+            if (refusal !== undefined) {
+                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `${path}.cache`, `${path}.cache: ${refusal}`));
+            }
+            else if (value.cache !== undefined) {
+                validateCache(value.cache, `${path}.cache`, diagnostics);
+            }
+            continue;
+        }
         if (!PIPELINE_PROPERTIES.has(key)) {
             diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", `${path}.${key}`, `unknown pipeline property: ${key}`));
         }
@@ -168,6 +209,13 @@ function validatePipelines(value, path, diagnostics) {
         validatePipelineHooks(value.hooks, `${path}.hooks`, diagnostics);
     }
 }
+function layerCacheRefusal(path) {
+    const layer = path.split(".")[0];
+    return layer === "application" || layer === "agent"
+        ? `cache applies to a client's reads; the ${layer} layer is never served a GET (state it at the root or in client)`
+        : undefined;
+}
+const WRITE_CACHE_REFUSAL = "cache applies to reads (the find family) only; a write is never a GET";
 function validateForceTransaction(value, path, diagnostics) {
     if (!Object.hasOwn(value, "forceTransaction")) {
         return;
@@ -177,21 +225,21 @@ function validateForceTransaction(value, path, diagnostics) {
         diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", propertyPath, `${propertyPath} must be a boolean`));
     }
 }
-function validateOperationLevel(value, path, isFamily, diagnostics) {
+function validateOperationLevel(value, path, isFamily, diagnostics, isRead) {
     if (!requireRecord(value, path, diagnostics)) {
         return;
     }
     for (const [key, child] of Object.entries(value)) {
         const keyPath = `${path}.${key}`;
         if (key === "pipelines") {
-            validatePipelines(child, keyPath, diagnostics);
+            validatePipelines(child, keyPath, diagnostics, isRead ? undefined : WRITE_CACHE_REFUSAL);
             continue;
         }
         if (key === "forceTransaction") {
             continue;
         }
         if (isFamily && OPERATION_VARIANTS.has(key)) {
-            validateOperationLevel(child, keyPath, false, diagnostics);
+            validateOperationLevel(child, keyPath, false, diagnostics, isRead);
             continue;
         }
         diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, isFamily
@@ -210,7 +258,7 @@ function validateOperations(value, path, diagnostics) {
             diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", familyPath, `unknown operation family: ${family}`));
             continue;
         }
-        validateOperationLevel(level, familyPath, true, diagnostics);
+        validateOperationLevel(level, familyPath, true, diagnostics, family === "find");
     }
 }
 function validateResourceTransactions(value, path, diagnostics) {
@@ -223,7 +271,7 @@ function validateResourceTransactions(value, path, diagnostics) {
             diagnostics.push(diagnostic("CONFIG_UNKNOWN_PROPERTY", keyPath, `unknown Resource transactions property: ${key}`));
             continue;
         }
-        validatePipelines(child, keyPath, diagnostics);
+        validatePipelines(child, keyPath, diagnostics, "cache applies to reads; a transaction is never a GET");
     }
 }
 function validateDefinition(value, path, diagnostics) {

package/dist/config/exact-framework-config.d.ts

@@ -16,6 +16,10 @@ type PipelinesSchema = {
     };
     readonly interceptors: Leaf;
     readonly filters: Leaf;
+    readonly cache: {
+        readonly for: Leaf;
+        readonly maxAge: Leaf;
+    };
 };
 type LimitsSchema = {
     readonly maxRequestBytes: Leaf;
@@ -24,6 +28,8 @@ type LimitsSchema = {
     readonly maxTransactionOperations: Leaf;
     readonly maxBooleanNodes: Leaf;
     readonly maxJsonDepth: Leaf;
+    readonly maxAll: Leaf;
+    readonly maxAllConcurrency: Leaf;
 };
 type LevelSchema = {
     readonly pipelines: PipelinesSchema;

package/dist/config/field-compute.resolver.js

@@ -1,3 +1,4 @@
+import { isRecord } from "../runtime/record.guard.js";
 function chainWrite(root, overlay) {
     if (root === undefined || overlay === undefined) {
         return root ?? overlay;
@@ -46,9 +47,6 @@ function chainRead(root, overlay) {
         ? compute
         : { dependsOn, compute };
 }
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 export function computeOfLayer(resources) {
     const result = {};
     if (!isRecord(resources)) {

package/dist/config/pipeline-config.d.ts

@@ -23,6 +23,17 @@ export type AvPipeline<M extends AvAdapterModel = AvAdapterModel, R extends stri
     readonly interceptors?: readonly AvInterceptor<M, R, F, V, A>[];
     /** Turn a thrown error into a {@link AvError} outcome. */
     readonly filters?: readonly AvFilter<M, R, F, V, PreCompute>[];
+    /**
+     * A read's cache stage, `cache({ for: "user", maxAge: 60 })`: the reads this
+     * level covers (its `find` operations) are also served as a GET a browser or
+     * a CDN may keep. The most specific level's stage wins. Always write `for`,
+     * even for the default `"user"`: the audience is the promise this read
+     * makes, and it should be visible in the code.
+     */
+    readonly cache?: {
+        readonly for?: "user" | "anonymous" | "everyone";
+        readonly maxAge: number;
+    };
 };
 /**
  * A Resource's transaction stages: they run once per transaction with a
@@ -51,6 +62,11 @@ export type ResolvedPipelineConfig = {
     };
     readonly interceptors: readonly AvInterceptor[];
     readonly filters: readonly AvFilter[];
+    /** The level's read cache stage, as authored (validated); rc.11. */
+    readonly cache?: {
+        readonly for?: "user" | "anonymous" | "everyone";
+        readonly maxAge: number;
+    };
 };
 /** One layer's registrations on one Resource's transactions. */
 export type ResolvedTransactionPipelineConfig = {

package/dist/config/pipeline-tree.resolver.js

@@ -1,6 +1,4 @@
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
+import { isRecord } from "../runtime/record.guard.js";
 function own(record, key) {
     return record !== undefined && Object.hasOwn(record, key)
         ? record[key]
@@ -23,6 +21,7 @@ function levelOf(value) {
         },
         interceptors: list(pipeline.interceptors),
         filters: list(pipeline.filters),
+        ...(isRecord(pipeline.cache) ? { cache: pipeline.cache } : {}),
     };
 }
 function transactionLevelOf(value) {

package/dist/contracts/canonical-json.writer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The canonical JSON text (RFC 8785) of a JSON value: an object's keys in
+ * UTF-16 code-unit order, a member holding `undefined` left out, nothing but
+ * `null`, booleans, finite numbers, strings, arrays and plain objects. Throws a
+ * `TypeError` for anything else, a lone surrogate in a string or key included.
+ */
+export declare function canonicalJson(value: unknown): string;

package/dist/contracts/canonical-json.writer.js

@@ -0,0 +1,55 @@
+export function canonicalJson(value) {
+    const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+    const text = (string) => {
+        if (LONE_SURROGATE.test(string)) {
+            throw new TypeError("Canonical JSON cannot write a lone surrogate.");
+        }
+        return JSON.stringify(string);
+    };
+    const write = (current, ancestors) => {
+        if (current === null) {
+            return "null";
+        }
+        switch (typeof current) {
+            case "boolean":
+                return current ? "true" : "false";
+            case "number":
+                if (!Number.isFinite(current)) {
+                    throw new TypeError("Canonical JSON cannot write a non-finite number.");
+                }
+                return JSON.stringify(current);
+            case "string":
+                return text(current);
+            case "object":
+                break;
+            default:
+                throw new TypeError(`Canonical JSON cannot write a ${typeof current}.`);
+        }
+        const container = current;
+        if (ancestors.includes(container)) {
+            throw new TypeError("Canonical JSON cannot write a cycle.");
+        }
+        const path = [...ancestors, container];
+        if (Array.isArray(container)) {
+            const items = [];
+            for (let index = 0; index < container.length; index += 1) {
+                items.push(write(container[index] ?? null, path));
+            }
+            return `[${items.join(",")}]`;
+        }
+        const prototype = Object.getPrototypeOf(container);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("Canonical JSON writes plain objects only.");
+        }
+        const record = container;
+        const members = [];
+        for (const key of Object.keys(record).sort((left, right) => left < right ? -1 : left > right ? 1 : 0)) {
+            const member = record[key];
+            if (member !== undefined) {
+                members.push(`${text(key)}:${write(member, path)}`);
+            }
+        }
+        return `{${members.join(",")}}`;
+    };
+    return write(value, []);
+}

package/dist/contracts/client-contract-structure.validator.d.ts

@@ -1307,6 +1307,64 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                             };
                         };
                     };
+                    readonly cache: {
+                        readonly is: "object";
+                        readonly required: {};
+                        readonly optional: {
+                            readonly first: {
+                                readonly is: "object";
+                                readonly required: {
+                                    readonly for: {
+                                        readonly is: "literal";
+                                        readonly values: readonly ["user", "anonymous", "everyone"];
+                                    };
+                                    readonly maxAge: {
+                                        readonly is: "number";
+                                    };
+                                };
+                                readonly optional: {};
+                            };
+                            readonly unique: {
+                                readonly is: "object";
+                                readonly required: {
+                                    readonly for: {
+                                        readonly is: "literal";
+                                        readonly values: readonly ["user", "anonymous", "everyone"];
+                                    };
+                                    readonly maxAge: {
+                                        readonly is: "number";
+                                    };
+                                };
+                                readonly optional: {};
+                            };
+                            readonly many: {
+                                readonly is: "object";
+                                readonly required: {
+                                    readonly for: {
+                                        readonly is: "literal";
+                                        readonly values: readonly ["user", "anonymous", "everyone"];
+                                    };
+                                    readonly maxAge: {
+                                        readonly is: "number";
+                                    };
+                                };
+                                readonly optional: {};
+                            };
+                            readonly count: {
+                                readonly is: "object";
+                                readonly required: {
+                                    readonly for: {
+                                        readonly is: "literal";
+                                        readonly values: readonly ["user", "anonymous", "everyone"];
+                                    };
+                                    readonly maxAge: {
+                                        readonly is: "number";
+                                    };
+                                };
+                                readonly optional: {};
+                            };
+                        };
+                    };
                 };
             };
         };
@@ -1331,6 +1389,12 @@ export declare const CLIENT_CONTRACT_STRUCTURE: {
                 readonly maxJsonDepth: {
                     readonly is: "number";
                 };
+                readonly maxAll: {
+                    readonly is: "number";
+                };
+                readonly maxAllConcurrency: {
+                    readonly is: "number";
+                };
             };
             readonly optional: Record<never, never>;
         };

package/dist/contracts/client-contract-structure.validator.js

@@ -265,6 +265,10 @@ const RELATION_FIELD = object({
     governed: literal([true]),
 });
 const OPERATION_AVAILABILITY = union(literal([true]), object({ projection: literal(PROJECTION_SCOPES) }, { write: literal(WRITE_SCOPES) }), object({ write: literal(WRITE_SCOPES) }, { projection: literal(PROJECTION_SCOPES) }));
+const READ_CACHE_MARK = object({
+    for: literal(["user", "anonymous", "everyone"]),
+    maxAge: NUMBER,
+}, {});
 const RESOURCE = object({
     fields: registry({
         is: "variants",
@@ -304,6 +308,12 @@ const RESOURCE = object({
         oneOf: nonEmptyList(pairOrMoreList(STRING)),
         parentSupplies: registry(registry(nonEmptyList(STRING))),
     }),
+    cache: object({}, {
+        first: READ_CACHE_MARK,
+        unique: READ_CACHE_MARK,
+        many: READ_CACHE_MARK,
+        count: READ_CACHE_MARK,
+    }),
 });
 const ACCESS_VERB = object({
     method: literal(["GET", "POST"]),
@@ -336,6 +346,8 @@ export const CLIENT_CONTRACT_STRUCTURE = object({
         maxTransactionOperations: NUMBER,
         maxBooleanNodes: NUMBER,
         maxJsonDepth: NUMBER,
+        maxAll: NUMBER,
+        maxAllConcurrency: NUMBER,
     }),
     transactions: literal(TRANSACTION_CAPABILITIES),
     protocol: object({

package/dist/contracts/contract-canonicalizer.js

@@ -187,8 +187,13 @@ function normalizeResource(resource) {
                 createRequirements: normalizeCreateRequirements(resource.createRequirements),
             }),
         ...coreResourceFacts(resource),
+        ...clientResourceFacts(resource),
     };
 }
+function clientResourceFacts(resource) {
+    const { cache } = resource;
+    return cache === undefined ? {} : { cache };
+}
 function coreResourceFacts(resource) {
     const facts = resource;
     return {