@memberjunction/core 5.51.0 → 6.1.0-edge.1

package/dist/generic/entityCompanion.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @fileoverview Entity Companions — named, serialisable side-channels attached to a `BaseEntity`.
+ *
+ * ## What a companion is
+ *
+ * A companion is a piece of state that belongs to a record but is **not one of its fields**, and
+ * that needs to travel with the record across the client/server boundary, participate in its
+ * validation, and contribute work to its save.
+ *
+ * The canonical example is a child collection — an order's lines, a journal entry's lines, a
+ * payment's allocations — but the abstraction is deliberately not about children. It is about
+ * "extra state that rides with the record", because MemberJunction has grown that concept ad hoc
+ * three times already:
+ *
+ * - `OldValues___` on the generated GraphQL save input (concurrency check payload)
+ * - `RestoreContext___` on the same input (restore lineage for the RecordChange row)
+ * - `EntityObjectJSON` in the TransactionGroup wire format (a whole record as opaque JSON)
+ *
+ * Each solved its own problem with its own bespoke slot, resolver branch and hand-written
+ * serialisation. Companions give the next such need — and the ones already in flight — one
+ * mechanism instead of a fourth bespoke field.
+ *
+ * ## What a companion is not
+ *
+ * A companion is **not** a way to smuggle arbitrary untyped data through the platform. Every
+ * companion has a stable {@link EntityCompanion.Name}, a typed wire shape, and explicit control
+ * over what it contributes to validation and save. Data with no owner and no contract belongs in a
+ * field, not here.
+ *
+ * ## Lifecycle
+ *
+ * ```text
+ * declare  →  subclass constructor calls RegisterCompanion() (usually via DeclareRelatedRecords())
+ * load     →  BaseEntity.Load()/LoadFromData() gives eager companions a chance to populate
+ * mutate   →  application code works with the typed companion API
+ * validate →  BaseEntity.Validate()/ValidateAsync() fans out to every companion
+ * save     →  companions contribute nodes to the EntitySavePlan; the graph executes atomically
+ * transport→  Serialize() on the way out, Deserialize() on the way in
+ * ```
+ *
+ * @module @memberjunction/core
+ */
+import { BaseEntity } from './baseEntity.js';
+import { ValidationResult } from './entityInfo.js';
+import type { EntitySavePlan } from './entitySavePlan.js';
+import type { EntitySaveOptions } from './interfaces.js';
+/**
+ * The serialized form of a single companion as it crosses the wire.
+ *
+ * Deliberately minimal: a stable name plus an opaque JSON payload. Keeping the payload opaque is
+ * what lets a new companion type ship without touching the transport, the resolvers, or CodeGen.
+ */
+export type EntityCompanionPayload = {
+    /** The companion's stable {@link EntityCompanion.Name}. */
+    Name: string;
+    /** The companion's own serialized state, JSON-safe. */
+    Data: unknown;
+};
+/**
+ * The property name under which companion payloads are carried inside the plain object produced by
+ * `BaseEntity.GetDataObject()` and consumed by `BaseEntity.LoadFromData()`.
+ *
+ * The trailing triple underscore follows the convention already set by `OldValues___` and
+ * `RestoreContext___`: it marks a reserved, non-field slot and makes accidental collision with a
+ * real column name effectively impossible.
+ */
+export declare const COMPANION_PAYLOAD_KEY = "Companions___";
+/**
+ * Which direction a companion payload is travelling, which changes what the receiver must do with
+ * it.
+ *
+ * - `'request'` — the payload is a **caller's intent**, arriving at the tier that will persist it.
+ *   Records that already exist must be loaded from the database first, so dirty tracking and
+ *   old-value comparisons are computed against real stored values. Skipping that load makes an
+ *   edited record look clean (old == new), its save is skipped, and the edit is silently lost.
+ * - `'result'` — the payload is **authoritative post-save state** coming back from the tier that
+ *   just persisted it. It is adopted as-is: no queries, and the records land clean. Re-loading here
+ *   would be one wasted round trip per record for data the sender already has.
+ */
+export type EntityCompanionDeserializeMode = 'request' | 'result';
+/**
+ * Base class for all entity companions.
+ *
+ * Subclass this only when you need a genuinely new *kind* of companion. For the common case of a
+ * parent/child collection, use `RelatedRecordCollection<T>` via `BaseEntity.DeclareRelatedRecords()` rather than
+ * writing a companion by hand.
+ *
+ * @typeParam TWire - The JSON-safe shape this companion serializes to and from.
+ *
+ * @example Declaring a custom companion on a shared (client + server) entity subclass
+ * ```typescript
+ * class ApprovalTrailCompanion extends EntityCompanion<ApprovalWire> {
+ *     public readonly Name = 'ApprovalTrail';
+ *
+ *     public async Serialize(): Promise<ApprovalWire | null> {
+ *         return this.entries.length ? { Entries: this.entries } : null;
+ *     }
+ *
+ *     public async Deserialize(data: ApprovalWire): Promise<void> {
+ *         this.entries = data.Entries ?? [];
+ *     }
+ * }
+ * ```
+ */
+export declare abstract class EntityCompanion<TWire = unknown> {
+    /**
+     * The entity this companion is attached to. Set by {@link BaseEntity.RegisterCompanion}.
+     */
+    readonly Owner: BaseEntity;
+    /**
+     * @param owner - The entity this companion belongs to.
+     */
+    constructor(owner: BaseEntity);
+    /**
+     * Stable identifier for this companion, unique within its owning entity.
+     *
+     * This is the wire key: it appears in serialized payloads and is how the receiving tier finds
+     * the companion to deserialize into. **Treat it as a published contract** — renaming it breaks
+     * in-flight payloads and any persisted snapshot that captured them.
+     */
+    abstract readonly Name: string;
+    /**
+     * Produces this companion's JSON-safe state for transport, or `null` when it has nothing to
+     * send.
+     *
+     * Returning `null` keeps the companion out of the payload entirely, which matters: a save that
+     * touches only header fields should not ship an empty children array and pay for it on every
+     * request.
+     *
+     * @returns The wire payload, or `null` to omit this companion.
+     */
+    abstract Serialize(): Promise<TWire | null>;
+    /**
+     * Restores this companion's state from a wire payload produced by {@link Serialize} on the
+     * other tier.
+     *
+     * Implementations must be tolerant of payloads written by an older version of themselves —
+     * a companion is a wire contract, and rolling deploys mean both versions run at once.
+     *
+     * @param data - The payload previously produced by {@link Serialize}.
+     * @param mode - Whether this payload is an inbound request or an authoritative result. See
+     *               {@link EntityCompanionDeserializeMode}; the distinction is load-bearing.
+     */
+    abstract Deserialize(data: TWire, mode: EntityCompanionDeserializeMode): Promise<void>;
+    /**
+     * Whether this companion holds unsaved changes.
+     *
+     * Rolled up into `BaseEntity.Dirty`, which is what makes a save actually happen when only the
+     * companion changed. Before companions existed, a clean parent with three new children returned
+     * early from `Save()` and silently persisted nothing.
+     *
+     * @returns True when saving would produce work.
+     */
+    get Dirty(): boolean;
+    /**
+     * Synchronous, in-memory validation contributed by this companion.
+     *
+     * Runs as part of the owner's `Validate()`, **before any write**, over the companion's complete
+     * state — including pending removals. That ordering is what lets cross-child invariants such as
+     * "debits must equal credits" be enforced correctly rather than after half the graph has landed.
+     *
+     * Push errors onto `result.Errors` and set `result.Success = false` to fail the save.
+     *
+     * @param _result - The accumulating validation result to contribute to.
+     */
+    Validate(_result: ValidationResult): void;
+    /**
+     * Asynchronous validation contributed by this companion — anything that needs a round trip.
+     *
+     * @remarks
+     * Unlike an entity's own `ValidateAsync()`, this is **not** governed by
+     * `BaseEntity.DefaultSkipAsyncValidation`. That flag exists so an entity can opt out of its own
+     * expensive async rules; applying it to companions silently skipped cross-child invariants,
+     * which is how `OrderEntityServer.ValidateAsync` came to be dead code on every save. Companion
+     * validation runs whenever the companion is dirty.
+     *
+     * @param _result - The accumulating validation result to contribute to.
+     */
+    ValidateAsync(_result: ValidationResult): Promise<void>;
+    /**
+     * Contributes this companion's work to the owner's save plan.
+     *
+     * Called after the owner's own node has been added, so implementations may assume the parent
+     * node exists and order their nodes relative to it. Add nothing when there is no work — an
+     * empty contribution keeps the save on the fast single-row path.
+     *
+     * @param _plan - The plan being assembled for this unit of work.
+     * @param _options - The caller's save options. Implementations that decide what counts as work
+     *                   (skipping clean children, most importantly) must honor flags such as
+     *                   `IgnoreDirtyState` that demand a full write-out.
+     */
+    ContributeSaveWork(_plan: EntitySavePlan, _options?: EntitySaveOptions): void;
+    /**
+     * Contributes this companion's work to the owner's delete plan.
+     *
+     * Called before the owner's own node, because children must generally be removed before the
+     * parent row they point at. Implementations that rely on database-level cascade delete should
+     * contribute nothing.
+     *
+     * @param _plan - The plan being assembled for this unit of work.
+     */
+    ContributeDeleteWork(_plan: EntitySavePlan): void;
+    /**
+     * Populates this companion from the database, when it is configured to load eagerly.
+     *
+     * Called by `BaseEntity.Load()` after the record's own fields are populated. **Never** called
+     * from `LoadFromData()` — that is the row-materialization path for
+     * `RunView(ResultType:'entity_object')`, so loading children there turns one view into an N+1
+     * storm. Set-oriented eager loading is handled by `RunView`'s batched child loading instead.
+     */
+    LoadEager(): Promise<void>;
+    /**
+     * Resets the companion to its post-save state — clearing pending removals, rebasing dirty
+     * tracking, and so on. Called after the graph commits successfully.
+     */
+    AcceptChanges(): void;
+}
+//# sourceMappingURL=entityCompanion.d.ts.map

