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

package/CHANGELOG.md

@@ -1,5 +1,162 @@
 # @aventara/core
 
+## 1.0.0-rc.9
+
+### Patch Changes
+
+- 205a379: `createFramework` takes `access`, an access provider: the policy engine and the request state from one object.
+  `AvAccessProvider` is the new main-entry type it is written against, with two members:
+
+  - `policy`: the engine every client and agent request is checked against, as `policy.engine` takes it.
+  - `state({ headers, request })`: seeds each request's `ctx.$state`. Its `me` is the principal the engine is asked
+    about, `null` for an anonymous caller.
+
+  Aventara Access provides one, and a hand-written provider works the same way (a till's PIN sign-in, say: see the
+  README). The host calls `state` once per request; server code that calls the Framework directly passes the state
+  itself. A governed field of the provider's engine is left out of the default projection's type, as with `policy`.
+  `access` together with `policy` is refused at startup (`CONFIG_INVALID_VALUE` at `policy`) and is a type error at
+  `policy`. A provider whose `policy` is no engine or whose `state` is no function is refused at startup, member by
+  member, and the engine's `governed`, `paths` and `afterChecks` are checked against the Core Contract under
+  `access.policy`. A prebuilt Contracts file counts the provider by its engine's governed set alone.
+
+- a0bb05e: A Framework's `diagnostics` sink receives every report when the process holds more than one copy of `@aventara/core`
+  (Next.js giving each layer its own copy, a duplicate install, a monorepo). A protocol failure such as a result with no
+  wire form (`500 A3003`), or an MCP endpoint failure, raised through another copy than the one that built the Framework
+  now reaches the sink instead of being silently dropped. Copies of one major version share the sinks; nothing in the
+  public API or its types changed.
+- 86ab319: Values and errors from `@aventara/core` are recognized across duplicate copies of the package in one process. A
+  bundler that gives each layer its own copy (Next.js instrumentation, route handlers and pages), a duplicate install, a
+  monorepo, Vite SSR, per-function bundles and test runners' module isolation all load core more than once.
+
+  - A decimal made by one copy is an `AvDecimal` to every other: `value instanceof AvDecimal` is `true`, the protocol
+    encodes it (a `find.many` selecting a decimal no longer answers `500 A3003` "Result serialization failed"), and a
+    Framework accepts it in arguments, `$sql` values and Adapter results.
+  - `AvError` and its subclasses (`AvValidationError`, `AvNotFoundError`, `AvConflictError`, `AvAuthError`,
+    `AvInternalError`, `AvProtocolError`, `AvContractMismatchError`), `AvConstructionError`,
+    `AvTransactionIntegrityError` and `AvTransactionSlotPathError` pass `instanceof` across copies, with the same
+    subclass rules: every one is an `AvError`, and each is only its own subclass. An `AvError` a pipeline throws with
+    another copy's class is answered as the outcome it names. A subclass you declare yourself is checked as before.
+  - Copies recognize each other within one major version only. Nothing in the public API or its types changed.
+
+- fdf52e6: `framework.serverClient` and `framework.serverClientTx`: the client layer for server code, called with application
+  values, such as a Next.js Server Component's.
+
+  - `framework.serverClient.<Resource>.<family>.<variant>(args, options?)` is typed from the Client Contract's view, as
+    `framework.client` is: what the client layer hides is absent. Its arguments are the application forms (`Date`,
+    `bigint`, `AvDecimal`, `Uint8Array`), the ones `framework.application` takes, and their wire strings are type errors.
+    Its results are `framework.client`'s. At runtime a value already in its wire form is accepted too, as
+    `framework.client` reads it.
+  - Each call copies its arguments, encodes the copy into the wire forms against the Client Contract, and runs the request
+    `framework.client` would run for those wire forms: the same client pipelines, validation, exposure and policy, the
+    same answers and the same `AvError` classes. `framework.client` itself is unchanged and keeps the wire forms.
+  - `framework.serverClientTx` builds client-origin transaction handles from application values. One
+    `framework.transaction([...])` may hold them beside `clientTx` handles, never beside `appTx` ones.
+  - New main-entry type names: `AvServerClientFacade`, `AvServerClientResourceFacade`, `AvServerClientFamilyFacade`,
+    `AvServerClientProjectingCall`, `AvServerClientPlainCall`, `AvServerClientTxFacade`,
+    `AvServerClientTxResourceFacade`, `AvServerClientTxFamilyFacade`, `AvServerClientTxProjectingCall`,
+    `AvServerClientTxPlainCall`.
+
+## 1.0.0-rc.8
+
+1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- 1c8e4ee: Helpers typed off the façades compile again in projects that emit declarations. In 1.0.0-rc.7 a function that took
+  `Parameters<AppFramework["application"]["Post"]["find"]["many"]>[0]` and returned its `where` (or built a new one
+  from it, `{ AND: [args.where ?? {}, { published: { equals: true } }] }`) without a return type failed `nest build`
+  (and `tsc` with `"declaration": true`) with `TS4023: ... has or is using name 'ScalarFilterOperands' ... but cannot be
+  named`, usually beside `TS7056`. A nested write's data could fail the same way, or name `NO_ADVERTISED_MEMBER`, and a
+  nested `$update`'s `where` was written into the `.d.ts` as `any`. The declaration now names the argument types
+  `@aventara/core` exports (`AvWhereInput`, `AvUpdateDataInput`, `AvCreateDataInput`, ...), and these new exports cover
+  the rest:
+
+  - `AvScalarFilterOperands`: one field's filter operators, which a filter's `not` holds again.
+  - `AvScalarWhereInput`: the `where` of a nested `$update` or `$delete` that only takes plain fields.
+  - `AvNoAdvertisedMember`: a write member that advertises nothing; it takes `{}` and refuses every key.
+  - `AvSqlStatementBuilder` and `AvSqlStatementValue`: the type of `framework.appTx.$sql` and the values it binds.
+    A method returning `framework.appTx.$sql` failed with `TS2883`/`TS2742` before.
+
+  `framework.execute` and `framework.executeTransaction` take request types that `@aventara/core` exports:
+  `AvOperationRequest` (`AvApplicationOperationRequest`, `AvClientOperationRequest`, `AvAgentOperationRequest`),
+  `AvTransactionRequest` (`AvApplicationTransactionRequest`, `AvClientTransactionRequest`,
+  `AvAgentTransactionRequest`) and `AvRequestProtocol` (a remote request's `protocol`). They were named from
+  `@aventara/core/internal` (`FrameworkOperationRequest`, `FrameworkTransactionRequest`, ...), so a declaration that
+  spelled them reached into the package's internal entry. Those names are gone from `@aventara/core/internal`.
+
+  An adapter's `referentialActions` edges name the fields that hold the reference `referenceFields`, as a relation of
+  the Core Contract does. They were called `references`, which the Core Contract uses for the target's fields.
+
+  Reading a projecting variant's argument type (`Parameters<…["find"]["many"]>[0]`) also type-checks faster: about
+  6,000 type instantiations over a three-field model, where rc.7 took about 29,000. The part of the argument other than
+  `select`/`include` is now marked `NoInfer` in the call's parameter, so an editor shows that parameter as
+  `NoInfer<Omit<…>> & …`. What it accepts is unchanged.
+
+  A create's `data` type now states each required field once, as a required member (`Readonly<{ title: string; } & {
+  body?: ... }>` in an editor's expanded hover). Before, a required field appeared as an optional member beside a
+  separate `{ readonly title: WrittenValue }`, and a declaration file wrote both. What a create accepts and refuses is
+  unchanged.
+
+- Operation results read as their value types in an editor and in emitted declarations. A result field that is nullable,
+  an enum or a `boolean` (such as a `Boolean @default(false)` column) was shown as `AvScalarValueType<…>`, with the
+  whole Contract view as its argument, and a project with `"declaration": true` wrote that view into its `.d.ts` once
+  per such field: a Nest service of five methods with no return types came out at 524 lines. Those fields now read
+  `body: string | null`, `published: boolean`, `publishedAt: Date | null`, and that service's declaration is 44 lines.
+  A result, and a relation included in it, is shown as its fields rather than as `ProjectedFields<…>`. This covers
+  `framework.application` and `framework.client` results, the same fields in a write's `data`, and clients generated
+  by `avclient`. What each type accepts is unchanged.
+
+## 1.0.0-rc.7
+
+1.0.0-rc.5 and 1.0.0-rc.6 were tagged but never published; 1.0.0-rc.7 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- f917c1c: A helper that reads `framework.contracts.core` compiles again in projects that emit declarations. In 1.0.0-rc.6 a
+  function returning a Resource or a field of the Core Contract without a return type, such as
+  `core.resources[resource]?.fields[relation]`, failed `nest build` (and `tsc` with `"declaration": true`, which Nest's
+  `tsconfig.json` sets) with `TS2883: The inferred type of 'relationOf' cannot be named without a reference to
+  'AvCoreField'` under TypeScript 6 (`TS2742` under 5.9), or with `TS4058`/`TS4023` naming `AvCoreResource`.
+  `@aventara/core` now exports the three types the Core Contract is written with: `AvCoreResource` (a Resource),
+  `AvCoreField` (one of its fields) and `AvCoreRelationField` (a relation field, with the target fields its reference
+  names in `references`).
+
+  A policy's startup check states the path once: `CONFIG_INVALID_VALUE at policy.engine.governed.Nope: "Nope" is no
+  Resource of the Core Contract`, where rc.6 repeated `policy.engine.governed.Nope:` inside the message. Each
+  diagnostic's `message` no longer starts with its `path`; read the path from `path`.
+
+## 1.0.0-rc.6
+
+1.0.0-rc.5 was tagged but never published. 1.0.0-rc.6 contains everything listed under 1.0.0-rc.5 and the fix below.
+
+### Patch Changes
+
+- 1cf72e0: Typed policy engines compile again in projects that emit declarations. In 1.0.0-rc.5 an engine written
+  `as const satisfies AvPolicyEngine` failed `nest build` (and `tsc` with `"declaration": true`, which Nest's
+  `tsconfig.json` sets) with `TS2883: The inferred type of 'policyEngine' cannot be named without a reference to
+  'PolicyFieldsAccess'` under TypeScript 6, or `TS2742` under 5.9, and so did the configuration and the framework holding
+  it. `fieldsOf`'s question is now written out in full in `AvPolicyEngine`, so a declaration can spell it.
+
+  A read question's `action` is now typed `undefined`, so an engine can destructure it from either question:
+  `fieldsOf({ resource, access, action })`. A write question's `action` is `"create"` or `"update"`, as before.
+
+## 1.0.0-rc.5
+
+### Patch Changes
+
+- 4795ff1: Two additions for policy engines. A Framework without a policy, and every Contract a caller is served, are unchanged.
+
+  - A policy engine can check a create whose row reaches another Resource through a relation. Discovery now states, on the end of a relation that holds the reference, which of the target's fields its reference fields name, pair by pair (`Note.campaign`: `referenceFields: ["campaignId"]`, `references: ["id"]`). An engine reads them from the model it is built from (a Prisma discovery artifact's `model`) or from `framework.contracts.core`, and asks one `exists` about the row they name: "a player creates a note only in a campaign they play in". Only the adapter's model and the Core Contract carry them. The Application, Client and Agent Contracts, `/_contract`, the MCP tools and every ClientContract hash are unchanged. The discovery artifact's model hash, and so a prebuilt Contracts file's fingerprint, change: regenerate the artifact and rebuild the prebuilt file.
+  - `fieldsOf({ access: "write" })` also names the action that writes the record, `action: "create" | "update"` (an upsert's branches each their own, a nested record its directive's), so an engine can lock a field on update and still let a create write it. A read question names none. An engine that ignores it keeps working.
+
+- 9e178ca: Fixes for applications that check requests with a policy engine. A Framework without a policy behaves as before.
+
+  - A cursor on a row the caller cannot read is answered exactly as a cursor on a row that does not exist, at the root and in a to-many relation, whatever values the caller sends beside the identifier. Before, the page started at the hidden row, so it told that the row exists and where its values sort. The Prisma adapter reads the cursor's row under the read scope first: one statement more for a cursor on a readable row, and only that read for one on a row the caller cannot read.
+  - A unique update with a nested write (`$create`, `$connect`, …) on a row the caller can read but not change answers `A4002`, as the same update without one does. It answered `A2003`. A row the caller cannot read still answers `A2003`.
+  - The `exists` questions a policy asks select the Resource's primary identifier, never another unique field such as a governed `email`.
+  - `policy.principal` may answer with a promise. A synchronous principal works as before; a rejection answers `A3000`, as a throw does.
+  - `AvConstructionError.message` names the first problem and how many more there are, for example `Aventara framework configuration validation failed: CONFIG_INVALID_TYPE at adapter.execute: adapter.execute must be a function (+2 more)`. `stage` and `diagnostics` are unchanged.
+
 ## 1.0.0-rc.4
 
 ### Patch Changes

package/ERRORS.md

@@ -1,6 +1,6 @@
 # Aventara error codes
 
-Every code `@aventara/core` 1.0.0-rc.4 answers, reports in a validation issue, or refuses to start with. Generated from `AvErrorCatalog` (exported by `@aventara/core`); do not edit.
+Every code `@aventara/core` 1.0.0-rc.9 answers, reports in a validation issue, or refuses to start with. Generated from `AvErrorCatalog` (exported by `@aventara/core`); do not edit.
 
 Branch on the code, never on the message. In code, `AvErrorCatalog[code]` gives the same entry: `{ code, kind, message, cause, fix, docs }`.
 
@@ -134,7 +134,7 @@ Each entry of `cause.issues[]` under `A2001`, `A2002`, `A2004`, `A2007` or `A200
 | [`COMPILER_INVALID_LIFECYCLE`](https://aventara-framework.vercel.app/docs/error-codes#compiler_invalid_lifecycle) | Invalid field lifecycle. | An added field declares a lifecycle other than VIRTUAL, a VIRTUAL field claims a database-generated lifecycle or a provider-side capability, or a definition redefines a discovered field's lifecycle. | Give an added field lifecycle: ["VIRTUAL"] and only the capabilities it can serve; computed lifecycles come from compute stages. |
 | [`COMPILER_MISSING_READ_COMPUTE`](https://aventara-framework.vercel.app/docs/error-codes#compiler_missing_read_compute) | A selectable virtual field has no compute.read. | A VIRTUAL field that can be selected has no pipelines.compute.read stage. | Add a compute.read stage, or make the field write-only with capabilities.select: false. |
 | [`COMPILER_INVALID_COMPUTE_DEPENDENCY`](https://aventara-framework.vercel.app/docs/error-codes#compiler_invalid_compute_dependency) | Invalid compute.read dependency. | A dependsOn entry that is not a stored scalar field of the same Resource. | List only stored scalar fields of the Resource in dependsOn. |
-| [`COMPILER_RESERVED_RESOURCE_NAME`](https://aventara-framework.vercel.app/docs/error-codes#compiler_reserved_resource_name) | Reserved Resource name. | A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref). | Rename the model; the table it maps to can keep its name. |
+| [`COMPILER_RESERVED_RESOURCE_NAME`](https://aventara-framework.vercel.app/docs/error-codes#compiler_reserved_resource_name) | Reserved Resource name. | A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref), or, on a host that adds members beside the Resources, is one of those members' names (on Next.js: tx and transaction on avClient, appTx and transaction on avApp). | Rename the model; the table it maps to can keep its name. A host member's name is also left free when the layer it belongs to hides the Resource. |
 | [`COMPILER_MISSING_IDENTIFIER`](https://aventara-framework.vercel.app/docs/error-codes#compiler_missing_identifier) | A unique operation has no identifier. | A layer exposes a unique variant (find.unique, update.unique, delete.unique, upsert.unique) and no complete identifier of the Resource: a Pick that did not pick one, or an Omit that hid every one. | Expose an identifier field (id, or every field of one unique), or exempt the unique variants. |
 | [`COMPILER_HIDDEN_REQUIRED_FIELD`](https://aventara-framework.vercel.app/docs/error-codes#compiler_hidden_required_field) | A layer that creates a Resource hides a required field. | A layer still creates the Resource (a create or upsert variant, or a nested create) while a required field, or a required relation's reference field, is hidden or has its create capability exempted, and no compute.create fills it. | Expose the field, give it a compute.create stage, or exempt the layer's create operations. |
 | [`COMPILER_INVALID_VALIDATOR`](https://aventara-framework.vercel.app/docs/error-codes#compiler_invalid_validator) | A field validator cannot apply. | A validator that is not built with AvZ, does not fit the field's type (AvZ.maxLength on an int, AvZ.maxItems on a field that is not a list), or sits on a relation or Json field. | Use an AvZ check that fits the field's type; a Json field's checks go in its json shape. |

package/README.md

@@ -118,6 +118,27 @@ try {
 generated client throws the same classes by the same table. `framework.execute` and `framework.executeTransaction`, the
 entries a transport calls, still answer the envelope.
 
+## The client layer, called with your own values
+
+`framework.client` reads its arguments in the wire forms a decoded request body carries: a `datetime` is its ISO string,
+a `bigint` its base-10 string. That suits a test that should behave like a remote caller. Server code that acts for a
+remote caller, such as a Server Component or a Server Action, holds `Date`s and `bigint`s instead. It calls
+`framework.serverClient`:
+
+```ts
+const recent = await framework.serverClient.Post.find.many({
+  where: { createdAt: { gt: new Date(Date.now() - 86_400_000) } },
+  select: ["id", "title"],
+});
+```
+
+`serverClient` has the client layer's types and rules: what the client layer hides is absent, and the client
+pipelines, validation, exposure and policy run. Its arguments are the application forms (`Date`, `bigint`,
+`AvDecimal`, `Uint8Array`), the same ones `framework.application` takes, and its results are `framework.client`'s.
+Each call copies its arguments, encodes them into the wire forms and runs the request `framework.client` would run.
+`framework.serverClientTx` builds client-layer transaction handles the same way; one `framework.transaction([...])`
+may hold them beside `clientTx` handles, never beside `appTx` ones.
+
 ## Every code, explained
 
 `AvErrorCatalog` holds every code this package answers, reports in a validation issue, or refuses to start with: its
@@ -199,15 +220,15 @@ findMany(): import("@aventara/core").AvApplicationProjectingCall<
   "Post", { readonly family: "find"; readonly variant: "many" }>;
 ```
 
-The names, one set per surface (`application`, `client`, `appTx`, `clientTx`):
+The names, one set per surface (`application`, `client`, `serverClient`, `appTx`, `clientTx`, `serverClientTx`):
 
 | Node | `framework.application` | the others |
 | --- | --- | --- |
-| the whole surface | `AvApplicationFacade` | `AvClientFacade`, `AvAppTxFacade`, `AvClientTxFacade` |
+| the whole surface | `AvApplicationFacade` | `AvClientFacade`, `AvServerClientFacade`, `AvAppTxFacade`, `AvClientTxFacade`, `AvServerClientTxFacade` |
 | one Resource | `AvApplicationResourceFacade` | `AvClientResourceFacade`, … |
 | one family | `AvApplicationFamilyFacade` | `AvClientFamilyFacade`, … |
-| a variant that takes a `select` or `include` | `AvApplicationProjectingCall` | `AvClientProjectingCall`, `AvAppTxProjectingCall`, `AvClientTxProjectingCall` |
-| a variant that does not (the `count` variants: `find.count`, `update.count`, …) | `AvApplicationPlainCall` | `AvClientPlainCall`, `AvAppTxPlainCall`, `AvClientTxPlainCall` |
+| a variant that takes a `select` or `include` | `AvApplicationProjectingCall` | `AvClientProjectingCall`, `AvServerClientProjectingCall`, `AvAppTxProjectingCall`, `AvClientTxProjectingCall`, `AvServerClientTxProjectingCall` |
+| a variant that does not (the `count` variants: `find.count`, `update.count`, …) | `AvApplicationPlainCall` | `AvClientPlainCall`, `AvServerClientPlainCall`, `AvAppTxPlainCall`, `AvClientTxPlainCall`, `AvServerClientTxPlainCall` |
 
 Each takes the view, `AvContractView`, as its first argument. The view's arguments are your model by its name, the root's
 and the overlay's exposure as written, and the `fields` entries your configuration's `resources` blocks hold. A
@@ -230,8 +251,8 @@ never with the model the inline stages were typed from.
 
 ## Server-side calls copy their input
 
-`framework.application`, `framework.client`, `framework.execute`, `framework.executeTransaction`, and the `appTx` /
-`clientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
+`framework.application`, `framework.client`, `framework.serverClient`, `framework.execute`,
+`framework.executeTransaction`, and the `appTx` / `clientTx` / `serverClientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
 Validation, your guards and pipes, computed values and the adapter all see only the copy, and your stages see it
 frozen: only a pipe changes the arguments, by returning new ones, so what the validators checked is what the adapter
 writes. In practice:
@@ -357,7 +378,11 @@ projection; name it to get it, `select: ["$defaults", "email"]`. A refusal answe
 Writes are checked too. A create asks `can` about each new row, whose rules may look rows up through `exists`. An
 update or delete acts only on rows the caller may change and read; a single-row one that misses answers `A4002` when
 the caller can read the row and `A2003` when it cannot. A field the write sends must be in
-`fieldsOf({ access: "write" })`. An update that moves a row out of what the caller reads, or fails an `after` condition
+`fieldsOf({ access: "write", action })`, `action` being `"create"` or `"update"` (an upsert's branches and a nested
+record's directive each their own), so a field can be locked on update and still written at create. A rule that
+reaches another Resource through a relation (a note only in a campaign its author plays in) reads which of the
+target's fields the reference names from the Core Contract (`framework.contracts.core`, a relation's `references`
+beside its `referenceFields`); no Contract a caller is served states them. An update that moves a row out of what the caller reads, or fails an `after` condition
 (`can` asked about the row the update returned), is rolled back. Where `transactionsStyle` is `"interactive"`, a
 checked write with a check after it (an update, a nested write) runs in a transaction of its own, and a create or
 delete checked before it runs is one statement; where it is `"none"`, a write that could only be checked after it runs
@@ -370,6 +395,54 @@ caller may change or delete, as `update.many` does. After the call, every row th
 (the after check, the move-out re-read), and every row they created is read back as stored and asked `can`; one refusal
 rolls the whole write back. Where `transactionsStyle` is `"none"`, a nested write under a policy is refused.
 
+## An access provider
+
+`access` takes the policy engine and the request state from one object, an `AvAccessProvider`. Aventara Access
+provides one, and you can write your own. It has two members:
+
+- `policy`: the engine, as `policy.engine` takes it.
+- `state({ headers, request })`: seeds each request's `ctx.$state`. Its `me` is the principal the engine is asked
+  about (`null` for an anonymous caller).
+
+The host calls `state` once per request: `@aventara/nest` with the platform request's headers and the request itself,
+`@aventara/next` with the request's headers (and the route's `Request` on a route call). With `access`, leave out
+`policy` and the host's own `state` option; either one beside it is refused at startup, and as a type error where the
+configuration's type shows both. Server code that calls the Framework directly passes the state itself,
+`{ state: await access.state({ headers }) }`.
+
+A point-of-sale till with its own PIN sign-in, written by hand:
+
+```ts
+import type { AvAccessProvider } from "@aventara/core";
+
+type Cashier = { id: string; role: "cashier" | "manager" };
+
+declare module "@aventara/core" {
+  interface AvState {
+    me?: Cashier | null;
+  }
+}
+
+export const tillAccess = {
+  // The till sends the PIN the cashier typed as `x-pos-pin`.
+  state: async ({ headers }) => ({ me: await cashierByPin(headers.get("x-pos-pin")) }),
+  policy: {
+    can: ({ principal, resource, action }) => {
+      const me = principal as Cashier | null;
+      if (me === null) return false; // no PIN, no till
+      if (resource === "Refund" && action !== "read") return me.role === "manager";
+      return true;
+    },
+    scopeOf: () => true,
+    fieldsOf: () => ({ always: "all", perRow: {} }),
+  },
+} satisfies AvAccessProvider;
+
+const framework = await createFramework({ api: "/api", adapter, access: tillAccess });
+```
+
+Every stage reads the cashier as `ctx.$state.me`, typed by the `AvState` declaration above.
+
 ## License
 
 PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you

package/dist/adapters/adapter-field.d.ts

@@ -38,6 +38,14 @@ export type AvAdapterRelationField<M extends AvAdapterModel> = {
      * one. Absent on the end that holds no reference (`User.posts`); never empty.
      */
     readonly referenceFields?: readonly [string, ...string[]];
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in
+     * the same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`, so `Post.authorId` holds `User.id`). Stated only
+     * beside `referenceFields`, with as many entries; absent on the end that
+     * holds no reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
 };
 /** One field the adapter discovered: a scalar or a relation. */
 export type AvAdapterField<M extends AvAdapterModel> = AvAdapterScalarField<M> | AvAdapterRelationField<M>;

package/dist/adapters/adapter-identifier.d.ts

@@ -13,3 +13,12 @@ export type AvAdapterIdentifier<TFields extends Readonly<Record<string, AvAdapte
     AvAdapterScalarFieldKey<TFields>,
     ...AvAdapterScalarFieldKey<TFields>[]
 ];
+/**
+ * The Resource's identifier as the Adapter states it first: in the Adapter's
+ * own order (an ORM adapter's is its schema's, so the primary key). The Core
+ * Contract sorts identifiers for its hash, so its first one is the
+ * alphabetically first (`email` before `id`) and says nothing about which is
+ * the primary key; the model keeps the order it declared. Empty for a Resource
+ * the model does not hold or that has no identifier.
+ */
+export declare function adapterPrimaryIdentifier(model: AvAdapterModel, resource: string): readonly string[];

package/dist/adapters/adapter-identifier.js

@@ -1 +1,6 @@
-export {};
+export function adapterPrimaryIdentifier(model, resource) {
+    const resources = model.resources;
+    return ((Object.hasOwn(resources, resource)
+        ? resources[resource]?.identifiers?.[0]
+        : undefined) ?? []);
+}

package/dist/adapters/adapter-operation.d.ts

@@ -6,12 +6,18 @@ import type { AvAdapterModel } from "./adapter-model.js";
  * Operation identity and arguments remain provider-neutral; adapters receive
  * only validated semantic argument objects, never raw transport input.
  *
- * One shape exists here only: the flat unique selector of an `update.unique` or
- * a `delete.unique` may carry `AND`, a list of conditions in the general
- * `where` grammar the selected row must also meet. A row the selector names
- * that misses them is a miss (the same `null` as a row that is not there). An
- * adapter must honour it or refuse the operation, never drop it: dropping it
- * would write a row the conditions exclude.
+ * Two shapes exist here only, both an `AND`: a list of conditions in the
+ * general `where` grammar the addressed row must also meet.
+ *
+ * - The flat unique selector of an `update.unique` or a `delete.unique` may
+ *   carry it. A row the selector names that misses them is a miss (the same
+ *   `null` as a row that is not there).
+ * - A `cursor` may carry it, at the root of a `find.many` and in a to-many
+ *   relation's arguments. A row the cursor names that misses them is a cursor
+ *   that names no row: the same answer as a cursor on a row that is not there.
+ *
+ * An adapter must honour it or refuse the operation, never drop it: dropping it
+ * would write a row the conditions exclude, or position a page at one.
  */
 export type AvAdapterOperation<M extends AvAdapterModel = AvAdapterModel> = AvOperationIdentity & {
     readonly resource: Extract<keyof M["resources"], string>;

package/dist/compiler/contract-compiler-diagnostic.guidance.js

@@ -66,8 +66,8 @@ export const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE = {
     },
     COMPILER_RESERVED_RESOURCE_NAME: {
         message: "Reserved Resource name.",
-        cause: "A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref).",
-        fix: "Rename the model; the table it maps to can keep its name.",
+        cause: "A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref), or, on a host that adds members beside the Resources, is one of those members' names (on Next.js: tx and transaction on avClient, appTx and transaction on avApp).",
+        fix: "Rename the model; the table it maps to can keep its name. A host member's name is also left free when the layer it belongs to hides the Resource.",
     },
     COMPILER_MISSING_IDENTIFIER: {
         message: "A unique operation has no identifier.",

package/dist/compiler/contract.compiler.js

@@ -81,15 +81,28 @@ function cloneAdapterField(field) {
         ...(Array.isArray(field.referenceFields) && field.referenceFields.length > 0
             ? { referenceFields: [...field.referenceFields] }
             : {}),
+        ...(Array.isArray(field.referenceFields) &&
+            Array.isArray(field.references) &&
+            field.references.length > 0 &&
+            field.references.length === field.referenceFields.length
+            ? { references: [...field.references] }
+            : {}),
     };
 }
-function pruneHiddenPairings(projection) {
+function pruneHiddenPairings(projection, references) {
     const resources = projection.resources;
     for (const [name, resource] of Object.entries(resources)) {
         for (const field of Object.values(resource.fields)) {
             if (field.kind !== "relation") {
                 continue;
             }
+            if (Array.isArray(field.references) &&
+                (references === "none" ||
+                    !wholePairing(resource.fields, Object.hasOwn(resources, String(field.target))
+                        ? resources[String(field.target)]?.fields
+                        : undefined, field.referenceFields, field.references))) {
+                delete field.references;
+            }
             if (Array.isArray(field.referenceFields)) {
                 const shown = field.referenceFields.filter((reference) => typeof reference === "string" &&
                     Object.hasOwn(resource.fields, reference) &&
@@ -113,6 +126,16 @@ function pruneHiddenPairings(projection) {
         }
     }
 }
+function wholePairing(fields, targetFields, referenceFields, references) {
+    const shownIn = (within, name) => typeof name === "string" &&
+        within !== undefined &&
+        Object.hasOwn(within, name) &&
+        within[name]?.kind === "scalar";
+    return (Array.isArray(referenceFields) &&
+        referenceFields.length === references.length &&
+        referenceFields.every((name) => shownIn(fields, name)) &&
+        references.every((name) => shownIn(targetFields, name)));
+}
 function cloneOperations(operations) {
     return cloneValue(operations);
 }
@@ -1008,7 +1031,7 @@ function projectCore(model, config, diagnostics) {
     const validators = compileValidatorTable(baseline.resources, scope.pipelines);
     const projection = projectExposure({ layer: "root", style: exposureStyle(scope), diagnostics }, baseline, baseline, scope.exemptions);
     qualifyFilterModes(projection);
-    pruneHiddenPairings(projection);
+    pruneHiddenPairings(projection, "shown");
     projectCreateRequirements(model, projection.resources);
     checkHiddenRequirements(model, "root", baseline.resources, baseline.resources, projection.resources, diagnostics);
     applyValidators(projection.resources, validators);
@@ -1059,7 +1082,7 @@ function projectDerivedScope(model, scopeName, core, parentView, config, diagnos
         ...(scopeName === "agent" ? { parent: config.agent.parent } : {}),
     }, baseline, parent, scope.exemptions);
     qualifyFilterModes(projection);
-    pruneHiddenPairings(projection);
+    pruneHiddenPairings(projection, "none");
     projectCreateRequirements(model, projection.resources);
     checkHiddenRequirements(model, scopeName, baseline.resources, parent.resources, projection.resources, diagnostics);
     applyValidators(projection.resources, validators);

package/dist/config/config.resolver.d.ts

@@ -11,6 +11,8 @@ import type { AvConfigFieldDefinition } from "./framework-field-definition.js";
 import { type ResolvedPipelineTree } from "./pipeline-tree.resolver.js";
 /** The root's `policy`, its engine's passive lists read once. */
 export type ResolvedPolicyConfig = {
+    /** Where the engine was configured, for the startup diagnostics' paths. */
+    readonly at: "policy.engine" | "access.policy";
     readonly engine: AvPolicyEngine;
     readonly principal: NonNullable<AvConfig["policy"]>["principal"];
     /** The governed fields and relations, by Resource. */

package/dist/config/config.resolver.js

@@ -158,11 +158,16 @@ function frozenPathLists(value) {
         Object.freeze(paths.map((path) => Object.freeze([...path]))),
     ])));
 }
-function resolvePolicy(policy) {
+const accessPrincipal = ({ $state, }) => $state.me ?? null;
+function resolvePolicy(configured, access) {
+    const policy = access === undefined
+        ? configured
+        : { engine: access.policy, principal: accessPrincipal };
     if (policy === undefined) {
         return undefined;
     }
     return Object.freeze({
+        at: access === undefined ? "policy.engine" : "access.policy",
         engine: policy.engine,
         principal: policy.principal,
         governed: frozenLists(policy.engine.governed),
@@ -188,7 +193,7 @@ export function resolveFrameworkConfig(config) {
         adapter: config.adapter,
         diagnostics: config.diagnostics,
         misuse: config.misuse,
-        policy: resolvePolicy(config.policy),
+        policy: resolvePolicy(config.policy, config.access),
         definitions: definitionsOf(root.resources),
         trees: {
             root: root.resources,

package/dist/config/config.validator.js

@@ -7,6 +7,7 @@ const ROOT_ONLY_PROPERTIES = new Set([
     "adapter",
     "prebuilt",
     "policy",
+    "access",
     "diagnostics",
     "misuse",
     "application",
@@ -628,6 +629,12 @@ export function validateFrameworkConfig(value) {
     if (Object.hasOwn(value, "policy") && value.policy !== undefined) {
         validatePolicy(value.policy, diagnostics);
     }
+    if (Object.hasOwn(value, "access") && value.access !== undefined) {
+        validateAccess(value.access, diagnostics);
+        if (Object.hasOwn(value, "policy") && value.policy !== undefined) {
+            diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", "policy", "policy cannot be configured with access: access.policy is the policy engine, and ctx.$state.me the principal; remove policy"));
+        }
+    }
     if (Object.hasOwn(value, "diagnostics") &&
         value.diagnostics !== undefined &&
         typeof value.diagnostics !== "function") {
@@ -670,26 +677,43 @@ function validatePolicy(value, diagnostics) {
         diagnostics.push(diagnostic("CONFIG_REQUIRED", "policy.engine", "policy.engine is required"));
         return;
     }
-    const engine = value.engine;
+    validatePolicyEngine(value.engine, "policy.engine", diagnostics);
+}
+function validateAccess(value, diagnostics) {
+    if (value === null || typeof value !== "object") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "access", "access must be an access provider, { policy, state }"));
+        return;
+    }
+    const provider = value;
+    if (typeof provider.state !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "access.state", "access.state must be a function"));
+    }
+    if (provider.policy === undefined) {
+        diagnostics.push(diagnostic("CONFIG_REQUIRED", "access.policy", "access.policy is required"));
+        return;
+    }
+    validatePolicyEngine(provider.policy, "access.policy", diagnostics);
+}
+function validatePolicyEngine(engine, at, diagnostics) {
     if (engine === null || typeof engine !== "object") {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "policy.engine", "policy.engine must be an object"));
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", at, `${at} must be an object`));
         return;
     }
     const members = engine;
     for (const question of ["can", "scopeOf", "fieldsOf"]) {
         if (typeof members[question] !== "function") {
-            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `policy.engine.${question}`, `policy.engine.${question} must be a function`));
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${question}`, `${at}.${question} must be a function`));
         }
     }
-    validatePolicyLists(members.governed, "governed", { all: "string lists", one: "a list of strings" }, isStringList, diagnostics);
-    validatePolicyLists(members.paths, "paths", {
+    validatePolicyLists(members.governed, at, "governed", { all: "string lists", one: "a list of strings" }, isStringList, diagnostics);
+    validatePolicyLists(members.paths, at, "paths", {
         all: "path lists",
         one: "a list of paths, each a list of strings",
     }, (paths) => Array.isArray(paths) && paths.every(isStringList), diagnostics);
-    validatePolicyLists(members.afterChecks, "afterChecks", { all: "action lists", one: "a list of actions" }, isStringList, diagnostics);
-    validateAfterCheckActions(members.afterChecks, diagnostics);
+    validatePolicyLists(members.afterChecks, at, "afterChecks", { all: "action lists", one: "a list of actions" }, isStringList, diagnostics);
+    validateAfterCheckActions(members.afterChecks, at, diagnostics);
 }
-function validateAfterCheckActions(lists, diagnostics) {
+function validateAfterCheckActions(lists, at, diagnostics) {
     if (!isPlainRecord(lists)) {
         return;
     }
@@ -699,7 +723,7 @@ function validateAfterCheckActions(lists, diagnostics) {
         }
         for (const action of actions) {
             if (action !== "update") {
-                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `policy.engine.afterChecks.${resource}`, `policy.engine.afterChecks.${resource}: "${action}" is no action an after check runs on; only "update" is`));
+                diagnostics.push(diagnostic("CONFIG_INVALID_VALUE", `${at}.afterChecks.${resource}`, `${at}.afterChecks.${resource}: "${action}" is no action an after check runs on; only "update" is`));
             }
         }
     }
@@ -707,17 +731,17 @@ function validateAfterCheckActions(lists, diagnostics) {
 function isStringList(value) {
     return (Array.isArray(value) && value.every((name) => typeof name === "string"));
 }
-function validatePolicyLists(lists, list, entry, isEntry, diagnostics) {
+function validatePolicyLists(lists, at, list, entry, isEntry, diagnostics) {
     if (lists === undefined) {
         return;
     }
     if (!isPlainRecord(lists)) {
-        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `policy.engine.${list}`, `policy.engine.${list} must be an object of ${entry.all} when provided`));
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${list}`, `${at}.${list} must be an object of ${entry.all} when provided`));
         return;
     }
     for (const [key, value] of Object.entries(lists)) {
         if (!isEntry(value)) {
-            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `policy.engine.${list}.${key}`, `policy.engine.${list}.${key} must be ${entry.one}`));
+            diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", `${at}.${list}.${key}`, `${at}.${list}.${key} must be ${entry.one}`));
         }
     }
 }

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

@@ -243,6 +243,7 @@ type RootSchema<M extends AvAdapterModel, Cfg> = LayerKeysSchema & {
         readonly engine: Leaf;
         readonly principal: Leaf;
     };
+    readonly access: Leaf;
     readonly diagnostics: Leaf;
     readonly misuse: Leaf;
     readonly resources: RootResourcesSchema<M>;
@@ -264,7 +265,16 @@ type Exact<S, V> = [S] extends [Leaf] ? unknown : V extends readonly unknown[] ?
  * rc.0 key, a `definition` in an overlay, a stage a relation field does not take,
  * or a name the model and the root do not have.
  */
-export type AvConfigExact<M extends AvAdapterModel, Cfg> = Exact<RootSchema<M, Cfg>, Cfg> & ExposedWithExemptions<Cfg, "application"> & ExposedWithExemptions<Cfg, "client"> & ExposedWithExemptions<Cfg, "agent"> & ForceNeedsTransactions<M, Cfg>;
+export type AvConfigExact<M extends AvAdapterModel, Cfg> = Exact<RootSchema<M, Cfg>, Cfg> & ExposedWithExemptions<Cfg, "application"> & ExposedWithExemptions<Cfg, "client"> & ExposedWithExemptions<Cfg, "agent"> & ForceNeedsTransactions<M, Cfg> & AccessWithoutPolicy<Cfg>;
+/** `policy` refused when the configuration also states `access`. */
+type AccessWithoutPolicy<Cfg> = Cfg extends {
+    readonly access: object;
+    readonly policy: object;
+} ? {
+    readonly policy: readonly [
+        "Error: `access` brings the policy engine; remove `policy`"
+    ];
+} : unknown;
 /** A layer's own literal `transactionsStyle`, `undefined` when it states none. */
 type StyleOf<Layer> = Layer extends {
     readonly transactionsStyle: infer Style;