@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.0

package/dist/runtime/owned-execution.registry.js

@@ -0,0 +1,7 @@
+const OWNED_EXECUTIONS = new WeakMap();
+export function recordOwnedExecution(framework, execution) {
+    OWNED_EXECUTIONS.set(framework, execution);
+}
+export function ownedExecutionOf(framework) {
+    return OWNED_EXECUTIONS.get(framework);
+}

package/dist/runtime/pipeline.d.ts

@@ -14,7 +14,7 @@ export type PipelineTransportContext = {
 /** What a pipeline callback is told about the operation it is wrapping. */
 export type PipelineContext<M extends AdapterModel = AdapterModel> = {
     readonly contract: Contract;
-    readonly scope: RequestOrigin;
+    readonly origin: RequestOrigin;
     readonly resource: FrameworkResourceKey<M>;
     readonly family: OperationFamily;
     readonly variant: string;
@@ -23,20 +23,32 @@ export type PipelineContext<M extends AdapterModel = AdapterModel> = {
     readonly transport?: PipelineTransportContext;
 };
 /** Allows or denies an operation; returning `false` answers `A4001`. */
-export type Guard<M extends AdapterModel = AdapterModel> = (context: PipelineContext<M>) => boolean | undefined | Promise<boolean | undefined>;
+export type Guard<M extends AdapterModel = AdapterModel> = {
+    guard(context: PipelineContext<M>): boolean | undefined | Promise<boolean | undefined>;
+}["guard"];
 /**
  * Transforms the arguments before the operation runs; returning `undefined`
  * keeps them as they are.
  */
-export type Pipe<M extends AdapterModel = AdapterModel> = (args: unknown, context: PipelineContext<M>) => unknown | Promise<unknown>;
+export type Pipe<M extends AdapterModel = AdapterModel> = {
+    pipe(args: unknown, context: PipelineContext<M>): unknown | Promise<unknown>;
+}["pipe"];
 /** Runs just before the operation executes. */
-export type BeforeHook<M extends AdapterModel = AdapterModel> = (context: PipelineContext<M>) => void | Promise<void>;
+export type BeforeHook<M extends AdapterModel = AdapterModel> = {
+    before(context: PipelineContext<M>): void | Promise<void>;
+}["before"];
 /** Runs after the operation succeeds, with its result. */
-export type AfterHook<M extends AdapterModel = AdapterModel> = (result: unknown, context: PipelineContext<M>) => void | Promise<void>;
+export type AfterHook<M extends AdapterModel = AdapterModel> = {
+    after(result: unknown, context: PipelineContext<M>): void | Promise<void>;
+}["after"];
 /** Wraps the operation's execution; call `next()` to run it and get its result. */
-export type Interceptor<M extends AdapterModel = AdapterModel> = (context: PipelineContext<M>, next: () => Promise<unknown>) => Promise<unknown>;
+export type Interceptor<M extends AdapterModel = AdapterModel> = {
+    intercept(context: PipelineContext<M>, next: () => Promise<unknown>): Promise<unknown>;
+}["intercept"];
 /**
  * Turns a thrown error into a {@link FrameworkError} to answer with; returning
  * `undefined` passes the error on.
  */
-export type Filter<M extends AdapterModel = AdapterModel> = (error: unknown, context: PipelineContext<M>) => FrameworkError | undefined | Promise<FrameworkError | undefined>;
+export type Filter<M extends AdapterModel = AdapterModel> = {
+    filter(error: unknown, context: PipelineContext<M>): FrameworkError | undefined | Promise<FrameworkError | undefined>;
+}["filter"];

package/dist/runtime/referential-action.d.ts

@@ -23,6 +23,13 @@ export type ReferentialEdge = {
     readonly field: string;
     /** The Resource the edge points AT — the one whose deletion fires `onDelete`. */
     readonly target: string;
+    /**
+     * The scalar fields of the ENCLOSING Resource that hold the reference, in the
+     * order the store pairs them with the `target`'s key. A record that writes the
+     * relation `field` and any of these names the reference twice and is refused;
+     * a required relation may be written through all of them instead.
+     */
+    readonly references: readonly string[];
     /** What deleting a `target` row does to rows of the ENCLOSING Resource. */
     readonly onDelete: ReferentialDeleteEffect;
 };

package/dist/runtime/request-envelope.validator.d.ts

@@ -0,0 +1,5 @@
+import type { ValidationIssue } from "../operations/validation-code.js";
+/** The issues of one malformed operation request envelope; empty when well formed. */
+export declare function validateOperationEnvelope(request: unknown): readonly ValidationIssue[];
+/** The issues of one malformed transaction request envelope; empty when well formed. */
+export declare function validateTransactionEnvelope(request: unknown): readonly ValidationIssue[];

package/dist/runtime/request-envelope.validator.js

@@ -0,0 +1,118 @@
+const ORIGINS = ["application", "client"];
+const OPERATION_IDENTITY_MEMBERS = ["resource", "family", "variant"];
+export function validateOperationEnvelope(request) {
+    if (!isRecord(request)) {
+        return [issue([], "V1001", "Operation request must be an object.")];
+    }
+    const issues = [...originAndIdentityIssues(request)];
+    for (const member of OPERATION_IDENTITY_MEMBERS) {
+        const failure = requiredStringIssue(request, member);
+        if (failure !== undefined) {
+            issues.push(failure);
+        }
+    }
+    return issues;
+}
+export function validateTransactionEnvelope(request) {
+    if (!isRecord(request)) {
+        return [issue([], "V1001", "Transaction request must be an object.")];
+    }
+    return originAndIdentityIssues(request);
+}
+function originAndIdentityIssues(request) {
+    const issues = [];
+    const origin = request.origin;
+    if (origin === undefined) {
+        issues.push(issue(["origin"], "V1000", 'Required property "origin" is missing.'));
+    }
+    else if (typeof origin !== "string") {
+        issues.push(issue(["origin"], "V1001", "Request origin must be a string."));
+    }
+    else if (!ORIGINS.includes(origin)) {
+        issues.push(issue(["origin"], "V1002", 'Request origin must be "application" or "client".'));
+    }
+    const requestId = request.requestId;
+    if (requestId === undefined || requestId === "") {
+        issues.push(issue(["requestId"], "V1000", 'Required property "requestId" is missing or empty.'));
+    }
+    else if (typeof requestId !== "string") {
+        issues.push(issue(["requestId"], "V1001", "Request id must be a string."));
+    }
+    if (origin === "client") {
+        issues.push(...protocolIssues(request.protocol));
+        if (request.transport !== undefined) {
+            issues.push(...transportIssues(request.transport));
+        }
+    }
+    else if (origin === "application") {
+        for (const member of ["protocol", "transport"]) {
+            if (request[member] !== undefined) {
+                issues.push(issue([member], "V1005", `Property "${member}" belongs to a client request, not an application one.`));
+            }
+        }
+    }
+    return issues;
+}
+function protocolIssues(protocol) {
+    if (protocol === undefined) {
+        return [
+            issue(["protocol"], "V1000", 'Required property "protocol" is missing from a client request.'),
+        ];
+    }
+    if (!isRecord(protocol)) {
+        return [
+            issue(["protocol"], "V1001", "Protocol identity must be an object."),
+        ];
+    }
+    const issues = [];
+    if (protocol.version === undefined) {
+        issues.push(issue(["protocol", "version"], "V1000", 'Required property "version" is missing.'));
+    }
+    else if (!Number.isInteger(protocol.version)) {
+        issues.push(issue(["protocol", "version"], "V1001", "Protocol version must be an integer."));
+    }
+    if (protocol.hash === undefined) {
+        issues.push(issue(["protocol", "hash"], "V1000", 'Required property "hash" is missing.'));
+    }
+    else if (typeof protocol.hash !== "string") {
+        issues.push(issue(["protocol", "hash"], "V1001", "Protocol hash must be a string."));
+    }
+    return issues;
+}
+function transportIssues(transport) {
+    if (!isRecord(transport)) {
+        return [
+            issue(["transport"], "V1001", "Transport metadata must be an object."),
+        ];
+    }
+    const issues = [];
+    if (transport.method !== "POST") {
+        issues.push(issue(["transport", "method"], "V1001", 'Transport method must be "POST".'));
+    }
+    const headers = transport.headers;
+    if (!isRecord(headers)) {
+        issues.push(issue(["transport", "headers"], "V1001", "Transport headers must be an object."));
+        return issues;
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        if (typeof value !== "string") {
+            issues.push(issue(["transport", "headers", name], "V1001", "A transport header value must be a string."));
+        }
+    }
+    return issues;
+}
+function requiredStringIssue(request, member) {
+    const value = request[member];
+    if (value === undefined) {
+        return issue([member], "V1000", `Required property "${member}" is missing.`);
+    }
+    return typeof value === "string"
+        ? undefined
+        : issue([member], "V1001", `Property "${member}" must be a string.`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function issue(path, code, message) {
+    return { path, code, message };
+}

package/dist/runtime/scalar-runtime.d.ts

@@ -1,9 +1,11 @@
 import type { RequestOrigin } from "../config/config-layer.js";
+import type { ScalarFilterOperator } from "../contracts/capability.js";
 import type { Contract } from "../contracts/contract.js";
 import type { ScalarField } from "../contracts/field.js";
 import type { OperationIdentity } from "../operations/operation-identity.js";
 import type { OperationValidationOptions, SemanticOperationArguments } from "../operations/operation-validator.js";
 import type { ValidationIssue } from "../operations/validation-code.js";
+import { type TransactionSlotShape } from "../transactions/transaction-reference.js";
 export type ScalarNormalizationResult = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
@@ -33,7 +35,17 @@ export declare function isPlainRecord(value: unknown): value is Readonly<Record<
  * Normalizes one field value to Aventara's provider-neutral runtime form.
  * `runtime` is used for framework-produced values regardless of request origin.
  */
-export declare function normalizeScalarFieldValue(contract: Contract, field: ScalarField<Contract>, value: unknown, scope: RequestOrigin | "runtime", path: Path): ScalarValueNormalizationResult;
+export declare function normalizeScalarFieldValue(contract: Contract, field: ScalarField<Contract>, value: unknown, origin: RequestOrigin | "runtime", path: Path): ScalarValueNormalizationResult;
+/**
+ * Every way a normalized value written to `field` does not conform to the field's
+ * Json Shape, each at its full path; none for an unshaped field or a `null`.
+ * `position` says whether `value` is the field's whole value or one entry of a
+ * list field (a `$push` operand).
+ *
+ * @throws Error when the field carries a shape no checker is bound to — a Contract
+ *   the Framework did not compile.
+ */
+export declare function jsonShapeIssues(field: ScalarField<Contract>, value: unknown, path: Path, position?: "value" | "entry"): readonly ValidationIssue[];
 /**
  * Copies one validated runtime value of a scalar field into a value the framework
  * owns, per scalar codec: `datetime` → a new `Date`, `bytes` → a sliced `Uint8Array`,
@@ -44,6 +56,22 @@ export declare function normalizeScalarFieldValue(contract: Contract, field: Sca
  * its copy.
  */
 export declare function copyScalarFieldValue(field: ScalarField<Contract>, value: unknown): unknown;
+/**
+ * The operators of a step's own filter whose operand is a reference position, and
+ * the shape each holds — the one table the normalization below and the reference
+ * collector (`transaction-reference-collector.ts`) both read. `not` also takes a
+ * nested operator object. Not here, so never a reference: `mode`, `isEmpty`, `path`
+ * and a `json` field's `string*`/`array*` operators, which take no field value.
+ */
+export declare const REFERENCE_OPERANDS: Readonly<Partial<Record<ScalarFilterOperator, TransactionSlotShape>>>;
+/** The shape of `operator`'s operand when it is a reference position. */
+export declare function referenceOperandShape(operator: string): TransactionSlotShape | undefined;
+/**
+ * Where a normalization writes: `"copy"` leaves the arguments it reads untouched,
+ * `"in-place"` writes into them — only for arguments the framework owns and reads
+ * nowhere else afterwards: a door's copy, or a body the protocol decoder parsed.
+ */
+export type NormalizationWrite = "copy" | "in-place";
 /**
  * Normalizes every scalar leaf in one structurally valid standard operation.
  * Client wire values are decoded; application values are validated in runtime form.
@@ -51,5 +79,5 @@ export declare function copyScalarFieldValue(field: ScalarField<Contract>, value
 export declare function normalizeOperationScalarValues(contract: Contract, request: OperationIdentity & {
     readonly resource: string;
     readonly arguments: SemanticOperationArguments;
-}, scope: RequestOrigin, options?: OperationValidationOptions): ScalarNormalizationResult;
+}, origin: RequestOrigin, options?: OperationValidationOptions, write?: NormalizationWrite): ScalarNormalizationResult;
 export {};