package/dist/generic/entityCompanion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityCompanion.d.ts","sourceRoot":"","sources":["../../src/generic/entityCompanion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACjC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,8BAA8B,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,eAAe,CAAC,KAAK,GAAG,OAAO;IACjD;;OAEG;IACH,SAAgB,KAAK,EAAE,UAAU,CAAC;IAElC;;OAEG;gBACS,KAAK,EAAE,UAAU;IAI7B;;;;;;OAMG;IACH,kBAAyB,IAAI,EAAE,MAAM,CAAC;IAEtC;;;;;;;;;OASG;aACa,SAAS,IAAI,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAElD;;;;;;;;;;OAUG;aACa,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,8BAA8B,GAAG,OAAO,CAAC,IAAI,CAAC;IAE7F;;;;;;;;OAQG;IACH,IAAW,KAAK,IAAI,OAAO,CAE1B;IAED;;;;;;;;;;OAUG;IACI,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAIhD;;;;;;;;;;;OAWG;IACU,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAIpF;;;;;;;;OAQG;IACI,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAIxD;;;;;;;OAOG;IACU,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC;;;OAGG;IACI,aAAa,IAAI,IAAI;CAG/B"}

package/dist/generic/entityCompanion.js

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview Entity Companions — named, serialisable side-channels attached to a `BaseEntity`.
+ *
+ * ## What a companion is
+ *
+ * A companion is a piece of state that belongs to a record but is **not one of its fields**, and
+ * that needs to travel with the record across the client/server boundary, participate in its
+ * validation, and contribute work to its save.
+ *
+ * The canonical example is a child collection — an order's lines, a journal entry's lines, a
+ * payment's allocations — but the abstraction is deliberately not about children. It is about
+ * "extra state that rides with the record", because MemberJunction has grown that concept ad hoc
+ * three times already:
+ *
+ * - `OldValues___` on the generated GraphQL save input (concurrency check payload)
+ * - `RestoreContext___` on the same input (restore lineage for the RecordChange row)
+ * - `EntityObjectJSON` in the TransactionGroup wire format (a whole record as opaque JSON)
+ *
+ * Each solved its own problem with its own bespoke slot, resolver branch and hand-written
+ * serialisation. Companions give the next such need — and the ones already in flight — one
+ * mechanism instead of a fourth bespoke field.
+ *
+ * ## What a companion is not
+ *
+ * A companion is **not** a way to smuggle arbitrary untyped data through the platform. Every
+ * companion has a stable {@link EntityCompanion.Name}, a typed wire shape, and explicit control
+ * over what it contributes to validation and save. Data with no owner and no contract belongs in a
+ * field, not here.
+ *
+ * ## Lifecycle
+ *
+ * ```text
+ * declare  →  subclass constructor calls RegisterCompanion() (usually via DeclareRelatedRecords())
+ * load     →  BaseEntity.Load()/LoadFromData() gives eager companions a chance to populate
+ * mutate   →  application code works with the typed companion API
+ * validate →  BaseEntity.Validate()/ValidateAsync() fans out to every companion
+ * save     →  companions contribute nodes to the EntitySavePlan; the graph executes atomically
+ * transport→  Serialize() on the way out, Deserialize() on the way in
+ * ```
+ *
+ * @module @memberjunction/core
+ */
+/**
+ * The property name under which companion payloads are carried inside the plain object produced by
+ * `BaseEntity.GetDataObject()` and consumed by `BaseEntity.LoadFromData()`.
+ *
+ * The trailing triple underscore follows the convention already set by `OldValues___` and
+ * `RestoreContext___`: it marks a reserved, non-field slot and makes accidental collision with a
+ * real column name effectively impossible.
+ */
+export const COMPANION_PAYLOAD_KEY = 'Companions___';
+/**
+ * Base class for all entity companions.
+ *
+ * Subclass this only when you need a genuinely new *kind* of companion. For the common case of a
+ * parent/child collection, use `RelatedRecordCollection<T>` via `BaseEntity.DeclareRelatedRecords()` rather than
+ * writing a companion by hand.
+ *
+ * @typeParam TWire - The JSON-safe shape this companion serializes to and from.
+ *
+ * @example Declaring a custom companion on a shared (client + server) entity subclass
+ * ```typescript
+ * class ApprovalTrailCompanion extends EntityCompanion<ApprovalWire> {
+ *     public readonly Name = 'ApprovalTrail';
+ *
+ *     public async Serialize(): Promise<ApprovalWire | null> {
+ *         return this.entries.length ? { Entries: this.entries } : null;
+ *     }
+ *
+ *     public async Deserialize(data: ApprovalWire): Promise<void> {
+ *         this.entries = data.Entries ?? [];
+ *     }
+ * }
+ * ```
+ */
+export class EntityCompanion {
+    /**
+     * @param owner - The entity this companion belongs to.
+     */
+    constructor(owner) {
+        this.Owner = owner;
+    }
+    /**
+     * Whether this companion holds unsaved changes.
+     *
+     * Rolled up into `BaseEntity.Dirty`, which is what makes a save actually happen when only the
+     * companion changed. Before companions existed, a clean parent with three new children returned
+     * early from `Save()` and silently persisted nothing.
+     *
+     * @returns True when saving would produce work.
+     */
+    get Dirty() {
+        return false;
+    }
+    /**
+     * Synchronous, in-memory validation contributed by this companion.
+     *
+     * Runs as part of the owner's `Validate()`, **before any write**, over the companion's complete
+     * state — including pending removals. That ordering is what lets cross-child invariants such as
+     * "debits must equal credits" be enforced correctly rather than after half the graph has landed.
+     *
+     * Push errors onto `result.Errors` and set `result.Success = false` to fail the save.
+     *
+     * @param _result - The accumulating validation result to contribute to.
+     */
+    Validate(_result) {
+        /* no-op by default */
+    }
+    /**
+     * Asynchronous validation contributed by this companion — anything that needs a round trip.
+     *
+     * @remarks
+     * Unlike an entity's own `ValidateAsync()`, this is **not** governed by
+     * `BaseEntity.DefaultSkipAsyncValidation`. That flag exists so an entity can opt out of its own
+     * expensive async rules; applying it to companions silently skipped cross-child invariants,
+     * which is how `OrderEntityServer.ValidateAsync` came to be dead code on every save. Companion
+     * validation runs whenever the companion is dirty.
+     *
+     * @param _result - The accumulating validation result to contribute to.
+     */
+    async ValidateAsync(_result) {
+        /* no-op by default */
+    }
+    /**
+     * Contributes this companion's work to the owner's save plan.
+     *
+     * Called after the owner's own node has been added, so implementations may assume the parent
+     * node exists and order their nodes relative to it. Add nothing when there is no work — an
+     * empty contribution keeps the save on the fast single-row path.
+     *
+     * @param _plan - The plan being assembled for this unit of work.
+     * @param _options - The caller's save options. Implementations that decide what counts as work
+     *                   (skipping clean children, most importantly) must honor flags such as
+     *                   `IgnoreDirtyState` that demand a full write-out.
+     */
+    ContributeSaveWork(_plan, _options) {
+        /* no-op by default */
+    }
+    /**
+     * Contributes this companion's work to the owner's delete plan.
+     *
+     * Called before the owner's own node, because children must generally be removed before the
+     * parent row they point at. Implementations that rely on database-level cascade delete should
+     * contribute nothing.
+     *
+     * @param _plan - The plan being assembled for this unit of work.
+     */
+    ContributeDeleteWork(_plan) {
+        /* no-op by default */
+    }
+    /**
+     * Populates this companion from the database, when it is configured to load eagerly.
+     *
+     * Called by `BaseEntity.Load()` after the record's own fields are populated. **Never** called
+     * from `LoadFromData()` — that is the row-materialization path for
+     * `RunView(ResultType:'entity_object')`, so loading children there turns one view into an N+1
+     * storm. Set-oriented eager loading is handled by `RunView`'s batched child loading instead.
+     */
+    async LoadEager() {
+        /* no-op by default */
+    }
+    /**
+     * Resets the companion to its post-save state — clearing pending removals, rebasing dirty
+     * tracking, and so on. Called after the graph commits successfully.
+     */
+    AcceptChanges() {
+        /* no-op by default */
+    }
+}
+//# sourceMappingURL=entityCompanion.js.map

