@aventara/core 0.1.0-pilot.1 → 0.1.0-pilot.2

package/dist/protocol/protocol.binder.d.ts

@@ -6,38 +6,32 @@ import { type AvProtocolResponse } from "./http-response.encoder.js";
 import { transportFailure } from "./protocol-failure.js";
 import { type SurfaceRoute } from "./protocol-surface.js";
 /**
- * The protocol bound to ONE Framework instance — what `AvProtocol.bind`
- * returns (§5.9; the type's name ruled 2026-10-05). A host binds once, at
- * startup, and calls these members per request; none takes a Contract, an
- * entrypoint or a limit, because the binding already read them.
- *
- * Grows one member per slice (§7); the exact set is pinned in
- * `index.test-d.ts`.
+ * The protocol bound to ONE Framework instance — what `AvProtocol.bind` returns. A
+ * host binds once, at startup, and calls these members per request; none takes a
+ * Contract, an entrypoint or a limit, because the binding already read them.
  */
 export type AvProtocolBinding = {
     /**
-     * Every route a host mounts for the bound ClientContract, from one list,
-     * each tagged by `kind` (ADR 0007 DA-13; the architect's ruling,
-     * 2026-10-05): one `POST` `operation` route per `(resource, family,
-     * variant)` it advertises — nothing it does not — then the `contract` route
-     * `GET /_contract` (always), then the `transactions` route
-     * `POST /_transactions` exactly when its `transactions` is `"interactive"`.
-     * Each path is relative to `framework.entrypoint`. Read once at bind time:
-     * every call answers the same deep-frozen list, which is passive data a
-     * host may serialize.
+     * Every route a host mounts for the bound ClientContract, from one list, each
+     * tagged by `kind`: one `POST` `operation` route per `(resource, family, variant)`
+     * it advertises — nothing it does not — then the `contract` route `GET /_contract`
+     * (always), then the `transactions` route `POST /_transactions` exactly when its
+     * `transactions` is `"interactive"`. Each path is relative to
+     * `framework.entrypoint`. Read once at bind time: every call answers the same
+     * deep-frozen list, which is passive data a host may serialize.
      *
-     * A host that mounts one route per entry still needs a fallback for the
-     * paths it did not mount: that is the absence responder's, not a catch-all
-     * into framework handling.
+     * A host that mounts one route per entry still needs a fallback for the paths it
+     * did not mount: that is the absence responder's, not a catch-all into framework
+     * handling.
      */
     readonly surface: () => readonly SurfaceRoute[];
     /**
      * An operation route's HTTP request → the client-origin request
-     * `framework.execute` takes, or the framework response that answers it
-     * instead, with the request id either way (Q13). Answers absence for an
-     * unadvertised triple without executing it (Q12), so a catch-all host is
-     * safe. Raw body: size, content type, JSON and shape enforced; parsed body:
-     * shape only — the rest was the host's parser's (Q11).
+     * `framework.execute` takes, or the framework response that answers it instead,
+     * with the request id either way. Answers absence for an unadvertised triple
+     * without executing it, so a catch-all host is safe. Raw body: size, content type,
+     * JSON and shape enforced; parsed body: shape only — the rest was the host's
+     * parser's.
      */
     readonly decodeOperation: (request: AvProtocolRequest) => DecodedOperation;
     /**
@@ -47,77 +41,70 @@ export type AvProtocolBinding = {
      */
     readonly decodeTransaction: (request: AvProtocolRequest) => DecodedTransaction;
     /**
-     * One operation's framework response — what `framework.execute` answered —
-     * as the HTTP response a host writes: the code's status (§13.2), `data` in
-     * wire forms (P1), `Aventara-Request-Id` echoed (Q13). A result with no wire
-     * form answers `A3003` → 500. A diagnostic of one operation names it
-     * (`resource`, `family`, `variant`), so the `A3003` reaches the diagnostics
-     * sink only when the host passes `decoded` — `decodeOperation`'s success
-     * value — as `handleOperation` does (the architect, 2026-10-05); without
-     * it the answer is the same and nothing is reported.
+     * One operation's framework response — what `framework.execute` answered — as the
+     * HTTP response a host writes: the code's status, `data` in wire forms,
+     * `Aventara-Request-Id` echoed. A result with no wire form answers `A3003` → 500.
+     * A diagnostic of one operation names it (`resource`, `family`, `variant`), so the
+     * `A3003` reaches the diagnostics sink only when the host passes `decoded` —
+     * `decodeOperation`'s success value — as `handleOperation` does; without it the
+     * answer is the same and nothing is reported.
      */
     readonly encodeOperation: (response: OperationResponse, requestId: string, decoded?: DecodedOperationRequest) => AvProtocolResponse;
     /**
-     * The same for `/_transactions` — what `framework.executeTransaction`
-     * answered. A second encoder by the architect's choice (§5.9); both share
-     * the one status table and the one wire walker. An `A3003` is reported to
-     * the Framework's diagnostics sink as a `"transaction"` diagnostic — client
-     * scope, this `requestId`, the step it blames as `operation` — with the
-     * value that had no wire form (or what its getter threw) as `error`.
+     * The same for `/_transactions` — what `framework.executeTransaction` answered. An
+     * `A3003` is reported to the Framework's diagnostics sink as a `"transaction"`
+     * diagnostic — client scope, this `requestId`, the step it blames as `operation` —
+     * with the value that had no wire form (or what its getter threw) as `error`.
      */
     readonly encodeTransaction: (response: TransactionResponse, requestId: string) => AvProtocolResponse;
     /**
      * A transport code — `A2000`, `A2010`, `A2011` or `A2012` — as the complete
-     * framework response, with framework-authored text (ruled 2026-10-05). For a
-     * host that parses the body itself and must answer its parser's failure.
-     * `A2012` requires the methods its route allows, so every 405 carries
-     * `Allow` (the director, 2026-10-05).
+     * framework response, with framework-authored text (ruled 2026-10-05). For a host
+     * that parses the body itself and must answer its parser's failure. `A2012`
+     * requires the methods its route allows, so every 405 carries `Allow`.
      */
     readonly failure: typeof transportFailure;
     /**
-     * The shortcut (R2): `decodeOperation` → `framework.execute` →
-     * `encodeOperation`, resolving the response the host writes for an
-     * operation route. A decode failure is answered without executing; an
-     * `A3003` is reported to the diagnostics sink with the operation's
-     * identity and request id. Total over any value an untyped host hands it:
-     * one that is not an `AvProtocolRequest` answers `400 A2000`; it never
-     * rejects.
+     * The shortcut: `decodeOperation` → `framework.execute` → `encodeOperation`,
+     * resolving the response the host writes for an operation route. A decode failure
+     * is answered without executing; an `A3003` is reported to the diagnostics sink
+     * with the operation's identity and request id. Total over any value an untyped
+     * host hands it: one that is not an `AvProtocolRequest` answers `400 A2000`; it
+     * never rejects.
      */
     readonly handleOperation: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
     /**
      * The same for `/_transactions`: `decodeTransaction` →
-     * `framework.executeTransaction` → `encodeTransaction`. Every step runs
-     * under ClientContract rules (R1); a committed plan is `200 A1009`, a
-     * rolled-back one its failing step's own status.
+     * `framework.executeTransaction` → `encodeTransaction`. Every step runs under
+     * ClientContract rules; a committed plan is `200 A1009`, a rolled-back one its
+     * failing step's own status.
      */
     readonly handleTransaction: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
     /**
-     * The `GET /_contract` responder (Q8): the bound ClientContract's
-     * JCS-canonical bytes, `ETag` its quoted hash, `Cache-Control: no-cache`,
-     * and `304` with no body when `If-None-Match` matches (weak comparison, a
-     * list, `*`). Requires no identity header; any other method is `405
-     * A2012` with `Allow: GET`. The bytes are written once, at bind time.
+     * The `GET /_contract` responder: the bound ClientContract's JCS-canonical bytes,
+     * `ETag` its quoted hash, `Cache-Control: no-cache`, and `304` with no body when
+     * `If-None-Match` matches (weak comparison, a list, `*`). Requires no identity
+     * header; any other method is `405 A2012` with `Allow: GET`. The bytes are written
+     * once, at bind time.
      */
     readonly encodeContract: (request: AvProtocolRequest) => AvProtocolResponse;
     /**
-     * The absence responder (Q2's O3): the fallback a host mounts for every
-     * path it did not mount from `surface()` — never a catch-all into framework
-     * handling (it reads no body, runs no pipeline, calls no Adapter). Answers
-     * what the catch-all decoder answers before a body — `A2000`, `A2006`,
-     * `A2005`, `A2001`, `A2002`, `A2012` with `Allow` — byte for byte; a route
-     * that exists reached with its own method as `500 A3000` (a host that
-     * mounted only part of the surface); and `undefined` for a path outside the
-     * protocol's namespace, which the host answers itself (the architect,
-     * 2026-10-05).
+     * The absence responder: the fallback a host mounts for every path it did not
+     * mount from `surface()` — never a catch-all into framework handling (it reads no
+     * body, runs no pipeline, calls no Adapter). Answers what the catch-all decoder
+     * answers before a body — `A2000`, `A2006`, `A2005`, `A2001`, `A2002`, `A2012`
+     * with `Allow` — byte for byte; a route that exists reached with its own method as
+     * `500 A3000` (a host that mounted only part of the surface); and `undefined` for
+     * a path outside the protocol's namespace, which the host answers itself.
      */
     readonly answerAbsent: (request: AvProtocolRequest) => AvProtocolResponse | undefined;
 };
 /**
- * `AvProtocol.bind(framework)`: reads the instance's compiled ClientContract
- * once and returns the bound members, frozen.
+ * `AvProtocol.bind(framework)`: reads the instance's compiled ClientContract once
+ * and returns the bound members, frozen.
  *
- * It validates nothing construction did not: `createFramework` already refused
- * a bad entrypoint (R4) and compiled the ClientContract this reads, so binding
- * cannot fail.
+ * It validates nothing construction did not: `createFramework` already refused a
+ * bad entrypoint and compiled the ClientContract this reads, so binding cannot
+ * fail.
  */
 export declare function bind(framework: Framework): AvProtocolBinding;

