@aventara/core 1.0.0-rc.4 → 1.0.0-rc.9

package/dist/operations/operation-arguments.d.ts

@@ -114,7 +114,7 @@ type FieldSlotReferences<C extends AvContract, K extends AvResourceKey<C>, F ext
  * operand but `mode`, `isEmpty`, `path` and the `json` ones may be a `$ref` of
  * the shape it holds (`References`).
  */
-type ScalarFilterOperands<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator, Mode extends ScalarFilterMode, PathMode extends ScalarFilterMode, LevelMode extends ScalarFilterMode> = {
+export type AvScalarFilterOperands<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator, Mode extends ScalarFilterMode, PathMode extends ScalarFilterMode, LevelMode extends ScalarFilterMode> = {
     equals: Value | References["value"];
     not: NegatedValue<Value, References, Operator> | ScalarFilterOperators<Value, Atom, Json, References, Operator, Mode, PathMode>;
     in: readonly Atom[] | References["entries"];
@@ -149,8 +149,8 @@ type ScalarFilterOperands<Value, Atom, Json, References extends Readonly<Record<
 type ScalarFilterOperators<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator, Mode extends ScalarFilterMode, PathMode extends ScalarFilterMode> = ScalarFilterLevel<ReadonlyOperands<Value, Atom, Json, References, Operator, Mode, PathMode, Mode>, Operator, Mode, NegatedValue<Value, References, Operator>, "path" extends Operator ? {
     readonly path?: never;
 } : unknown> | ("path" extends Operator ? ScalarFilterOperatorsAtPath<ReadonlyOperands<Value, Atom, Json, References, Operator, Mode, PathMode, PathMode>, Operator, PathMode, NegatedValue<Value, References, Operator>> : never);
-/** {@link ScalarFilterOperands}, each operand read-only. */
-type ReadonlyOperands<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator, Mode extends ScalarFilterMode, PathMode extends ScalarFilterMode, LevelMode extends ScalarFilterMode> = Readonly<ScalarFilterOperands<Value, Atom, Json, References, Operator, Mode, PathMode, LevelMode>>;
+/** {@link AvScalarFilterOperands}, each operand read-only. */
+type ReadonlyOperands<Value, Atom, Json, References extends Readonly<Record<TransactionSlotShape, unknown>>, Operator extends AvScalarFilterOperator, Mode extends ScalarFilterMode, PathMode extends ScalarFilterMode, LevelMode extends ScalarFilterMode> = Readonly<AvScalarFilterOperands<Value, Atom, Json, References, Operator, Mode, PathMode, LevelMode>>;
 /** The operators of a level that compare something: all but `mode` and `path`. */
 type ComparingOperator<Operator extends AvScalarFilterOperator> = Exclude<Operator, "mode" | "path">;
 /** `not`'s value arm: equality negated, offered only where `equals` is. */
@@ -224,7 +224,7 @@ export type AvWhereInput<C extends AvContract, K extends AvResourceKey<C>, Forms
     AND?: readonly AvWhereInput<C, K, Forms, ReferenceForms>[];
     OR?: readonly AvWhereInput<C, K, Forms, ReferenceForms>[];
     NOT?: AvWhereInput<C, K, Forms, ReferenceForms>;
-} & ScalarWhereFields<C, K, Forms, ReferenceForms> & RelationWhereFields<C, K, Forms, ReferenceForms>>;
+}> & ScalarWhereFields<C, K, Forms, ReferenceForms> & RelationWhereFields<C, K, Forms, ReferenceForms>;
 type ActiveIdentifier<C extends AvContract, K extends AvResourceKey<C>> = C["resources"][K]["identifiers"][number];
 type IdentifierObject<C extends AvContract, K extends AvResourceKey<C>, I extends readonly string[], Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     [F in Extract<I[number], AvFieldKey<C, K>>]: ScalarValueAt<C, K, F, Forms> | SlotReference<C, K, F, ReferenceForms, "nonNullValue">;
@@ -356,18 +356,18 @@ type ManyOrOne<C extends AvContract, K extends AvResourceKey<C>, F extends Relat
  * A `where` of plain fields: each scalar field's filter, combined with
  * `AND`/`OR`/`NOT`, and no relation filter at any depth.
  */
-type ScalarOnlyWhereInput<C extends AvContract, K extends AvResourceKey<C>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
-    AND?: readonly ScalarOnlyWhereInput<C, K, Forms, ReferenceForms>[];
-    OR?: readonly ScalarOnlyWhereInput<C, K, Forms, ReferenceForms>[];
-    NOT?: ScalarOnlyWhereInput<C, K, Forms, ReferenceForms>;
-} & ScalarWhereFields<C, K, Forms, ReferenceForms>>;
+export type AvScalarWhereInput<C extends AvContract, K extends AvResourceKey<C>, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never> = Readonly<{
+    AND?: readonly AvScalarWhereInput<C, K, Forms, ReferenceForms>[];
+    OR?: readonly AvScalarWhereInput<C, K, Forms, ReferenceForms>[];
+    NOT?: AvScalarWhereInput<C, K, Forms, ReferenceForms>;
+}> & ScalarWhereFields<C, K, Forms, ReferenceForms>;
 /**
  * The `where` of a nested `$update` or `$delete` through relation `F`: plain fields
  * only where the relation states `nestedWriteFilter: "scalar"`, any filter otherwise.
  */
 type NestedWriteWhereInput<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = CapabilitiesOf<C, K, F> extends {
     readonly nestedWriteFilter: "scalar";
-} ? ScalarOnlyWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> : AvWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
+} ? AvScalarWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> : AvWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
 type ConnectOrCreateEntry<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     where: AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>;
     create: AvCreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms, readonly [K, F]>;
