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

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

@@ -1,4 +1,5 @@
-import { PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
+import { isAccessPath, isAccessUrl } from "./access-route.rules.js";
+import { FILTER_MODES, PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
 import { AVENTARA_PROTOCOL_VERSION } from "./contract-protocol.js";
 import { LIFECYCLE_TRAITS } from "./lifecycle-trait.js";
 import { REFERENCE_WRITE_LIMITS } from "./reference-write-limit.js";
@@ -226,6 +227,8 @@ const SCALAR_FIELD = object({
     capabilities: object({}, {
         select: BOOLEAN,
         filter: list(literal(SCALAR_FILTER_OPERATORS)),
+        filterModes: list(literal(FILTER_MODES)),
+        pathFilterModes: list(literal(FILTER_MODES)),
         order: BOOLEAN,
         orderNulls: BOOLEAN,
         create: list(literal(SCALAR_MUTATION_DIRECTIVES)),
@@ -235,6 +238,7 @@ const SCALAR_FIELD = object({
     format: STRING,
     json: { is: "jsonSchema" },
     validators: list(FIELD_CHECK),
+    governed: literal([true]),
 });
 const RELATION_FIELD = object({
     kind: literal(["relation"]),
@@ -255,8 +259,16 @@ const RELATION_FIELD = object({
         update: RELATION_MUTATION,
         nestedWriteFilter: literal(["scalar"]),
     }),
+}, {
+    inverse: STRING,
+    referenceFields: nonEmptyList(STRING),
+    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",
@@ -296,6 +308,32 @@ 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"]),
+    path: { is: "route", form: "path" },
+    result: { is: "jsonSchema" },
+}, { args: { is: "jsonSchema" } });
+const ACCESS = object({}, {
+    url: { is: "route", form: "url" },
+    verbs: object({}, {
+        signIn: ACCESS_VERB,
+        signUp: ACCESS_VERB,
+        signOut: ACCESS_VERB,
+        resetPassword: ACCESS_VERB,
+        me: ACCESS_VERB,
+        switchUser: ACCESS_VERB,
+        lock: ACCESS_VERB,
+        setPin: ACCESS_VERB,
+        enrollDevice: ACCESS_VERB,
+        revokeDevice: ACCESS_VERB,
+    }),
 });
 export const CLIENT_CONTRACT_STRUCTURE = object({
     scalars: registry(object({ builtin: literal([true]) })),
@@ -308,13 +346,15 @@ export const CLIENT_CONTRACT_STRUCTURE = object({
         maxTransactionOperations: NUMBER,
         maxBooleanNodes: NUMBER,
         maxJsonDepth: NUMBER,
+        maxAll: NUMBER,
+        maxAllConcurrency: NUMBER,
     }),
     transactions: literal(TRANSACTION_CAPABILITIES),
     protocol: object({
         version: literal([AVENTARA_PROTOCOL_VERSION]),
         hash: { is: "prefixed", prefix: "sha256:" },
     }),
-}, { referenceWrites: literal(REFERENCE_WRITE_LIMITS) });
+}, { referenceWrites: literal(REFERENCE_WRITE_LIMITS), access: ACCESS });
 export function validateClientContractStructure(value) {
     const defect = defectOf(CLIENT_CONTRACT_STRUCTURE, value, "$", 0);
     if (defect !== undefined) {
@@ -336,6 +376,13 @@ function defectOf(node, value, path, depth) {
                 (value.startsWith(node.prefix)
                     ? undefined
                     : at(path, depth, `is ${JSON.stringify(value)}, which does not begin with ${JSON.stringify(node.prefix)}`)));
+        case "route":
+            return (kindDefect(value, "string", path, depth) ??
+                ((node.form === "url" ? isAccessUrl : isAccessPath)(value)
+                    ? undefined
+                    : at(path, depth, node.form === "url"
+                        ? "is no absolute http(s) URL and no root-relative path"
+                        : 'is no path under the url, starting with one "/"')));
         case "list":
             return listDefect(node, value, path, depth);
         case "registry": {

package/dist/contracts/contract-access.d.ts

@@ -0,0 +1,29 @@
+import type { JsonSchema } from "./json-shape.js";
+/**
+ * The ClientContract's `access` section: present exactly when the framework's
+ * `access` option is configured, and then it marks the `POST /_access/can`
+ * route. `url` and `verbs` say where Aventara Access is mounted and each of its
+ * `$access` verbs, when the provider states them.
+ */
+export type AvContractClientAccess = {
+    /** Where the app mounted Access: absolute, or root-relative (`"/api/auth"`). */
+    readonly url?: string;
+    /**
+     * Each `$access` verb the provider offers: its route under `url`, and the
+     * JSON Schema of its arguments and result. A verb left out is no verb of
+     * `$access` (a `service` profile has no `signIn` or `signUp`; only a
+     * `kiosk` profile has `switchUser`, `lock`, `setPin`, `enrollDevice` and
+     * `revokeDevice`).
+     */
+    readonly verbs?: {
+        readonly [Verb in "signIn" | "signUp" | "signOut" | "resetPassword" | "me" | "switchUser" | "lock" | "setPin" | "enrollDevice" | "revokeDevice"]?: {
+            readonly method: "GET" | "POST";
+            /** Under `url`: `"/sign-in/email"`. */
+            readonly path: string;
+            /** The arguments' JSON Schema; absent when the verb takes none. */
+            readonly args?: JsonSchema;
+            /** The result's JSON Schema (`me`: the value when someone is signed in). */
+            readonly result: JsonSchema;
+        };
+    };
+};

package/dist/contracts/contract-access.js

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

package/dist/contracts/contract-canonicalizer.d.ts

@@ -7,8 +7,15 @@ export declare class AvCanonicalJsonError extends TypeError {
 }
 /** Canonical JSON (RFC 8785) for a JSON-safe value. */
 export declare function canonicalizeJson(value: unknown): string;
+/**
+ * Canonical JSON (RFC 8785) for a value as JSON carries it: a key holding
+ * `undefined` is left out, and an array element holding it (or a hole) is
+ * `null`, as `JSON.stringify` writes them. Everything else as
+ * {@link canonicalizeJson}.
+ */
+export declare function canonicalizeWireJson(value: unknown): string;
 /** One top-level member of a canonical Contract: its key and its value's canonical text. */
-export type CanonicalContractMember = {
+type CanonicalContractMember = {
     readonly key: string;
     readonly text: string;
 };
@@ -25,3 +32,4 @@ export declare function recordCanonicalContractText(contract: AvContract, text:
  * recorded one, else written now. Both are the same bytes for the same Contract.
  */
 export declare function canonicalContractTextOf<C extends AvContract>(contract: C): string;
+export {};

package/dist/contracts/contract-canonicalizer.js

@@ -1,10 +1,12 @@
-import { PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
+import { brandCoreClass } from "../runtime/core-class.brand.js";
+import { FILTER_MODES, PROJECTION_SCOPES, WRITE_SCOPES } from "./capability.js";
 import { LIFECYCLE_TRAITS } from "./lifecycle-trait.js";
 import { projectionScopeOf, writeScopeOf } from "./resource-operations.js";
 const PAGINATION_ORDER = ["limit", "offset", "cursor"];
 const REDUCER_ORDER = ["$count"];
 export class AvCanonicalJsonError extends TypeError {
 }
+brandCoreClass(AvCanonicalJsonError, "AvCanonicalJsonError");
 function compareCodeUnits(left, right) {
     if (left === right) {
         return 0;
@@ -61,6 +63,12 @@ function normalizeCapabilities(capabilities) {
     if (Array.isArray(filter)) {
         normalized.filter = normalizeStringSet(filter);
     }
+    for (const key of ["filterModes", "pathFilterModes"]) {
+        const modes = normalized[key];
+        if (Array.isArray(modes)) {
+            normalized[key] = normalizeStringSet(modes, FILTER_MODES);
+        }
+    }
     for (const key of ["create", "update"]) {
         const value = normalized[key];
         if (Array.isArray(value)) {
@@ -178,6 +186,21 @@ 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 {
+        ...(facts.schema === undefined ? {} : { schema: facts.schema }),
+        ...(facts.managedElsewhere === undefined
+            ? {}
+            : { managedElsewhere: facts.managedElsewhere }),
     };
 }
 function isJsonObject(value) {
@@ -286,7 +309,7 @@ function canonicalizePrimitive(value, link) {
             return undefined;
     }
 }
-function canonicalizeValue(value, link = undefined) {
+function canonicalizeValue(value, link = undefined, undefinedAsJson = false) {
     const output = [];
     const stack = [{ kind: "value", value, link }];
     while (stack.length > 0) {
@@ -310,7 +333,10 @@ function canonicalizeValue(value, link = undefined) {
             output.push("[");
             stack.push({ kind: "text", text: "]" });
             for (let index = current.length - 1; index >= 0; index -= 1) {
-                if (index in current) {
+                if (undefinedAsJson && current[index] === undefined) {
+                    stack.push({ kind: "text", text: "null" });
+                }
+                else if (index in current) {
                     stack.push({
                         kind: "value",
                         value: current[index],
@@ -328,7 +354,9 @@ function canonicalizeValue(value, link = undefined) {
             throw new AvCanonicalJsonError(`non-plain object at ${pathOf(link)} is not canonical JSON`);
         }
         const record = current;
-        const keys = Object.keys(record).sort(compareCodeUnits);
+        const keys = Object.keys(record)
+            .filter((key) => !undefinedAsJson || record[key] !== undefined)
+            .sort(compareCodeUnits);
         output.push("{");
         stack.push({ kind: "text", text: "}" });
         for (let index = keys.length - 1; index >= 0; index -= 1) {
@@ -349,6 +377,9 @@ function canonicalizeValue(value, link = undefined) {
 export function canonicalizeJson(value) {
     return canonicalizeValue(value);
 }
+export function canonicalizeWireJson(value) {
+    return canonicalizeValue(value, undefined, true);
+}
 export function canonicalizeContractMembers(contract) {
     const record = normalizeContract(contract);
     return Object.keys(record)

package/dist/contracts/contract-hash.d.ts

@@ -4,7 +4,6 @@ import type { AvContractHash, AvContractProtocol } from "./contract-protocol.js"
 export type AvContractClientHashInput = Omit<AvContractClient, "protocol"> & {
     readonly protocol: AvContractProtocol;
 };
-export declare function createClientContractHashInput(contract: AvContractClient | AvContractClientHashInput): AvContractClientHashInput;
 /** Computes a ClientContract's `sha256:` hash, ignoring `protocol.hash` itself. */
 export declare function computeClientContractHash(contract: AvContractClient | AvContractClientHashInput): Promise<AvContractHash>;
 /**

package/dist/contracts/contract-hash.js

@@ -1,5 +1,5 @@
 import { canonicalizeContract } from "./contract-canonicalizer.js";
-export function createClientContractHashInput(contract) {
+function createClientContractHashInput(contract) {
     const { protocol, ...semantic } = contract;
     return {
         ...semantic,

package/dist/contracts/contract-limits.d.ts

@@ -12,6 +12,10 @@ export type AvContractLimits = {
     readonly maxBooleanNodes: number;
     /** How deeply a `json` field's value may nest: its arrays and objects, counted from the value. */
     readonly maxJsonDepth: number;
+    /** The most operations one Operation Set (`POST /_all`) may hold. */
+    readonly maxAll: number;
+    /** The most entries of one Operation Set that run at once; at least 1. */
+    readonly maxAllConcurrency: number;
 };
 /** The limits in force when the configuration sets none. */
 export declare const DEFAULT_CONTRACT_LIMITS: {
@@ -21,4 +25,6 @@ export declare const DEFAULT_CONTRACT_LIMITS: {
     readonly maxTransactionOperations: 20;
     readonly maxBooleanNodes: 50;
     readonly maxJsonDepth: 64;
+    readonly maxAll: 10;
+    readonly maxAllConcurrency: 4;
 };

package/dist/contracts/contract-limits.js

@@ -5,4 +5,6 @@ export const DEFAULT_CONTRACT_LIMITS = {
     maxTransactionOperations: 20,
     maxBooleanNodes: 50,
     maxJsonDepth: 64,
+    maxAll: 10,
+    maxAllConcurrency: 4,
 };

package/dist/contracts/contract.d.ts

@@ -1,6 +1,8 @@
+import type { AvContractClientAccess } from "./contract-access.js";
 import type { AvContractLimits } from "./contract-limits.js";
 import type { AvContractClientProtocol } from "./contract-protocol.js";
 import type { AvEnumDefinition } from "./enum-definition.js";
+import type { AvCoreField } from "./field.js";
 import type { ReferenceWriteLimit } from "./reference-write-limit.js";
 import type { AvResource } from "./resource.js";
 import type { AvScalarRegistry } from "./scalar.js";
@@ -24,8 +26,27 @@ export interface AvContract {
      */
     readonly referenceWrites?: ReferenceWriteLimit;
 }
-/** The Contract compiled from the root configuration. */
+/**
+ * The Contract compiled from the root configuration. Its relation fields also
+ * state the target's fields their reference names (`references`), and its
+ * Resources the database schema the store keeps them in (`schema`) and whether
+ * another service owns them (`managedElsewhere`), which no other Contract
+ * carries.
+ */
 export interface AvContractCore extends AvContract {
+    /** The Resources, by name. */
+    readonly resources: Readonly<Record<string, AvCoreResource>>;
+}
+/**
+ * A Resource as the Core Contract states it: its fields are
+ * {@link AvCoreField}s, so its relation fields carry `references`.
+ */
+export interface AvCoreResource extends AvResource<AvContractCore> {
+    readonly fields: Readonly<Record<string, AvCoreField<AvContractCore>>>;
+    /** The database schema the store keeps this Resource in, when the adapter states one. */
+    readonly schema?: string;
+    /** Present when another service owns this Resource: it is read, never written. */
+    readonly managedElsewhere?: true;
 }
 /** The Contract in-process calls run under (`framework.application`). */
 export interface AvContractApplication extends AvContract {
@@ -35,8 +56,28 @@ export interface AvContractApplication extends AvContract {
  * identified by its hash.
  */
 export interface AvContractClient extends AvContract {
+    /**
+     * The Resources, by name. One with a cached read carries `cache`, by `find`
+     * variant: that read is also served as
+     * `GET /_resources/<resource>/find/<variant>?q=…&v=…`, which a browser
+     * (`for: "user"`), a CDN for anonymous callers (`"anonymous"`) or a CDN for
+     * everyone (`"everyone"`) may keep for `maxAge` seconds.
+     */
+    readonly resources: Readonly<Record<string, AvResource<this> & {
+        readonly cache?: {
+            readonly [variant in "first" | "unique" | "many" | "count"]?: {
+                readonly for: "user" | "anonymous" | "everyone";
+                readonly maxAge: number;
+            };
+        };
+    }>>;
     /** The protocol version and this Contract's hash. */
     readonly protocol: AvContractClientProtocol;
+    /**
+     * Present exactly when the framework's `access` option is configured: the
+     * `POST /_access/can` route, and `$access`'s other verbs when it has `verbs`.
+     */
+    readonly access?: AvContractClientAccess;
 }
 /**
  * The Contract an AI agent's calls run under (the `agent` layer), identified by

package/dist/contracts/field.d.ts

@@ -1,4 +1,4 @@
-import type { AvPaginationCapability, AvProjectionScope, AvRelationFilterCapability, AvRelationMutationDirective, AvRelationReducer, AvScalarFilterOperator, AvScalarMutationDirective, AvWriteScope } from "./capability.js";
+import type { AvPaginationCapability, AvProjectionScope, AvRelationFilterCapability, AvRelationMutationDirective, AvRelationReducer, AvScalarFilterOperator, AvScalarMutationDirective, AvWriteScope, ScalarFilterMode } from "./capability.js";
 import type { AvContract } from "./contract.js";
 import type { AvFieldCheck } from "./field-check.js";
 import type { JsonSchema } from "./json-shape.js";
@@ -53,6 +53,19 @@ export type AvRelationMutationCapability = readonly AvRelationMutationDirective[
 export type AvScalarFieldCapabilities = {
     readonly select?: boolean;
     readonly filter?: readonly AvScalarFilterOperator[];
+    /**
+     * The modes the `mode` operator takes on this field: `"default"` (the
+     * database's own comparison) always, and `"sensitive"` or `"insensitive"`
+     * where the adapter honours them. Present exactly when `filter` offers `mode`.
+     */
+    readonly filterModes?: readonly ScalarFilterMode[];
+    /**
+     * A `json` field's modes when the filter names a `path`: the text compared is
+     * the value at that path rather than the whole document, and the database may
+     * honour more modes there. Present exactly when `filter` offers `mode` and
+     * `path`; without a `path`, `filterModes` applies.
+     */
+    readonly pathFilterModes?: readonly ScalarFilterMode[];
     readonly order?: boolean;
     readonly orderNulls?: boolean;
     readonly create?: readonly AvScalarMutationDirective[];
@@ -125,6 +138,12 @@ export type AvScalarField<C extends AvContract> = {
      * `list: true` length check, which applies to the list.
      */
     readonly validators?: readonly AvFieldCheck[];
+    /**
+     * `true` when the policy governs the field: it is left out of every default
+     * projection, and a caller that wants it names it (`select: ["$defaults",
+     * "email"]`).
+     */
+    readonly governed?: true;
 };
 /** A relation field; the `target` Resource describes the related row. */
 export type AvRelationField<C extends AvContract> = {
@@ -133,6 +152,44 @@ export type AvRelationField<C extends AvContract> = {
     readonly cardinality: "one" | "many";
     readonly nullable: boolean;
     readonly capabilities: AvRelationFieldCapabilities;
+    /**
+     * The target's relation field that is this relation's other end
+     * (`User.posts` ↔ `Post.author`): a record written through this relation sits
+     * at that field's `"loopback"` write position. Absent when the adapter states
+     * no pairing or the layer hides the other end.
+     */
+    readonly inverse?: string;
+    /**
+     * The scalar fields of this Resource that hold the relation's reference, in the
+     * order the data source pairs them with the target's key (`Post.category` has
+     * `["categoryId"]`). Writing the relation and one of them in one record names
+     * the reference twice; inside a record written through the relation's other
+     * end they sit at the `"loopback"` position with it. Absent on the end that
+     * holds no reference, and where the layer shows none of them.
+     */
+    readonly referenceFields?: readonly [string, ...string[]];
+    /**
+     * `true` when the policy engine's `governed` set names the relation: including
+     * it on rows the caller may not read it on refuses the request.
+     */
+    readonly governed?: true;
 };
 /** One field of a Resource: a scalar or a relation. */
 export type AvField<C extends AvContract> = AvScalarField<C> | AvRelationField<C>;
+/**
+ * A relation field as the Core Contract states it: an {@link AvRelationField}
+ * and, on the end that holds the reference, the target's fields it names.
+ */
+export type AvCoreRelationField<C extends AvContract> = AvRelationField<C> & {
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in the
+     * same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`). Present only beside a `referenceFields` the
+     * Contract states whole, and only when every one of them is a scalar field
+     * the Core Contract shows on the target; absent on the end that holds no
+     * reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
+};
+/** One field of a Resource as the Core Contract states it. */
+export type AvCoreField<C extends AvContract> = AvScalarField<C> | AvCoreRelationField<C>;

package/dist/contracts/json-schema.projector.d.ts

@@ -0,0 +1,11 @@
+type Schema = {
+    readonly [key: string]: unknown;
+};
+/**
+ * `value` projected onto `schema` (the `json` field subset): every object down
+ * to the members the schema declares, a list member by member, frozen.
+ *
+ * @throws TypeError when the value is not one the schema describes.
+ */
+export declare function projectJsonValue(value: unknown, schema: Schema): unknown;
+export {};

package/dist/contracts/json-schema.projector.js

@@ -0,0 +1,76 @@
+import { isRecord } from "../runtime/record.guard.js";
+function memberSchema(schema) {
+    if (!isRecord(schema)) {
+        throw new TypeError("the schema is not one of the forms a ClientContract states");
+    }
+    return schema;
+}
+function fits(value, schema) {
+    if (Object.hasOwn(schema, "const")) {
+        return value === schema.const;
+    }
+    if (Array.isArray(schema.enum)) {
+        return schema.enum.includes(value);
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const options = schema[keyword];
+        if (Array.isArray(options)) {
+            return options.some((option) => fits(value, option));
+        }
+    }
+    switch (schema.type) {
+        case "null":
+            return value === null;
+        case "boolean":
+            return typeof value === "boolean";
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number";
+        case "integer":
+            return Number.isInteger(value);
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return isRecord(value);
+        default:
+            return false;
+    }
+}
+export function projectJsonValue(value, schema) {
+    if (!fits(value, schema)) {
+        throw new TypeError("the value is not the one the ClientContract describes");
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const options = schema[keyword];
+        if (Array.isArray(options)) {
+            const option = options.find((candidate) => fits(value, candidate));
+            return projectJsonValue(value, option);
+        }
+    }
+    if (Array.isArray(value)) {
+        const prefix = schema.prefixItems;
+        const items = Array.isArray(prefix)
+            ? undefined
+            : memberSchema(schema.items);
+        return Object.freeze(value.map((member, index) => projectJsonValue(member, items ?? memberSchema(prefix[index]))));
+    }
+    if (isRecord(value)) {
+        const properties = schema.properties;
+        if (isRecord(properties)) {
+            const copy = {};
+            for (const [key, member] of Object.entries(properties)) {
+                if (Object.hasOwn(value, key) && value[key] !== undefined) {
+                    copy[key] = projectJsonValue(value[key], member);
+                }
+            }
+            return Object.freeze(copy);
+        }
+        const values = memberSchema(schema.additionalProperties);
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, member]) => [
+            key,
+            projectJsonValue(member, values),
+        ])));
+    }
+    return value;
+}

package/dist/contracts/scalar-value-type.d.ts

@@ -78,5 +78,7 @@ type ListValue<List, Atom> = [List] extends [false] ? Atom : [List] extends [tru
  * - `list: true` → `readonly T[]`, whose entries are never `null`;
  * - `nullable: true` → `| null`, on the whole value, list or not.
  */
-export type AvScalarValueType<C extends AvContract, Field extends AvScalarField<C>, Forms extends ScalarForms = AvApplicationScalarForms> = ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never);
+export type AvScalarValueType<C extends AvContract, Field extends AvScalarField<C>, Forms extends ScalarForms = AvApplicationScalarForms> = [
+    ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never)
+] extends [infer Value] ? Value : never;
 export {};

package/dist/framework/access-facade.d.ts

@@ -0,0 +1,116 @@
+import type { AvContract } from "../contracts/contract.js";
+import type { AvApplicationScalarForms } from "../contracts/scalar-value-type.js";
+import type { AvResourceKey, AvUniqueWhereInput } from "../operations/operation-arguments.js";
+import type { AvAccessProvider } from "../policy/access-provider.interface.js";
+import type { AvAccessQuestion } from "../policy/access-question.js";
+import type { AccessQuestionsAnswerer } from "../policy/access-question.runtime.js";
+import type { AvAccessVerbs } from "../policy/access-verbs.js";
+import type { AvState } from "../runtime/request-state.js";
+/** The questions a client of `C` may ask: one per Resource, with its own unique `where` in the application forms. */
+export type AccessQuestionOf<C extends AvContract> = C extends AvContract ? {
+    readonly [R in AvResourceKey<C>]: AvAccessQuestion<R, AvUniqueWhereInput<C, R, AvApplicationScalarForms>>;
+}[AvResourceKey<C>] : never;
+/** The headers a server-side `$access` call hands Access: a Web `Headers`, or a Node request's `headers`. */
+type AccessHeadersInput = {
+    get(name: string): string | null;
+    has(name: string): boolean;
+    forEach(callback: (value: string, name: string) => void): void;
+} | {
+    readonly [name: string]: string | readonly string[] | undefined;
+};
+/** A server-side `$access` call's options. */
+type ServerAccessOptions = {
+    /** As `AvExecutionOptions.requestId`: `can`'s request id. */
+    readonly requestId?: string;
+    /**
+     * As `AvExecutionOptions.state`: the state `can` is answered under. Left out,
+     * `can` is answered under the state the provider seeds from `headers`, or
+     * anonymously without them.
+     */
+    readonly state?: AvState & object;
+    /**
+     * The request's headers, which Access reads the session from: a Web
+     * `Headers`, or a Node request's `headers` (`req.headers`). Omitted, none.
+     */
+    readonly headers?: AccessHeadersInput;
+    /** The host's own request, handed to Access as `state` is. */
+    readonly request?: unknown;
+    /**
+     * The host's own response (Express's `res`, Fastify's `reply`): Access sets
+     * a sign-in's or sign-out's cookie on it. Under Next, a Server Action needs
+     * none: Access sets it through Next's `cookies()`.
+     */
+    readonly response?: unknown;
+};
+/** What a verb's `call` resolves, `null` and `undefined` taken out. */
+type CallResult<Verb> = Verb extends {
+    call(input: never): Promise<infer Result>;
+} ? Exclude<Result, null | undefined> : unknown;
+/** The `args` a verb's `call` reads. */
+type CallArgs<Verb> = Verb extends {
+    call(input: infer Input): Promise<unknown>;
+} ? Input extends {
+    readonly args: infer Args;
+} ? Args : unknown : unknown;
+/** The provider's `client`, when its type states one. */
+type ClientOf<A> = A extends {
+    readonly client: infer Client;
+} ? Exclude<Client, undefined> : never;
+/** The verbs a provider's `verbs` type states as present (an optional one is no verb). */
+type PresentVerbs<Verbs> = {
+    [V in keyof Verbs]-?: undefined extends Verbs[V] ? never : V;
+}[keyof Verbs] & ProviderVerbName;
+/** The verbs a provider's `client` may state. */
+type ProviderVerbName = keyof NonNullable<AvAccessProvider["client"]>["verbs"];
+/** `$access` of a client of `C` whose provider is `A`: `can`, and the verbs its `client` offers. */
+type ServerAccess<C extends AvContract, A> = [ClientOf<A>] extends [never] ? Pick<AvAccessVerbs<AccessQuestionOf<C>, never, {
+    signIn: never;
+    signUp: never;
+    resetPassword: never;
+    switchUser: never;
+    setPin: never;
+    enrollDevice: never;
+    revokeDevice: never;
+}, ServerAccessOptions>, "can"> : ClientOf<A> extends {
+    readonly verbs: infer Verbs;
+} ? Pick<AvAccessVerbs<AccessQuestionOf<C>, CallResult<VerbOf<Verbs, "me">>, {
+    signIn: CallArgs<VerbOf<Verbs, "signIn">>;
+    signUp: CallArgs<VerbOf<Verbs, "signUp">>;
+    resetPassword: CallArgs<VerbOf<Verbs, "resetPassword">>;
+    switchUser: CallArgs<VerbOf<Verbs, "switchUser">>;
+    setPin: CallArgs<VerbOf<Verbs, "setPin">>;
+    enrollDevice: CallArgs<VerbOf<Verbs, "enrollDevice">>;
+    revokeDevice: CallArgs<VerbOf<Verbs, "revokeDevice">>;
+}, ServerAccessOptions>, "can" | PresentVerbs<Verbs>> : never;
+/** One verb of a provider's `verbs` type, or `never` when it states none. */
+type VerbOf<Verbs, V extends string> = V extends keyof Verbs ? Exclude<Verbs[V], undefined> : never;
+/** The configuration's `access` provider; `undefined` without one. */
+export type AccessProviderOf<Cfg> = Cfg extends {
+    readonly access: infer A extends AvAccessProvider;
+} ? A : undefined;
+/**
+ * `framework.serverClient`'s `$access` member over the Client Contract's view
+ * `C`: `{ $access }` with `access`, nothing (`unknown`) without it.
+ */
+export type ServerClientAccess<C, A> = [A] extends [undefined] ? unknown : C extends AvContract ? {
+    /**
+     * The policy's answers for the UI (`can`) and, when the provider
+     * states its `client`, the Aventara Access verbs, each run in
+     * process with the headers the call names.
+     */
+    readonly $access: ServerAccess<C, A>;
+} : unknown;
+/** What `$access` reads off the Framework. */
+type ServerClientAccessDependencies = {
+    /** The Client Contract, whose unique `where`s a question's is encoded by. */
+    readonly contract: AvContract;
+    /** The `can` route's answerer. */
+    readonly answer: AccessQuestionsAnswerer;
+    /** The provider's `client`, when it has one. */
+    readonly client: AvAccessProvider["client"];
+    /** The provider's `state`, called on the provider: `can`'s state from a call's `headers`. */
+    readonly state: AvAccessProvider["state"];
+};
+/** A server-side `$access`, as `serverClient` carries it. */
+export declare function createServerClientAccess(dependencies: ServerClientAccessDependencies): object;
+export {};