package/dist/protocol/protocol.binder.js

@@ -6,14 +6,6 @@ import { encodeOperationResponse, encodeTransactionResponse, } from "./http-resp
 import { handleOperationRequest, handleTransactionRequest, operationUnencodableReport, planUnencodableReport, } from "./protocol.handler.js";
 import { transportFailure } from "./protocol-failure.js";
 import { surfaceOf } from "./protocol-surface.js";
-/**
- * `AvProtocol.bind(framework)`: reads the instance's compiled ClientContract
- * once and returns the bound members, frozen.
- *
- * It validates nothing construction did not: `createFramework` already refused
- * a bad entrypoint (R4) and compiled the ClientContract this reads, so binding
- * cannot fail.
- */
 export function bind(framework) {
     const { contracts } = framework;
     const surface = surfaceOf(contracts.client);

package/dist/protocol/protocol.handler.d.ts

@@ -16,48 +16,44 @@ export type HandlerContext = {
 };
 /**
  * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a
- * `"transaction"` diagnostic — client scope (the protocol has no other
- * origin, P4), the request id the plan ran under, and the step the encoder
- * blames as `operation` when it blames one. One spelling for both
- * `protocol.encodeTransaction` and `protocol.handleTransaction`.
+ * `"transaction"` diagnostic — client scope, the request id the plan ran under,
+ * and the step the encoder blames as `operation` when it blames one. One spelling
+ * for both `protocol.encodeTransaction` and `protocol.handleTransaction`.
  */
 export declare function planUnencodableReport(sink: FrameworkDiagnosticsSink | undefined, requestId: string): UnencodableReport;
 /**
  * Where one operation's `A3003` goes: the Framework's diagnostics sink, as an
- * `"operation"` diagnostic carrying the decoded request's identity and id —
- * the shape the public `OperationDiagnostic` already has. One spelling for
- * `protocol.handleOperation` and for `protocol.encodeOperation` given the
- * decoded request (the architect, 2026-10-05).
+ * `"operation"` diagnostic carrying the decoded request's identity and id — the
+ * shape the public `OperationDiagnostic` already has. One spelling for
+ * `protocol.handleOperation` and for `protocol.encodeOperation` given the decoded
+ * request.
  */
 export declare function operationUnencodableReport(sink: FrameworkDiagnosticsSink | undefined, request: ClientOperationRequest): UnencodableReport;
 /**
- * `protocol.handleOperation(request)` (§5.9, R2; S8): the three steps a host
- * would otherwise spell out — `decodeOperation` → `framework.execute` →
- * `encodeOperation` — in one call, resolving the `AvProtocolResponse` the host
- * writes. A request the decoder answers itself (a transport failure, an
- * identity mismatch, an unadvertised route) is answered without executing.
+ * `protocol.handleOperation(request)`: the three steps a host would otherwise
+ * spell out — `decodeOperation` → `framework.execute` → `encodeOperation` — in one
+ * call, resolving the `AvProtocolResponse` the host writes. A request the decoder
+ * answers itself (a transport failure, an identity mismatch, an unadvertised
+ * route) is answered without executing.
  *
- * Total over ANY value, never rejecting: the decoder answers every value (one
- * that is not an `AvProtocolRequest` as `400 A2000`; the director,
- * 2026-10-05), `execute` resolves for every request it is handed, and the
- * encoder answers every response — a result with no wire form as `A3003` →
- * 500. That `A3003`
- * reaches the Framework's diagnostics sink as an `"operation"` diagnostic
- * carrying the decoded request's identity and id (the director, 2026-10-05),
- * which only this shortcut holds: the bare `encodeOperation` is given the
- * response and the request id alone.
+ * Total over ANY value, never rejecting: the decoder answers every value,
+ * `execute` resolves for every request it is handed, and the encoder answers every
+ * response — a result with no wire form as `A3003` →
+ * 500. That `A3003` reaches the Framework's diagnostics sink as an `"operation"`
+ *      diagnostic carrying the decoded request's identity and id, which only this
+ *      shortcut holds: the bare `encodeOperation` is given the response and the
+ *      request id alone.
  */
 export declare function handleOperationRequest(context: HandlerContext, request: AvProtocolRequest): Promise<AvProtocolResponse>;
 /**
- * `protocol.handleTransaction(request)` (§5.9, R2; S9): the same shortcut for
- * `/_transactions` — `decodeTransaction` → `framework.executeTransaction` →
- * `encodeTransaction`. The decoded plan is client origin and cannot say
- * otherwise, so every step runs under ClientContract rules (R1): a
- * client-hidden field, a client-restricted variant or a client-hidden
- * Resource is refused as through its single-operation route, plus
- * `cause.operation`. A committed plan is `200 A1009` (P3); a rolled-back one
- * answers its failing step's code at that code's status (Q4). Total over any
- * value, as {@link handleOperationRequest} is; an `A3003` is
- * reported through {@link planUnencodableReport}.
+ * `protocol.handleTransaction(request)`: the same shortcut for `/_transactions` —
+ * `decodeTransaction` → `framework.executeTransaction` → `encodeTransaction`. The
+ * decoded plan is client origin and cannot say otherwise, so every step runs under
+ * ClientContract rules: a client-hidden field, a client-restricted variant or a
+ * client-hidden Resource is refused as through its single-operation route, plus
+ * `cause.operation`. A committed plan is `200 A1009`; a rolled-back one answers
+ * its failing step's code at that code's status. Total over any value, as {@link
+ * handleOperationRequest} is; an `A3003` is reported through {@link
+ * planUnencodableReport}.
  */
 export declare function handleTransactionRequest(context: HandlerContext, request: AvProtocolRequest): Promise<AvProtocolResponse>;

package/dist/protocol/protocol.handler.js

@@ -1,13 +1,6 @@
 import { createDiagnosticsReporter, createReporter, } from "../runtime/diagnostics-reporter.js";
 import { decodeOperationRequest, decodeTransactionRequest, } from "./http-request.decoder.js";
 import { encodeOperationResponse, encodeTransactionResponse, } from "./http-response.encoder.js";
-/**
- * Where a plan's `A3003` goes: the Framework's diagnostics sink, as a
- * `"transaction"` diagnostic — client scope (the protocol has no other
- * origin, P4), the request id the plan ran under, and the step the encoder
- * blames as `operation` when it blames one. One spelling for both
- * `protocol.encodeTransaction` and `protocol.handleTransaction`.
- */
 export function planUnencodableReport(sink, requestId) {
     return (error, operation) => createReporter(sink, {
         kind: "transaction",
@@ -16,33 +9,9 @@ export function planUnencodableReport(sink, requestId) {
         ...(operation === undefined ? {} : { operation }),
     })(error, "A3003");
 }
-/**
- * Where one operation's `A3003` goes: the Framework's diagnostics sink, as an
- * `"operation"` diagnostic carrying the decoded request's identity and id —
- * the shape the public `OperationDiagnostic` already has. One spelling for
- * `protocol.handleOperation` and for `protocol.encodeOperation` given the
- * decoded request (the architect, 2026-10-05).
- */
 export function operationUnencodableReport(sink, request) {
     return (error) => createDiagnosticsReporter(sink, request)(error, "A3003");
 }
-/**
- * `protocol.handleOperation(request)` (§5.9, R2; S8): the three steps a host
- * would otherwise spell out — `decodeOperation` → `framework.execute` →
- * `encodeOperation` — in one call, resolving the `AvProtocolResponse` the host
- * writes. A request the decoder answers itself (a transport failure, an
- * identity mismatch, an unadvertised route) is answered without executing.
- *
- * Total over ANY value, never rejecting: the decoder answers every value (one
- * that is not an `AvProtocolRequest` as `400 A2000`; the director,
- * 2026-10-05), `execute` resolves for every request it is handed, and the
- * encoder answers every response — a result with no wire form as `A3003` →
- * 500. That `A3003`
- * reaches the Framework's diagnostics sink as an `"operation"` diagnostic
- * carrying the decoded request's identity and id (the director, 2026-10-05),
- * which only this shortcut holds: the bare `encodeOperation` is given the
- * response and the request id alone.
- */
 export async function handleOperationRequest(context, request) {
     const decoded = decodeOperationRequest(context.contracts, request);
     if (!decoded.ok) {
@@ -51,18 +20,6 @@ export async function handleOperationRequest(context, request) {
     const response = await context.execute(decoded.request);
     return encodeOperationResponse(response, decoded.requestId, operationUnencodableReport(context.sink, decoded.request));
 }
-/**
- * `protocol.handleTransaction(request)` (§5.9, R2; S9): the same shortcut for
- * `/_transactions` — `decodeTransaction` → `framework.executeTransaction` →
- * `encodeTransaction`. The decoded plan is client origin and cannot say
- * otherwise, so every step runs under ClientContract rules (R1): a
- * client-hidden field, a client-restricted variant or a client-hidden
- * Resource is refused as through its single-operation route, plus
- * `cause.operation`. A committed plan is `200 A1009` (P3); a rolled-back one
- * answers its failing step's code at that code's status (Q4). Total over any
- * value, as {@link handleOperationRequest} is; an `A3003` is
- * reported through {@link planUnencodableReport}.
- */
 export async function handleTransactionRequest(context, request) {
     const decoded = decodeTransactionRequest(context.contracts, request);
     if (!decoded.ok) {

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

@@ -35,17 +35,6 @@ function supportsProjection(request) {
     }
     return request.variant !== "count";
 }
-/**
- * Plan one scalar of the read. Two Contracts answer two different questions:
- * the **active** Contract decides what the read RETURNS, and the **Core**
- * Contract decides what the Adapter is ASKED for — only a field it stores.
- *
- * A field added at a scope (`application.fields`) exists in that scope's
- * Contract and not in Core, and is VIRTUAL by construction
- * (`contract.compiler.ts`), so it is returned and computed, never requested.
- * Resolving the returned field against Core instead dropped it from the default
- * read and sent an explicit `select` of it to the Adapter as a column (D2).
- */
 function addScalarProjection(core, active, behaviors, resourceName, fieldName, adapterSelect, requested, computed) {
     const activeField = lookupField(lookupResource(active, resourceName), fieldName);
     if (activeField?.kind !== "scalar") {
@@ -253,13 +242,6 @@ function replaceWithInternalSelect(args, select) {
     internal.select = select;
     return internal;
 }
-/**
- * Clone the caller projection into the internal Adapter projection: the read
- * set the Adapter is asked for, always explicit for a projecting variant, plus
- * whatever computed scalar fields need to materialize. Caller-visible arguments
- * are never mutated and hidden dependencies are resolved through the Core
- * Contract.
- */
 export function planReadOperation(core, active, behaviors, request, args) {
     if (!isRecord(args) || !supportsProjection(request)) {
         return { arguments: args, projection: undefined, materialize: false };
@@ -285,11 +267,6 @@ export function planReadOperation(core, active, behaviors, request, args) {
             materialize: true,
         };
     }
-    // No caller projection: the read set is the default projection, issued
-    // explicitly and unconditionally. Leaving it unspecified would mean "whatever
-    // the Adapter's provider reads by default", which is every stored column —
-    // including one the active scope has removed from reads, fetched into server
-    // memory before the output validator could refuse it (D1).
     const defaults = defaultProjectionLevel(core, active, behaviors, request.resource);
     return {
         arguments: { ...args, select: defaults.select },
@@ -319,8 +296,6 @@ async function materializeRecord(active, behaviors, request, plan, value, contex
     if (!isRecord(value)) {
         return value;
     }
-    // The active Contract planned this read, so it is the one that knows every
-    // computed field in it — a field added at its scope included (D2).
     const resource = lookupResource(active, plan.resource);
     if (resource === undefined) {
         return value;
@@ -359,10 +334,6 @@ async function materializeRecord(active, behaviors, request, plan, value, contex
         .filter((fieldName) => Object.hasOwn(record, fieldName))
         .map((fieldName) => [fieldName, record[fieldName]]));
 }
-/**
- * Materialize computed scalar reads and remove internal dependency fields,
- * against `active` — the Contract `planReadOperation` was given as `active`.
- */
 export async function materializeReadOperation(active, behaviors, request, plan, value, contextFactory) {
     const projection = plan.projection;
     if (!plan.materialize || projection === undefined) {

package/dist/runtime/create-requirement.d.ts

@@ -0,0 +1,65 @@
+import type { Contract } from "../contracts/contract.js";
+import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { ValidationIssue } from "../operations/validation-code.js";
+/**
+ * Core's create-requirement vocabulary, and the check that reads it.
+ *
+ * **The facts are an Adapter's.** Which values a store cannot create a row
+ * without is a property of the store's schema — a column with no default, a
+ * reference that must point somewhere — and only the Adapter can read it. The
+ * words are Aventara's, so an Adapter translates its provider's facts into them,
+ * and the reasoning over them is core's, so no Adapter re-implements it.
+ *
+ * None of this enters a Contract. A Contract carries no foreign-key detail and
+ * no knowledge of which relation is the other end of which, and a requirement
+ * needs both; it is a server-side fact, read once when the Framework is
+ * constructed, like the referential actions.
+ *
+ * **When the check runs.** After guards, pipes and computed write behaviours —
+ * the moment the arguments are what the Adapter will be handed — and before
+ * any `before` hook or Adapter work. Earlier would refuse a value a pipe or a
+ * computed behaviour was about to supply; later is the store's own refusal,
+ * which reaches the caller as an internal failure. A missing value is the
+ * caller's to fix, so it answers `A2004` with a `V1000` issue at the path where
+ * the value belongs.
+ */
+/** A relation edge, named by the Resource that holds it and its field there. */
+export type CreateRequirementEdge = {
+    readonly resource: string;
+    readonly relation: string;
+};
+/**
+ * One value a create of a Resource cannot do without.
+ *
+ * - `field` — a scalar with no default, generated value or other source: it
+ *   must be written.
+ * - `relation` — a required to-one relation: it must be written (connected or
+ *   created), or every one of `orFields` must be — the scalar fields that hold
+ *   the reference. When the row is created **through** the relation's other end
+ *   (`inverse`), the parent supplies it, and it is not required.
+ */
+export type CreateRequirement = {
+    readonly kind: "field";
+    readonly field: string;
+} | {
+    readonly kind: "relation";
+    readonly relation: string;
+    readonly orFields: readonly string[];
+    readonly inverse?: CreateRequirementEdge;
+};
+/**
+ * Every Resource's create requirements, keyed by Resource. A Resource that is
+ * absent, or carries an empty list, requires nothing core can check.
+ */
+export type CreateRequirementTable = Readonly<Record<string, readonly CreateRequirement[]>>;
+type Path = readonly (string | number)[];
+/**
+ * The `V1000` issues for every create position in one operation's arguments
+ * that lacks a value the Adapter requires — `create.*`'s `data`, `upsert`'s
+ * `create`, and every nested create under any write — in argument order.
+ * Empty when nothing is missing. Total over malformed input.
+ */
+export declare function missingCreateValues(contract: Contract, table: CreateRequirementTable, request: OperationIdentity & {
+    readonly resource: string;
+}, args: unknown, argumentsPath: Path): readonly ValidationIssue[];
+export {};

package/dist/runtime/create-requirement.js

@@ -0,0 +1,141 @@
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { advertisedDirectivesAt } from "../contracts/field.js";
+import { NESTED_WRITE_SCOPE, resolveWriteScope, } from "../operations/write-scope.resolver.js";
+import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "./mutation-planner.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function written(record, key) {
+    return Object.hasOwn(record, key) && record[key] !== undefined;
+}
+function requirementsOf(table, resource) {
+    const listed = Object.hasOwn(table, resource) ? table[resource] : undefined;
+    return Array.isArray(listed) ? listed : [];
+}
+function creatableScalar(contract, resource, field) {
+    const found = lookupField(lookupResource(contract, resource), field);
+    return found?.kind === "scalar" && found.capabilities.create !== undefined;
+}
+function creatableRelation(contract, resource, relation, scope) {
+    const found = lookupField(lookupResource(contract, resource), relation);
+    return (found?.kind === "relation" &&
+        advertisedDirectivesAt(found.capabilities.create, scope) !== undefined);
+}
+function checkCreateRecord(context, resource, record, path, scope, via) {
+    if (!isRecord(record)) {
+        return;
+    }
+    const { contract, issues } = context;
+    for (const requirement of requirementsOf(context.table, resource)) {
+        if (requirement.kind === "field") {
+            if (!written(record, requirement.field) &&
+                creatableScalar(contract, resource, requirement.field)) {
+                issues.push({
+                    code: "V1000",
+                    path: [...path, requirement.field],
+                    message: `Field "${requirement.field}" is required to create ${resource}.`,
+                });
+            }
+            continue;
+        }
+        if (via !== undefined &&
+            requirement.inverse?.resource === via.resource &&
+            requirement.inverse.relation === via.relation) {
+            continue;
+        }
+        const orFields = Array.isArray(requirement.orFields)
+            ? requirement.orFields
+            : [];
+        if (written(record, requirement.relation) ||
+            (orFields.length > 0 && orFields.every((field) => written(record, field)))) {
+            continue;
+        }
+        if (creatableRelation(contract, resource, requirement.relation, scope)) {
+            issues.push({
+                code: "V1000",
+                path: [...path, requirement.relation],
+                message: `Relation "${requirement.relation}" is required to create ${resource}${orFields.length > 0 ? `: write it, or ${orFields.map((field) => `"${field}"`).join(" and ")}` : ""}.`,
+            });
+            continue;
+        }
+        const missing = orFields.find((field) => !written(record, field) && creatableScalar(contract, resource, field));
+        if (missing !== undefined) {
+            issues.push({
+                code: "V1000",
+                path: [...path, missing],
+                message: `Field "${missing}" is required to create ${resource}.`,
+            });
+        }
+    }
+    walkNestedCreates(context, resource, record, path);
+}
+function walkNestedCreates(context, resource, record, path) {
+    if (!isRecord(record)) {
+        return;
+    }
+    const owner = lookupResource(context.contract, resource);
+    for (const [key, value] of Object.entries(record)) {
+        const field = lookupField(owner, key);
+        if (field?.kind !== "relation" || !isRecord(value)) {
+            continue;
+        }
+        const via = { resource, relation: key };
+        for (const [directive, operand] of Object.entries(value)) {
+            if (!isRelationMutationDirective(directive)) {
+                continue;
+            }
+            const entries = Array.isArray(operand)
+                ? operand.map((entry, index) => ({ entry, at: [index] }))
+                : [{ entry: operand, at: [] }];
+            for (const { entry, at } of entries) {
+                const entryPath = [...path, key, directive, ...at];
+                for (const site of RELATION_MUTATION_RECORD_SITES[directive]) {
+                    const siteRecord = site.key === undefined
+                        ? entry
+                        : isRecord(entry)
+                            ? entry[site.key]
+                            : undefined;
+                    const sitePath = site.key === undefined ? entryPath : [...entryPath, site.key];
+                    if (site.stage === "create") {
+                        checkCreateRecord(context, field.target, siteRecord, sitePath, NESTED_WRITE_SCOPE, via);
+                    }
+                    else {
+                        walkNestedCreates(context, field.target, siteRecord, sitePath);
+                    }
+                }
+            }
+        }
+    }
+}
+export function missingCreateValues(contract, table, request, args, argumentsPath) {
+    if (!isRecord(args)) {
+        return [];
+    }
+    const context = { contract, table, issues: [] };
+    const scope = resolveWriteScope(lookupResource(contract, request.resource), request);
+    if (request.family === "create" && written(args, "data")) {
+        const data = args.data;
+        if (Array.isArray(data)) {
+            data.forEach((entry, index) => {
+                checkCreateRecord(context, request.resource, entry, [...argumentsPath, "data", index], scope, undefined);
+            });
+        }
+        else {
+            checkCreateRecord(context, request.resource, data, [...argumentsPath, "data"], scope, undefined);
+        }
+    }
+    if (request.family === "upsert") {
+        checkCreateRecord(context, request.resource, args.create, [...argumentsPath, "create"], scope, undefined);
+        walkNestedCreates(context, request.resource, args.update, [
+            ...argumentsPath,
+            "update",
+        ]);
+    }
+    if (request.family === "update") {
+        walkNestedCreates(context, request.resource, args.data, [
+            ...argumentsPath,
+            "data",
+        ]);
+    }
+    return context.issues;
+}

package/dist/runtime/decimal.d.ts

@@ -5,8 +5,8 @@ export declare class Decimal {
     toString(): string;
     /**
      * The decimal string, exactly as given: what `JSON.stringify` writes for a
-     * Decimal (Q16), so a result a developer serializes by hand carries its
-     * digits rather than `{}`. The protocol's encoders do not rely on it.
+     * Decimal, so a result a developer serializes by hand carries its digits rather
+     * than `{}`. The protocol's encoders do not rely on it.
      */
     toJSON(): string;
 }