@@ -397,15 +397,14 @@ type ToManyUpsertEntry<C extends AvContract, K extends AvResourceKey<C>, F exten
     update: AvUpdateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms, readonly [K, F]>;
 }>;
 type RelationDirectiveValue<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Directive extends AvRelationMutationDirective, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Directive extends "$create" ? ManyOrOne<C, K, F, AvCreateDataInput<C, RelationTarget<C, K, F>, UnrestrictedWrite, Forms, ReferenceForms, readonly [K, F]>> : Directive extends "$connect" ? ManyOrOne<C, K, F, AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>> : Directive extends "$connectOrCreate" ? ManyOrOne<C, K, F, ConnectOrCreateEntry<C, K, F, Forms, ReferenceForms>> : Directive extends "$disconnect" ? RelationCardinality<C, K, F> extends "one" ? true : AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> | readonly AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>[] : Directive extends "$set" ? RelationCardinality<C, K, F> extends "one" ? AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms> | null : readonly AvUniqueWhereInput<C, RelationTarget<C, K, F>, Forms, ReferenceForms>[] : Directive extends "$update" ? RelationCardinality<C, K, F> extends "one" ? ToOneUpdateEntry<C, K, F, Forms, ReferenceForms> : ManyOrOne<C, K, F, ToManyUpdateEntry<C, K, F, Forms, ReferenceForms>> : Directive extends "$delete" ? RelationCardinality<C, K, F> extends "one" ? ToOneDeleteEntry<C, K, F, Forms, ReferenceForms> : ManyOrOne<C, K, F, ToManyDeleteEntry<C, K, F, Forms, ReferenceForms>> : Directive extends "$upsert" ? RelationCardinality<C, K, F> extends "one" ? ToOneUpsertEntry<C, K, F, Forms, ReferenceForms> : ManyOrOne<C, K, F, ToManyUpsertEntry<C, K, F, Forms, ReferenceForms>> : never;
-declare const NO_ADVERTISED_MEMBER: unique symbol;
 /**
  * A write member that advertises nothing: it accepts `{}` and refuses every key.
  */
-type NoAdvertisedMember = {
-    readonly [NO_ADVERTISED_MEMBER]?: never;
-};
-/** `Write`, or {@link NoAdvertisedMember} when `Write` has no keys at all. */
-type RefuseEveryKeyWhenEmpty<Write> = [keyof Write] extends [never] ? NoAdvertisedMember : Write;
+export interface AvNoAdvertisedMember {
+    readonly [Symbol.unscopables]?: never;
+}
+/** `Write`, or {@link AvNoAdvertisedMember} when `Write` has no keys at all. */
+type RefuseEveryKeyWhenEmpty<Write> = [keyof Write] extends [never] ? AvNoAdvertisedMember : Write;
 type RelationMutationActionFor<C extends AvContract, K extends AvResourceKey<C>, F extends RelationFieldKeyOf<C, K>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = RefuseEveryKeyWhenEmpty<Readonly<Partial<{
     [Directive in Extract<CapabilityTokens<C, K, F, Stage, Scope>, AvRelationMutationDirective>]: RelationDirectiveValue<C, K, F, Directive, Forms, ReferenceForms>;
 }>>>;