package/dist/generic/entityCompanion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityCompanion.js","sourceRoot":"","sources":["../../src/generic/entityCompanion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAoBH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAgBrD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAgB,eAAe;IAMjC;;OAEG;IACH,YAAY,KAAiB;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAoCD;;;;;;;;OAQG;IACH,IAAW,KAAK;QACZ,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;;OAUG;IACI,QAAQ,CAAC,OAAyB;QACrC,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,aAAa,CAAC,OAAyB;QAChD,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,KAAqB,EAAE,QAA4B;QACzE,sBAAsB;IAC1B,CAAC;IAED;;;;;;;;OAQG;IACI,oBAAoB,CAAC,KAAqB;QAC7C,sBAAsB;IAC1B,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,SAAS;QAClB,sBAAsB;IAC1B,CAAC;IAED;;;OAGG;IACI,aAAa;QAChB,sBAAsB;IAC1B,CAAC;CACJ"}

package/dist/generic/entityInfo.d.ts

@@ -73,6 +73,27 @@ export declare class EntityRelationshipInfo extends BaseInfo {
     * * Description: Indicates whether this relationship should be automatically updated by CodeGen. When set to 0, the record will not be modified by CodeGen. Defaults to true.
     */
     AutoUpdateFromSchema: boolean;
+    /**
+    * * Field Name: RelatedRecordCollection
+    * * SQL Data Type: nvarchar(MAX), nullable
+    *
+    * Optional JSON policy object declaring this relationship as a first-class **related-record
+    * collection** — a set of records that load, validate and persist as one unit with the parent.
+    * When non-null, CodeGen emits a typed `DeclareRelatedRecords(...)` declaration onto the
+    * generated entity subclass, so applications no longer hand-write it.
+    *
+    * Shape is `IRelatedRecordCollectionConfig`: `Name` (the generated property name, e.g. `Lines`),
+    * `Load`, `OnRemove`, `OrderBy`, `Sequence` and `ClearAfterSave`. {@link RelatedEntity} and
+    * {@link RelatedEntityJoinField} are deliberately **not** repeated inside the JSON — they are
+    * already columns on this row, and duplicating them would create two sources of truth with the
+    * JSON copy winning silently.
+    *
+    * `null` (the default, and every pre-6.2 row) means the relationship is not a declared
+    * collection: nothing is generated and nothing loads eagerly.
+    *
+    * @see guides/TRANSACTIONS_AND_BATCHING_GUIDE.md
+    */
+    RelatedRecordCollection: string;
     Entity: string;
     EntityBaseTable: string;
     EntityBaseView: string;
@@ -954,6 +975,57 @@ export declare class EntityInfo extends BaseInfo {
      * Whether the base view is generated by CodeGen (true) or manually created (false)
      */
     BaseViewGenerated: boolean;
+    /**
+     * When set, CodeGen generates the entity's full base view under THIS name instead of
+     * {@link BaseView}, and the application owns `BaseView` — which is expected to wrap it:
+     *
+     * ```sql
+     * CREATE VIEW vwOrderHeaders AS
+     * SELECT g.*, CASE WHEN ... END AS IsOverdue
+     * FROM   vwOrderHeadersGenerated g
+     * ```
+     *
+     * This is how an entity gets a custom base view WITHOUT inheriting the generated SQL. With
+     * `BaseViewGenerated = 0` alone the application takes over the whole view — every related-entity
+     * display join, the geo join, the recursive root-ID apply — and must hand-maintain it forever;
+     * a foreign key added later then silently never appears, because nothing regenerates the join.
+     * Naming an inner view keeps all of that regenerating underneath a thin, reviewable custom layer.
+     *
+     * NULL (the default, and every pre-existing entity) preserves the original behaviour exactly:
+     * `BaseViewGenerated` alone decides whether CodeGen writes `BaseView`, and there is no second view.
+     *
+     * `BaseView` remains the public surface either way — field discovery, permissions and the
+     * generated CRUD procedures all target it, so a column added by the custom layer becomes a
+     * first-class virtual `EntityField`.
+     */
+    GeneratedBaseViewName: string;
+    /**
+     * The view CodeGen actually WRITES for this entity.
+     *
+     * Normally {@link BaseView}. When {@link GeneratedBaseViewName} is set, the generated SQL goes
+     * there instead and `BaseView` belongs to the application, which layers over it — see
+     * {@link HasLayeredBaseView}.
+     *
+     * Resolved in ONE place because the two names must never drift: several call sites decide where
+     * to write the view, what to call the emitted file, and which object to refresh, and a
+     * disagreement between any two of them produces a view that exists under a name nothing reads.
+     *
+     * Derived FROM {@link HasLayeredBaseView} rather than re-testing `GeneratedBaseViewName`, so the
+     * two getters cannot disagree by construction. Testing the raw column here would diverge on a
+     * name that differs from `BaseView` only by case: `HasLayeredBaseView` would say "not layered"
+     * (it compares case-insensitively, because SQL Server object names are) while this getter
+     * returned the differently-cased string — leaving CodeGen writing to one object while every
+     * layering-gated code path believed there was no second view at all.
+     */
+    get GeneratedViewName(): string;
+    /**
+     * True when this entity has a generated inner view with an application-owned `BaseView` on top.
+     *
+     * In that arrangement CodeGen still generates everything — related-entity display fields, geo
+     * columns, recursive root-ID columns — into {@link GeneratedViewName}, so the custom layer stays
+     * thin and does not go stale when the schema gains a foreign key.
+     */
+    get HasLayeredBaseView(): boolean;
     /**
      * Database schema that contains this entity's table and view
      */
@@ -1038,6 +1110,47 @@ export declare class EntityInfo extends BaseInfo {
      * Global flag controlling whether records can be deleted via API
      */
     AllowDeleteAPI: boolean;
+    /**
+     * Whether rows may be INSERTed by SQL that does not go through {@link BaseEntity}.Save() —
+     * bulk loads, ETL/integration sync, or rows created as a side effect of a stored procedure.
+     *
+     * `false` (the default, and every entity that has not opted in) means all inserts are expected
+     * to flow through `BaseEntity`, which is the only path where record-change tracking, entity
+     * actions, validation and cache invalidation actually run.
+     *
+     * **This DECLARES intent; it enforces nothing.** No constraint, trigger or grant prevents
+     * anyone from executing SQL. It exists so the code paths and tooling that *choose* to honour
+     * the platform contract — bulk/ETL and integration sync, record-set processing, and generators
+     * or agents authoring SQL — have one authoritative answer instead of tribal knowledge.
+     *
+     * A database CHECK requires {@link TrackRecordChanges} and {@link TrustServerCacheCompletely}
+     * to both be `false` when this is set, because a direct insert produces neither an audit row
+     * nor a cache-invalidation event — leaving either on yields an audit trail that looks complete
+     * but is not, and a server cache that serves stale rows indefinitely.
+     */
+    AllowDirectSQLInsert: boolean;
+    /**
+     * Whether rows may be UPDATEd by SQL that does not go through {@link BaseEntity}.Save() —
+     * bulk backfills, integration sync, or maintenance routines.
+     *
+     * `false` (the default) means all updates are expected to flow through `BaseEntity`. See
+     * {@link AllowDirectSQLInsert} for the full rationale, the "declares, does not enforce"
+     * caveat, and the `TrackRecordChanges` / `TrustServerCacheCompletely` requirement.
+     */
+    AllowDirectSQLUpdate: boolean;
+    /**
+     * Whether rows may be DELETEd by SQL that does not go through {@link BaseEntity}.Delete() —
+     * purge and retention routines, or integration sync reconciling against a remote source.
+     *
+     * `false` (the default) means all deletes are expected to flow through `BaseEntity`. See
+     * {@link AllowDirectSQLInsert} for the full rationale and the `TrackRecordChanges` /
+     * {@link TrustServerCacheCompletely} requirement.
+     *
+     * Additionally requires {@link DeleteType} to be `'Hard'`: a direct `DELETE` removes the row
+     * outright rather than setting `DeletedAt`, so sanctioning it on a soft-delete entity would
+     * quietly defeat soft delete. A database CHECK refuses the combination.
+     */
+    AllowDirectSQLDelete: boolean;
     /**
      * If true, uses a custom resolver for GraphQL operations instead of standard CRUD
      */
@@ -1483,12 +1596,45 @@ export declare class EntityInfo extends BaseInfo {
     GetUserRowLevelSecurityInfo(user: UserInfo, type: EntityPermissionType): RowLevelSecurityFilterInfo[];
     /**
      * Generates a where clause for SQL filtering for a given entity for a given user and permission type. If there is no RLS for a given entity or the user is exempt from RLS for the entity, a blank string is returned.
+     *
+     * @deprecated ROLE RLS ONLY — this method is subject to the role-RLS exemption and
+     * silently omits API-key row filters, so a caller reaching for this familiar name gets
+     * a clause that is fail-open for filtered API-key sessions. Use
+     * {@link GetEffectiveRowFilterWhereClause}, which composes every filter layer. A repo
+     * test asserts no non-test caller exists outside that method.
      * @param user
      * @param type
      * @param returnPrefix
      * @returns
      */
     GetUserRowLevelSecurityWhereClause(user: UserInfo, type: EntityPermissionType, returnPrefix: string): string;
+    /**
+     * The EFFECTIVE row-filter clause for a user + permission type: role RLS (subject to the
+     * role exemption) AND the API-key row filters carried on the session (NOT subject to the
+     * role exemption — a key ceiling exists precisely to bind principals whose roles are
+     * unrestricted; see UserExemptFromRowLevelSecurity, which exempts off the mere presence
+     * of a filter-less permission row). Composition: OR within the role layer (roles are
+     * additive), AND across layers (no layer can widen another). Returns '' only when no
+     * layer contributes.
+     *
+     * This is THE method every enforcement point must call. Deterministic by construction —
+     * key-filter clauses render in FilterID order and list tokens sort their elements —
+     * because the identical clause participates in the RunView cache fingerprint (INV-2):
+     * any nondeterminism silently splits or merges cache slots.
+     *
+     * The application-ceiling layer (APIApplicationScope.RowFilterID) is deferred to v2 by
+     * design decision; the column ships unused and the term composes here when it lands.
+     */
+    GetEffectiveRowFilterWhereClause(user: UserInfo, type: EntityPermissionType, returnPrefix: string): string;
+    /**
+     * Resolves the API-key row-filter clause for this entity + permission type from the
+     * bindings stamped on the session UserInfo. Multiple matching bindings AND together
+     * (most-restrictive-wins — an unfiltered grant elsewhere cannot cancel a filter).
+     * Fail-closed at every edge: a binding whose filter is missing from metadata (dangling
+     * or unloaded) contributes `(1=0)`, and unresolved tokens inside a filter collapse it
+     * to `(1=0)` via the match-nothing markup mode.
+     */
+    private getAPIKeyRowFilterClause;
     /**
      * Returns a RunViewParams object that is setup to filter the related entity for the provided record
      * @param record