@@ -432,14 +431,23 @@ type OneDirective<Tokens extends AvScalarMutationDirective, C extends AvContract
 /**
  * Each writable scalar takes its value under `Forms`, or a directive object of
  * the directives it advertises at this stage — or, in a transaction plan's
- * top-level data, a `$ref` to a source of the same type.
- */
-type ScalarMutationFields<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms, Via extends ParentEdge = never> = Readonly<{
-    [F in Exclude<WritableScalarKey<C, K, Stage, Scope>, LoopbackRefused<C, K, Stage, Via>>]?: ScalarValueAt<C, K, F, Forms> | ScalarMutationActionFor<C, K, F, Stage, Scope, Forms> | SlotReference<C, K, F, ReferenceForms, "value">;
-}>;
-type RelationMutationFields<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms, Via extends ParentEdge = never> = Readonly<{
-    [F in Exclude<WritableRelationKey<C, K, Stage, Scope>, LoopbackRefused<C, K, Stage, Via>>]?: RelationMutationActionFor<C, K, F & RelationFieldKeyOf<C, K>, Stage, Scope, Forms, ReferenceForms>;
-}>;
+ * top-level data, a `$ref` to a source of the same type. A field a create must
+ * write (`RequiredWriteKey`) is required.
+ */
+type ScalarMutationFields<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms, Via extends ParentEdge = never, Keys extends AvFieldKey<C, K> = Exclude<WritableScalarKey<C, K, Stage, Scope>, LoopbackRefused<C, K, Stage, Via>>, Required extends Keys = Extract<Keys, RequiredWriteKey<C, K, Stage, Scope, Via>>> = Readonly<([Required] extends [never] ? unknown : {
+    [F in Required]: ScalarValueAt<C, K, F, Forms> | ScalarMutationActionFor<C, K, F, Stage, Scope, Forms> | SlotReference<C, K, F, ReferenceForms, "value">;
+}) & ([Exclude<Keys, Required>] extends [never] ? unknown : {
+    [F in Exclude<Keys, Required>]?: ScalarValueAt<C, K, F, Forms> | ScalarMutationActionFor<C, K, F, Stage, Scope, Forms> | SlotReference<C, K, F, ReferenceForms, "value">;
+})>;
+/**
+ * Each writable relation takes the directive object it advertises at this
+ * stage. A relation a create must write (`RequiredWriteKey`) is required.
+ */
+type RelationMutationFields<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms, Via extends ParentEdge = never, Keys extends AvFieldKey<C, K> = Exclude<WritableRelationKey<C, K, Stage, Scope>, LoopbackRefused<C, K, Stage, Via>>, Required extends Keys = Extract<Keys, RequiredWriteKey<C, K, Stage, Scope, Via>>> = Readonly<([Required] extends [never] ? unknown : {
+    [F in Required]: RelationMutationActionFor<C, K, F & RelationFieldKeyOf<C, K>, Stage, Scope, Forms, ReferenceForms>;
+}) & ([Exclude<Keys, Required>] extends [never] ? unknown : {
+    [F in Exclude<Keys, Required>]?: RelationMutationActionFor<C, K, F & RelationFieldKeyOf<C, K>, Stage, Scope, Forms, ReferenceForms>;
+})>;
 /** A relation edge a nested create is reached through: `[parent, relation]`. */
 type ParentEdge = readonly [string, string];
 /** The other end of `Via`'s relation, as the Contract pairs it; `never` when it does not. */
@@ -497,13 +505,21 @@ type GroupPresence<Group, Scalars, Relations, Supplied> = Group extends readonly
 }) : Present<Relation> : Present<References[number]> : unknown : unknown;
 /** Every group of a `oneOf` tuple, each one's presence intersected. */
 type GroupsPresence<Groups, Scalars, Relations, Supplied> = Groups extends readonly [infer Group, ...infer Rest] ? GroupPresence<Group, Scalars, Relations, Supplied> & GroupsPresence<Rest, Scalars, Relations, Supplied> : unknown;
+/**
+ * The names a create of `K` at `Scope` must write: every `required` name it can
+ * write there, less what the parent supplies through `Via`. `never` for an
+ * update, and where the Contract states nothing.
+ */
+type RequiredWriteKey<C extends AvContract, K extends AvResourceKey<C>, Stage extends "create" | "update", Scope extends AvWriteScope, Via> = Stage extends "create" ? [CreateRequirementsAt<C, K>] extends [never] ? never : CreateRequirementsAt<C, K> extends infer Requirements ? string extends RequirementNames<Requirements, "required"> ? never : Exclude<Extract<RequirementNames<Requirements, "required">, WritableScalarKey<C, K, "create", Scope> | WritableRelationKey<C, K, "create", Scope>>, SuppliedThrough<Requirements, Via>> : never : never;
+/** The members a create's two halves hold at `Scope`, reached through `Via`. */
+type HeldCreateKey<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope, Via> = Exclude<WritableScalarKey<C, K, "create", Scope> | WritableRelationKey<C, K, "create", Scope>, LoopbackRefused<C, K, "create", Via>>;
 /**
  * What a create of Resource `K` at write position `Scope` must and must not
  * write: every `required` name it can write, and one side of every `oneOf`
  * group — less what the parent supplies when the create is nested through
  * `Via`. `unknown` (no constraint) when the Contract states nothing.
  */
-type CreateRequirementPresence<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope, Via> = [CreateRequirementsAt<C, K>] extends [never] ? unknown : CreateRequirementsAt<C, K> extends infer Requirements ? string extends RequirementNames<Requirements, "required"> ? unknown : Present<Exclude<Extract<RequirementNames<Requirements, "required">, WritableScalarKey<C, K, "create", Scope> | WritableRelationKey<C, K, "create", Scope>>, SuppliedThrough<Requirements, Via>>> & (Requirements extends {
+type CreateRequirementPresence<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope, Via> = [CreateRequirementsAt<C, K>] extends [never] ? unknown : CreateRequirementsAt<C, K> extends infer Requirements ? string extends RequirementNames<Requirements, "required"> ? unknown : Present<Exclude<RequiredWriteKey<C, K, "create", Scope, Via>, HeldCreateKey<C, K, Scope, Via>>> & (Requirements extends {
     readonly oneOf?: infer Groups;
 } ? GroupsPresence<Groups, WritableScalarKey<C, K, "create", Scope>, WritableRelationKey<C, K, "create", Scope>, SuppliedThrough<Requirements, Via>> : unknown) : unknown;
 /**
@@ -518,12 +534,12 @@ type CreateRequirementPresence<C extends AvContract, K extends AvResourceKey<C>,
  * reference fields — never both. `Via` is the `[parent, relation]` a nested
  * create is reached through: what that parent supplies is not required.
  */
-export type AvCreateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never, Via extends ParentEdge = never> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "create", Scope, Forms, ReferenceForms, Via> & RelationMutationFields<C, K, "create", Scope, Forms, ReferenceForms, Via>>> & CreateRequirementPresence<C, K, Scope, Via>;
+export type AvCreateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never, Via extends ParentEdge = never> = RefuseEveryKeyWhenEmpty<ScalarMutationFields<C, K, "create", Scope, Forms, ReferenceForms, Via>> & RefuseEveryKeyWhenEmpty<RelationMutationFields<C, K, "create", Scope, Forms, ReferenceForms, Via>> & CreateRequirementPresence<C, K, Scope, Via>;
 /**
  * An `update` data argument, at one write position. See {@link AvCreateDataInput};
  * `Via` is the `[parent, relation]` a nested update is reached through.
  */
-export type AvUpdateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never, Via extends ParentEdge = never> = RefuseEveryKeyWhenEmpty<Readonly<ScalarMutationFields<C, K, "update", Scope, Forms, ReferenceForms, Via> & RelationMutationFields<C, K, "update", Scope, Forms, ReferenceForms, Via>>>;
+export type AvUpdateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = UnrestrictedWrite, Forms extends ScalarForms = UnstatedForms, ReferenceForms extends ScalarForms = never, Via extends ParentEdge = never> = RefuseEveryKeyWhenEmpty<ScalarMutationFields<C, K, "update", Scope, Forms, ReferenceForms, Via>> & RefuseEveryKeyWhenEmpty<RelationMutationFields<C, K, "update", Scope, Forms, ReferenceForms, Via>>;
 type QueryProjectionArgs<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvProjectionScope, Forms extends ScalarForms> = ProjectionChoice<C, K, Scope, false, Forms>;
 /**
  * Every standard operation's argument object, with each argument at its

package/dist/operations/operation-call.d.ts

@@ -56,7 +56,7 @@ export type AvOperationSlot<I extends AvOperationIdentity, Result> = I["variant"
 /** What a direct call resolves: the slot, every failure thrown. */
 type Settled<I extends AvOperationIdentity, Result> = AvOperationSlot<I, Result>;
 /** A direct call that projects: generic in its `select`/`include` literal. */
-export type ProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
+export type ProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: CallArgumentList<Omit<Args, ProjectionKey>, NoInfer<Omit<Args, ProjectionKey>> & ProjectionArgument<Select, Include>, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>>;
 /** A direct call that does not project. */
 export type PlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Options> = (...args: CallArgumentList<Args, Args, Options>) => Promise<Settled<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>>;
 /**
@@ -72,7 +72,7 @@ export type AvOperationCall<C extends AvContract, R extends AvResourceKey<C>, I
  */
 export type DeferredArguments<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ResultForms extends ScalarForms> = ReferenceableArgumentsFor<C, R, I, Forms, ResultForms>;
 /** A deferred operation that projects: generic in its `select`/`include` literal. */
-export type DeferredProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, Omit<Args, ProjectionKey> & ProjectionArgument<Select, Include>>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>, Origin>;
+export type DeferredProjectingCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = <const Select extends SelectOf<Args> = never, const Include extends IncludeOf<Args> = never>(...args: ArgumentList<Omit<Args, ProjectionKey>, NoInfer<Omit<Args, ProjectionKey>> & ProjectionArgument<Select, Include>>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, InferredProjection<Select, Include>, ResultForms>>, Origin>;
 /** A deferred operation that does not project. */
 export type DeferredPlainCall<C extends AvContract, R extends AvResourceKey<C>, I extends AvOperationIdentity, Args, ResultForms extends ScalarForms, Origin extends HandleOrigin> = (...args: ArgumentList<Args, Args>) => AvOperation<AvOperationSlot<I, AdmittedOperationResult<C, R, I, unknown, ResultForms>>, Origin>;
 /**

package/dist/operations/operation-result.d.ts

@@ -35,7 +35,7 @@ type EntryArguments<Entry, F extends string> = Entry extends object ? Entry exte
  */
 type ProjectedFields<C extends AvContract, K extends AvResourceKey<C>, Keys extends AvFieldKey<C, K>, Entries, Forms extends ScalarForms> = {
     readonly [F in Keys]: FieldOf<C, K, F> extends AvScalarField<C> ? AvScalarValueType<C, FieldOf<C, K, F>, Forms> : FieldOf<C, K, F> extends AvRelationField<C> ? RelationResult<C, Extract<FieldOf<C, K, F>["target"], AvResourceKey<C>>, FieldOf<C, K, F>, EntryArguments<Entries, F>, Forms> : never;
-};
+} extends infer Fields ? Fields : never;
 /**
  * One projection level: `select` returns exactly its entries, `include` the
  * default fields plus the named relations, and no projection the default fields.

package/dist/policy/access-provider.interface.d.ts

@@ -0,0 +1,36 @@
+import type { AvState } from "../runtime/request-state.js";
+import type { AvPolicyEngine } from "./policy-engine.js";
+/**
+ * What the framework's `access` option takes: the policy engine every client
+ * and agent request is checked against, and how a request's state is seeded.
+ * Aventara Access provides one; one written by hand works the same way.
+ *
+ * The request's principal is `ctx.$state.me` (`null` when it is absent), so
+ * `state` names it as `me`. With `access`, the configuration states no
+ * `policy`, and the host no `state` of its own.
+ */
+export interface AvAccessProvider {
+    /** The policy engine (`AvPolicyEngine`), asked about every client and agent request. */
+    readonly policy: AvPolicyEngine;
+    /**
+     * Seeds a request's `ctx.$state` from its headers (a Web `Headers`): `me`, the principal the
+     * policy is asked about (`null` for an anonymous caller), and anything else
+     * the stages read. Called once per request by the host. `request` is the
+     * host's own request when it has one: Express's `req`, Fastify's
+     * `request`, or the Next.js route handler's `Request`. A throw is answered
+     * like any developer failure: a thrown `AvError` as its own outcome,
+     * anything else as an internal failure.
+     */
+    state(input: {
+        readonly headers: {
+            get(name: string): string | null;
+            has(name: string): boolean;
+            forEach(callback: (value: string, name: string) => void): void;
+        };
+        readonly request?: unknown;
+    }): (AvState & {
+        readonly me: unknown;
+    }) | Promise<AvState & {
+        readonly me: unknown;
+    }>;
+}

package/dist/policy/access-provider.interface.js

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

package/dist/policy/access-provider.registry.d.ts

@@ -0,0 +1,9 @@
+import type { AvAccessProvider } from "./access-provider.interface.js";
+/** Records the provider `framework` was configured with; called once, at construction. */
+export declare function recordAccessProvider(framework: object, access: AvAccessProvider | undefined): void;
+/**
+ * The `state` of the provider `framework` was configured with (`access`),
+ * called on the provider; `undefined` for a Framework without `access`, or a
+ * value that is no constructed Framework.
+ */
+export declare function accessStateOf(framework: object): AvAccessProvider["state"] | undefined;

package/dist/policy/access-provider.registry.js

@@ -0,0 +1,10 @@
+const ACCESS_PROVIDERS = new WeakMap();
+export function recordAccessProvider(framework, access) {
+    if (access !== undefined) {
+        ACCESS_PROVIDERS.set(framework, access);
+    }
+}
+export function accessStateOf(framework) {
+    const access = ACCESS_PROVIDERS.get(framework);
+    return access === undefined ? undefined : (input) => access.state(input);
+}

package/dist/policy/policy-admission.js

@@ -232,7 +232,10 @@ export async function admitByPolicy(session, core, active, request, args) {
         ...named.used.keys(),
         ...named.nodes.map((node) => node.resource),
     ]);
-    const answers = new Map(await Promise.all([...resources].map(async (resource) => [resource, await session.fields(resource, "read")])));
+    const answers = new Map(await Promise.all([...resources].map(async (resource) => [
+        resource,
+        await session.fields(resource, { access: "read" }),
+    ])));
     const conditional = new Map();
     for (const [resource, fields] of named.used) {
         const answer = answers.get(resource);
@@ -300,7 +303,6 @@ async function admitNestedRecords(session, core, resource, directives) {
     if (!isRecord(directives)) {
         return undefined;
     }
-    const fields = await session.fields(resource, "write");
     const owner = lookupResource(core, resource);
     for (const [directive, operand] of Object.entries(directives)) {
         if (!isRelationMutationDirective(directive)) {
@@ -312,6 +314,10 @@ async function admitNestedRecords(session, core, resource, directives) {
                 if (!isRecord(record)) {
                     continue;
                 }
+                const fields = await session.fields(resource, {
+                    access: "write",
+                    action: site.stage,
+                });
                 for (const [field, value] of Object.entries(record)) {
                     if (value === undefined) {
                         continue;
@@ -343,10 +349,13 @@ export async function admitWriteByPolicy(session, core, request, args) {
         return undefined;
     }
     const resource = request.resource;
-    const fields = await session.fields(resource, "write");
     const grants = [];
     const names = [];
     for (const { record, stage } of records) {
+        const fields = await session.fields(resource, {
+            access: "write",
+            action: stage,
+        });
         for (const [field, value] of Object.entries(record)) {
             if (value === undefined) {
                 continue;

package/dist/policy/policy-after-update.runtime.js

@@ -1,8 +1,9 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { frozenCopy } from "../runtime/readonly-value.js";
 import { policyRefusal } from "./policy-admission.js";
 import { allOf, whereOf } from "./policy-condition.js";
-import { identifiedRows, identifierOf } from "./policy-read.runtime.js";
+import { identifiedRows } from "./policy-read.runtime.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -48,7 +49,7 @@ function touches(core, model, resource, scope, data) {
                 }
             }
             else {
-                for (const member of identifierOf(model, resource)) {
+                for (const member of adapterPrimaryIdentifier(model, resource)) {
                     read.add(member);
                 }
             }
@@ -82,7 +83,7 @@ function identityKey(identifier, row) {
 export function afterCheckFields(core, model, resource) {
     return listOf(core, `after\u0000${resource}`, () => [
         ...new Set([
-            ...identifierOf(model, resource),
+            ...adapterPrimaryIdentifier(model, resource),
             ...rowFieldsOf(core, resource),
         ]),
     ]);
@@ -101,7 +102,7 @@ export async function checkChanged(session, core, model, resource, checks, chang
         return undefined;
     }
     const fresh = session.renewed();
-    const identifier = identifierOf(model, resource);
+    const identifier = adapterPrimaryIdentifier(model, resource);
     const these = identifiedRows(core, identifier, resource, changed);
     if (these === false) {
         return undefined;

package/dist/policy/policy-engine.d.ts

@@ -97,11 +97,18 @@ export interface AvPolicyEngine<Governed extends {
      * may use on every row it can reach (`"all"`: every field that is not
      * governed); `perRow` maps a field it may use only on some rows to the
      * condition those rows meet. A field in neither is refused (`A4002`)
-     * wherever the request names it.
+     * wherever the request names it. A write question names the `action` the
+     * fields are written by, `"create"` or `"update"` (an upsert's branches
+     * each by their own), so a field may be locked on update and still written
+     * at create.
      */
-    fieldsOf(question: PolicyQuestion & {
-        readonly access: "read" | "write";
-    }): PolicyAnswer<{
+    fieldsOf(question: PolicyQuestion & ({
+        readonly access: "read";
+        readonly action?: undefined;
+    } | {
+        readonly access: "write";
+        readonly action: "create" | "update";
+    })): PolicyAnswer<{
         readonly always: "all" | readonly string[];
         readonly perRow: {
             readonly [field: string]: AvPolicyWhere | undefined;

package/dist/policy/policy-nested-write.runtime.js

@@ -1,10 +1,11 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { isRelationMutationDirective } from "../runtime/mutation-planner.js";
 import { frozenCopy } from "../runtime/readonly-value.js";
 import { policyRefusal } from "./policy-admission.js";
 import { afterUpdate, checkChanged, rowFieldsOf, } from "./policy-after-update.runtime.js";
 import { allOf, noneOf, someOf, whereOf, } from "./policy-condition.js";
-import { identifiedRows, identifierOf } from "./policy-read.runtime.js";
+import { identifiedRows } from "./policy-read.runtime.js";
 import { fieldAccess } from "./policy-session.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -106,14 +107,17 @@ class NestedWalk {
         return undefined;
     }
     identifier(resource) {
-        const identifier = identifierOf(this.model, resource);
+        const identifier = adapterPrimaryIdentifier(this.model, resource);
         if (identifier.length === 0) {
             throw new NestedRefusal(`The policy checks the rows a nested write reaches in Resource "${resource}" by identifier, and the Resource has none.`);
         }
         return identifier;
     }
-    async grantsOf(resource, records) {
-        const fields = await this.session.fields(resource, "write");
+    async grantsOf(resource, records, action) {
+        const fields = await this.session.fields(resource, {
+            access: "write",
+            action,
+        });
         const grants = new Map();
         for (const record of records) {
             for (const [name, value] of Object.entries(record)) {
@@ -333,7 +337,7 @@ class NestedWalk {
                     ? false
                     : identifiedRows(this.core, identifier, resource, rows);
         }
-        const grants = await this.grantsOf(resource, [data]);
+        const grants = await this.grantsOf(resource, [data], "update");
         if (grants.length > 0) {
             this.ask(resource, "fields", allOf(reach, someOf(grants.map(noneOf))));
         }
@@ -369,7 +373,7 @@ class NestedWalk {
         const before = there === false
             ? []
             : await this.session.rows(resource, whereOf(there), identifier);
-        const grants = await this.grantsOf(resource, records);
+        const grants = await this.grantsOf(resource, records, "create");
         const inner = await this.level(resource, { kind: "new" }, records);
         return async (parents) => {
             if (parents.length === 0) {
@@ -415,7 +419,7 @@ async function checkCreatedRows(session, core, identifier, resource, grants, row
 export async function planNestedWrites(session, core, model, resource, record, parent) {
     const walk = new NestedWalk(session, core, model);
     try {
-        const identifier = identifierOf(model, resource);
+        const identifier = adapterPrimaryIdentifier(model, resource);
         if (identifier.length === 0) {
             throw new NestedRefusal(`The policy checks the rows a nested write reaches by identifier, and Resource "${resource}" has none.`);
         }

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

@@ -59,8 +59,6 @@ export type PolicyRootRows = {
     readonly carried?: readonly string[];
 };
 type Row = Readonly<Record<string, unknown>>;
-/** The Resource's identifier as the adapter states it first (its primary key). */
-export declare function identifierOf(model: AvAdapterModel, resource: string): readonly string[];
 /**
  * One read's policy (see the module comment): what the adapter runs, and the
  * checks its answer goes through; or the empty answer when the read reaches no

package/dist/policy/policy-read.runtime.js

@@ -1,3 +1,4 @@
+import { adapterPrimaryIdentifier } from "../adapters/adapter-identifier.js";
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { policyRefusal } from "./policy-admission.js";
 import { allOf, anyOf, everyOf, noneOf, someOf, } from "./policy-condition.js";
@@ -11,12 +12,6 @@ function relationOf(core, resource, name) {
         ? field
         : undefined;
 }
-export function identifierOf(model, resource) {
-    const resources = model.resources;
-    return ((Object.hasOwn(resources, resource)
-        ? resources[resource]?.identifiers?.[0]
-        : undefined) ?? []);
-}
 function innerFilters(relation, value) {
     return relation.cardinality === "many"
         ? [value.some, value.every, value.none]
@@ -192,6 +187,12 @@ function emptyRelationValue(select) {
         ? { data: [], count: 0 }
         : { count: 0 };
 }
+function scopedCursor(cursor, scope) {
+    if (!isRecord(cursor) || typeof scope === "boolean") {
+        return cursor;
+    }
+    return { ...cursor, AND: [scope] };
+}
 function withIdentifier(select, identifier) {
     const missing = identifier.filter((member) => !select.includes(member));
     return missing.length === 0 ? select : [...select, ...missing];
@@ -210,6 +211,7 @@ export async function enforceReadPolicy(session, core, model, request, plan, ada
     const checks = await returnedRowChecks(session, core, plan);
     let identity = request;
     let rootWhere = args.where;
+    let rootCursor = args.cursor;
     const scope = rows === undefined ? scoped.scope(root) : rows.scope;
     if (scope === undefined) {
     }
@@ -251,6 +253,7 @@ export async function enforceReadPolicy(session, core, model, request, plan, ada
             };
         }
         rootWhere = where === true ? undefined : where;
+        rootCursor = scopedCursor(args.cursor, scope);
     }
     const rewriteLevel = (resource, select, level) => {
         const entries = [];
@@ -289,6 +292,9 @@ export async function enforceReadPolicy(session, core, model, request, plan, ada
                 else {
                     rewritten.where = where;
                 }
+                if (value.cursor !== undefined) {
+                    rewritten.cursor = scopedCursor(value.cursor, scoped.scope(relation.target));
+                }
             }
             const inner = rewriteLevel(relation.target, value.select, nestedLevel);
             nested.set(name, inner);
@@ -303,7 +309,7 @@ export async function enforceReadPolicy(session, core, model, request, plan, ada
             : [];
         return {
             select: withIdentifier(checked
-                ? withIdentifier(entries, identifierOf(model, resource))
+                ? withIdentifier(entries, adapterPrimaryIdentifier(model, resource))
                 : entries, carried),
             emptied,
             nested,
@@ -320,6 +326,9 @@ export async function enforceReadPolicy(session, core, model, request, plan, ada
     else {
         runArguments.where = rootWhere;
     }
+    if (rootCursor !== undefined) {
+        runArguments.cursor = rootCursor;
+    }
     if (Array.isArray(args.select)) {
         runArguments.select = rewritten.select;
     }
@@ -353,7 +362,7 @@ export async function returnedRowChecks(session, core, plan) {
         if (level === undefined) {
             return;
         }
-        const fields = await session.fields(level.resource, "read");
+        const fields = await session.fields(level.resource, { access: "read" });
         const conditions = [];
         if (reachedOne) {
             const scope = await session.scope(level.resource, "read");
@@ -461,7 +470,7 @@ async function rowsReadable(session, core, model, projection, checks, data) {
         if (miss === true) {
             return true;
         }
-        const identifier = identifierOf(model, level.resource);
+        const identifier = adapterPrimaryIdentifier(model, level.resource);
         const reach = allOf(identifiedRows(core, identifier, level.resource, rows), miss);
         return (reach !== false &&
             session.exists(level.resource, reach === true ? {} : reach));

package/dist/policy/policy-request.d.ts

@@ -1,3 +1,4 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvAdapterOperationExecutor } from "../adapters/adapter-operation-executor.interface.js";
 import type { ResolvedPolicyConfig } from "../config/config.resolver.js";
 import type { AvRequestOrigin } from "../config/config-layer.js";
@@ -19,13 +20,16 @@ export type PolicyCaller = {
 export declare function callerOf(options: unknown): PolicyCaller | undefined;
 /**
  * The policy session of one request, or `undefined` when the policy does not
- * check it. Deriving the principal is server code: a throw is the caller's
- * to answer as the server's defect.
+ * check it; a promise of it when the principal arrives as one. Deriving the
+ * principal is server code: a throw, or a rejection, is the caller's to answer
+ * as the server's defect.
  */
 export declare function openRequestPolicy(policy: ResolvedPolicyConfig | undefined, core: AvContractCore, request: {
     readonly origin: AvRequestOrigin;
     readonly state: AvState;
-}, caller: PolicyCaller | undefined, executor: AvAdapterOperationExecutor): PolicySession | undefined;
+}, caller: PolicyCaller | undefined, adapter: AvAdapterOperationExecutor & {
+    readonly model: AvAdapterModel;
+}): PolicySession | undefined | Promise<PolicySession | undefined>;
 /**
  * Policy admission inside its own boundary, as the Framework Validation Layer's
  * is: a refusal, a defect of the engine or its answers (`A3000`), or an adapter

package/dist/policy/policy-request.js

@@ -14,7 +14,12 @@ export function callerOf(options) {
     }
     return principal === undefined ? undefined : { principal };
 }
-export function openRequestPolicy(policy, core, request, caller, executor) {
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+export function openRequestPolicy(policy, core, request, caller, adapter) {
     if (policy === undefined) {
         return undefined;
     }
@@ -30,9 +35,15 @@ export function openRequestPolicy(policy, core, request, caller, executor) {
             $state: request.state,
             $origin: request.origin,
         });
+        if (isThenable(principal)) {
+            return Promise.resolve(principal).then((settled) => sessionOf(policy, core, request.origin, adapter, settled));
+        }
     }
-    return openPolicySession(policy, core, principal, request.origin, {
-        executor,
+    return sessionOf(policy, core, request.origin, adapter, principal);
+}
+function sessionOf(policy, core, origin, adapter, principal) {
+    return openPolicySession(policy, core, adapter.model, principal, origin, {
+        executor: adapter,
         boundary: new AdapterBoundary(),
     });
 }

package/dist/policy/policy-session.d.ts

@@ -1,10 +1,17 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvAdapterOperationExecutor } from "../adapters/adapter-operation-executor.interface.js";
 import type { ResolvedPolicyConfig } from "../config/config.resolver.js";
 import type { AvRequestOrigin } from "../config/config-layer.js";
 import type { AvContractCore } from "../contracts/contract.js";
 import type { AdapterBoundary } from "../runtime/error-boundary.js";
 import type { PolicyCondition } from "./policy-condition.js";
-import type { AvPolicyWhere } from "./policy-engine.js";
+import type { AvPolicyEngine, AvPolicyWhere } from "./policy-engine.js";
+/**
+ * What `fieldsOf` is asked about, beside the question every method states:
+ * reading, or writing by one action. Read from the engine's own signature,
+ * which writes the union inline (see `AvPolicyEngine.fieldsOf`).
+ */
+export type PolicyFieldsAccess = Parameters<AvPolicyEngine["fieldsOf"]>[0] extends infer Question ? Question extends unknown ? Pick<Question, Extract<keyof Question, "access" | "action">> : never : never;
 /** An action a policy question names. */
 export type PolicyAction = "read" | "create" | "update" | "delete";
 /** `fieldsOf`'s answer, held: the names read into sets once. */
@@ -39,8 +46,11 @@ export type PolicySession = {
     can(resource: string, action: PolicyAction, row?: Readonly<Record<string, unknown>>): Promise<boolean>;
     /** The rows the principal may `action` (`scopeOf`), checked. */
     scope(resource: string, action: "read" | "update" | "delete"): Promise<PolicyCondition>;
-    /** The fields the principal may read or write (`fieldsOf`), checked. */
-    fields(resource: string, access: "read" | "write"): Promise<PolicyFields>;
+    /**
+     * The fields the principal may read, or write by one action (`fieldsOf`),
+     * checked.
+     */
+    fields(resource: string, access: PolicyFieldsAccess): Promise<PolicyFields>;
     /** Whether a row of `resource` meets `where`: core's own question, unchecked. */
     exists(resource: string, where: AvPolicyWhere): Promise<boolean>;
     /**
@@ -70,7 +80,7 @@ export type PolicySession = {
  * Opens the policy session of one request: `principal` under `origin`, its
  * `exists` on `execution` until {@link PolicySession.on} moves it.
  */
-export declare function openPolicySession(policy: ResolvedPolicyConfig, core: AvContractCore, principal: unknown, origin: AvRequestOrigin, execution: PolicyExecution): PolicySession;
+export declare function openPolicySession(policy: ResolvedPolicyConfig, core: AvContractCore, model: AvAdapterModel, principal: unknown, origin: AvRequestOrigin, execution: PolicyExecution): PolicySession;
 /**
  * Whether `fields` lets the principal use `field` of `resource` on every row it
  * reaches: listed in `always`, or covered by `"all"` when it is not governed.