@memberjunction/core-entities-server 6.2.0-edge.6 → 6.2.0-edge.7

package/dist/custom/MJQueryEntityServer.server.d.ts

@@ -1,20 +1,49 @@
 import { EntitySaveOptions, SimpleEmbeddingResult } from "@memberjunction/core";
 import { MJQueryEntityExtended } from "@memberjunction/core-entities";
+import type { DeclaredQueryChildren, QueryExtractionOverride, QueryExtractionResult, ChildRowWriteSummary } from "./query-extraction/index.js";
 /**
- * Server-side query entity with embedding generation, SQL extraction pipeline,
- * and dialect auto-conversion. Extends `MJQueryEntityExtended` which provides
- * child-relationship getters and business logic available on both client and server.
+ * Server-side query entity with embedding generation, SQL extraction, and dialect auto-conversion.
+ * Extends `MJQueryEntityExtended`, which provides the child-relationship getters and business
+ * logic available on both client and server.
+ *
+ * **Extraction.** A save of a new query, of a query whose SQL changed, or with
+ * {@link ExtractionOverride} `Force`, establishes the query's facts (`ComputeQueryExtraction`):
+ * its parameters, compositions and the entities it reads from MJ's parser, and its output fields
+ * from the database server's description of each render. Save-time rule errors and repeated
+ * output names refuse a new or edited query, with the reasons in the save's result. Once the save
+ * of the query row succeeds, the child rows are brought in line with the facts as the system user,
+ * keeping what people authored (`WriteExtractedChildRows`), and the query's `UsesTemplate`,
+ * `ExtractedSQLHash`, `ExtractionStatus` and `ExtractionMessage` record the run. Empty
+ * descriptions are then filled by an LLM after the save's transaction commits, unless the save
+ * skips AI actions.
  */
 export declare class MJQueryEntityServer extends MJQueryEntityExtended {
-    /** Optional caller-provided parameter sample values. When set, these override
-     *  LLM-generated sampleValues during the extraction pipeline. Use this to pass
-     *  tested/validated values from the calling system.
-     *  Keys are parameter names, values are the tested sample values. */
+    /** Optional caller-provided parameter sample values. When set, these are used as the sample of a
+     *  parameter extraction adds, and in the renders that are described. Use this to pass tested,
+     *  validated values from the calling system. Keys are parameter names. */
     ParameterHints?: Map<string, string>;
+    /**
+     * What the next save does about extraction: `Auto` (the default) extracts when the query is new
+     * or its SQL changed; `Skip` does not extract, so the save-time rules are not applied and the
+     * child rows, the Extraction columns and `UsesTemplate` stay as they are (for bulk loaders and
+     * fixtures that write those themselves); `Force` extracts even when the SQL did not change.
+     * Reset to `Auto` after each save.
+     */
+    ExtractionOverride: QueryExtractionOverride;
+    /** The SQL a re-extraction reads instead of the cached platform variant (set by {@link RerunExtraction}). */
+    private platformSQLOverride;
+    /** The facts an explicit refresh already established, which its save writes instead of extracting again. */
+    private presetExtraction;
+    /** Whether the running save is an explicit refresh ({@link ApplyRefreshAsync}). */
+    private refreshing;
+    /** What the last save's child-row writes changed; `null` when it wrote none. */
+    private lastWriteSummary;
     /**
      * Simple proxy to local helper method for embeddings. Needed for BaseEntity sub-classes that want to use embeddings built into BaseEntity
      */
     protected EmbedTextLocal(textToEmbed: string): Promise<SimpleEmbeddingResult>;
+    /** A stored vector from a model other than the default local one is re-embedded on save. */
+    protected IsEmbeddingStale(embeddingModelID: string | null): Promise<boolean>;
     /**
      * Generates an embedding from composite text (Name + UserQuestion + Description) for richer semantic search.
      * Stores the vector in EmbeddingVector (JSON) and EmbeddingVectorBinary (float32 bytes, base64), and the
@@ -24,11 +53,79 @@ export declare class MJQueryEntityServer extends MJQueryEntityExtended {
      * embedder error — all three columns are cleared, so a query whose text changed never keeps a vector
      * computed from its old text. An embedder error is logged and does not fail the save; the query simply
      * has no semantic match until its next successful embedding.
+     *
+     * Does nothing when {@link SkipEmbeddings} is set (a bulk load computes them later), so the stored
+     * vector is left as it is.
+     *
+     * @param textChanged - false when the text is unchanged and only the stored vector's model is stale:
+     *   a failed embed then keeps the existing vector, which still matches the text.
      */
-    protected GenerateCompositeEmbedding(): Promise<void>;
+    protected GenerateCompositeEmbedding(textChanged?: boolean): Promise<void>;
     /** Clears the stored vector (both forms) and the model it was computed with. */
     private clearEmbedding;
+    /** Re-embeds when the embedded text changed, or when the stored vector came from a model other than the default local one. */
+    private refreshEmbeddingAsync;
     Save(options?: EntitySaveOptions): Promise<boolean>;
+    /** Whether this object saves through a network (client) provider rather than to a database. */
+    private get savesOverNetwork();
+    /**
+     * The save: facts first (a refusal writes nothing), then the query row (a graph save with any
+     * declared children), then the child rows extraction derives, then the approval fingerprint.
+     */
+    private saveWithExtractionAsync;
+    private get hasSQL();
+    /**
+     * Whether this save extracts, and under which rules: a new or edited query extracts under the
+     * save-time rules; a save that writes declared child rows, or a `Force` override, re-extracts an
+     * unchanged query under the refresh rules, so the facts of rows it writes are corrected again.
+     */
+    private planExtraction;
+    /**
+     * Sets the columns a save records about the SQL before the row is written. `UsesTemplate` is a
+     * lexical fact and follows every SQL change; it is never changed by a failed extraction. A save
+     * with {@link ExtractionOverride} `Skip` leaves it as the caller set it, like the other
+     * extraction results.
+     */
+    private applyRunColumns;
+    /**
+     * Gives each field row this save declares the facts extraction established for it, before the
+     * graph is written. Facts follow the SQL and the database server whatever a caller declares, so
+     * a declaration that carries facts (types, nullability, sequence, source) for another platform is
+     * corrected before it is written instead of being written and then corrected, and a new declared
+     * row, which may declare only its name and annotations, gets the facts its columns require.
+     */
+    private applyFactsToDeclaredFields;
+    /** Whether the SQL holds a template tag outside comments, read by the lexer. */
+    private lexicalUsesTemplate;
+    /** The save's result entry for a refused save, carrying the reasons. */
+    private refusalResult;
+    /**
+     * The declared-rows-win hook, run before the save writes anything.
+     *
+     * A caller can save a query together with child rows it declares, through the `Parameters`,
+     * `Fields` and `Entities` collections. When a NEW declared row has the key of a stored row with a
+     * different ID whose `DetectionMethod` is not `Manual` (a row extraction created), the stored row
+     * is deleted inside the same graph save, before the declared row is inserted. The declared row
+     * keeps the ID the caller gave it, which is what makes a metadata file that names its child IDs
+     * converge instead of colliding with rows extraction wrote earlier. A stored `Manual` row is never
+     * deleted here; a declared row that collides with one fails the save on the database's own
+     * uniqueness rule where there is one.
+     *
+     * Extraction then runs after `super.Save()`, sees the declared rows already written, and treats
+     * them like any stored row: their facts are corrected from the SQL, their authored annotations
+     * kept.
+     *
+     * @param options - The save's options. A `ReplayOnly` save, or one that skips related
+     *   collections, writes no declared rows, so nothing is declared.
+     * @returns The keys of the child rows this save declares.
+     */
+    protected PrepareDeclaredChildrenAsync(options?: EntitySaveOptions): Promise<DeclaredQueryChildren>;
+    /**
+     * Reads the stored child rows from the database (never a cache, which inside a transaction can
+     * miss rows written earlier in it) and queues the extraction-created rows each new declared row
+     * replaces for deletion in the graph save.
+     */
+    private queueReplacedRowDeletionsAsync;
     /**
      * Stores the fingerprint of the definition just approved: this row's SQL, template flag and
      * external source, with its dialect and parameter rows read back from the database. Until this
@@ -39,55 +136,92 @@ export declare class MJQueryEntityServer extends MJQueryEntityExtended {
     private loadDefinitionRowsAsync;
     Delete(options?: EntitySaveOptions): Promise<boolean>;
     /**
-     * Returns the database platform of the connected database.
-     * Uses the DB_PLATFORM env var (same source as MJServer's provider selection).
+     * The platform the query is extracted for: the platform of the provider this entity saves
+     * through, so two providers on different platforms in one process each extract for their own.
      */
-    private get currentPlatform();
+    private get extractionPlatform();
+    /** The provider as extraction reads and writes through it; `null` when it cannot read views and create entity objects. */
+    private get extractionProvider();
     /**
-     * Resolves the SQL to use for extraction based on the current database platform.
-     *
-     * Resolution order:
-     *   1. MJ: Query SQLs record matching the current platform's dialect → use that SQL
-     *   2. Base Query.SQL field → fall back if no dialect variant exists
-     *
-     * After resolution, validates the SQL is compatible with the current platform's
-     * dialect by attempting a parse. Logs a warning if the SQL appears to be for a
-     * different dialect (e.g., T-SQL bracket identifiers on a PostgreSQL database).
+     * The user derived child rows are read and written as: the system user, once the caller's save
+     * of the query is authorized (the rows mirror SQL the caller was allowed to change, like CodeGen
+     * output). The caller when no system user is loaded.
      */
-    private resolveExtractionSQL;
+    private get extractionUser();
+    /** The SQL extraction reads: a re-extraction's override, else the query's SQL for the platform. */
+    private get extractionSQL();
+    /** Establishes the query's facts (nothing is written); an explicit refresh's facts when it already has them. */
+    private computeExtractionAsync;
     /**
-     * Best-effort dialect validation: attempts to parse the SQL with the current platform's
-     * dialect. If parsing throws, logs a warning — the SQL may be for a different dialect.
-     *
-     * This is a heuristic, not a guarantee: node-sql-parser is permissive on many
-     * dialect-specific functions (ISNULL, GETDATE pass in both dialects), so a passing
-     * parse does not prove the SQL is correct for this dialect. But a failing parse is a
-     * strong signal of incompatibility.
+     * The queries the SQL composes, read on this save's provider with every cache bypassed, so a
+     * target saved earlier in the same transaction (one metadata push creating both queries) is
+     * found before the shared query cache hears of it. Nothing is read for SQL that composes
+     * nothing, or on a provider that cannot run views.
+     */
+    private readCompositionTargetsAsync;
+    /** Loads QueryEngine when this process has not yet (a CLI or sync context); compositions resolve against it. */
+    private ensureQueryEngineLoadedAsync;
+    /**
+     * The parameter rows extraction knows before it runs: the stored rows, read from the database
+     * (never the cache), overlaid by the rows this save declares.
      */
-    private validateDialectCompatibility;
+    private knownParametersAsync;
+    private storedParametersAsync;
     /**
-     * Builds the QuerySyncContext from this entity instance for use by the extraction pipeline.
-     * Resolves the SQL to the appropriate dialect variant for the connected database.
+     * Writes the derived child rows as the system user, inside the caller's transaction when there
+     * is one, then queues the description pass. A failed write is recorded on the query
+     * (`ExtractionStatus` `Error`) rather than failing a save whose row is already written.
      */
-    private buildSyncContext;
+    private writeExtractionAsync;
+    /** An entity's name from the saving provider's catalog, for reporting; the ID when it is not there. */
+    private entityNameOf;
+    private recordWriteFailureAsync;
+    /** The post-commit token of the caller's transaction, captured before the save writes anything. */
+    private capturePostCommitToken;
     /**
-     * Re-runs the extraction pipeline on this query. Called by MJQuerySQLEntityServer
-     * when a dialect variant matching the current platform is saved — this handles
-     * the timing issue where the parent Query is saved before its QuerySQL children
-     * exist in the cache.
+     * Queues the LLM description pass to run after the caller's transaction commits, when some row
+     * has no description and the save does not skip AI actions. No LLM call is made inside the
+     * transaction. A save-triggered extraction that changed no child row does not queue it: the
+     * rows are as the last run left them, so a repeated save (a re-push of unchanged metadata) does
+     * not call the LLM again, and a pass that failed is not retried, and recorded, on every save.
+     * An explicit refresh that asks for the pass always queues it.
+     */
+    private queueDescriptionPass;
+    /**
+     * Re-extracts this query: a save with {@link ExtractionOverride} `Force`. Called by
+     * `MJQuerySQLEntityServer` when a dialect variant for the current platform is saved.
      *
-     * @param skipAIEnrichment Skip the LLM enrichment stage, as `SkipEntityAIActions` does for Save.
+     * @param skipAIEnrichment Skip the description pass, as `SkipEntityAIActions` does for a save.
+     * @param platformSQL The SQL to extract from (the variant just saved), instead of the cached
+     *   platform variant, which inside a transaction may not hold it yet.
+     */
+    RerunExtraction(skipAIEnrichment?: boolean, platformSQL?: string): Promise<void>;
+    /**
+     * Establishes this saved query's facts under the refresh rules (a save-time rule error is
+     * recorded, never a refusal), as the save would, and writes nothing. The facts are read on the
+     * provider this entity was loaded with, for its platform.
      */
-    RerunExtraction(skipAIEnrichment?: boolean): Promise<void>;
+    ComputeRefreshExtractionAsync(): Promise<QueryExtractionResult>;
     /**
-     * Runs the extraction pipeline and saves the UsesTemplate flag.
-     * On error, sets UsesTemplate=false and attempts to save so the query remains usable.
+     * The child-row changes `extraction` would make, worked out against the rows stored now and
+     * read as this entity's context user. Nothing is written.
+     */
+    PreviewRefreshAsync(extraction: QueryExtractionResult, entityName?: (entityID: string) => string): Promise<ChildRowWriteSummary>;
+    /**
+     * Writes `extraction` (from {@link ComputeRefreshExtractionAsync}): a save with
+     * {@link ExtractionOverride} `Force` that records the run on the query and brings the child
+     * rows in line with the facts. Unlike a save-triggered extraction, the child rows are written
+     * as this entity's context user, so each write is checked against that user's permissions, and
+     * a failed write fails the refresh instead of being recorded on the query. SQL, dialect
+     * variants and the embedding are never written.
      *
-     * @param skipAIEnrichment Skip the LLM enrichment stage (the save asked to skip AI actions).
+     * @param withAI Queue the LLM description pass for rows still without a description.
+     * @returns What the child-row writes changed.
+     * @throws Error when the save or a child-row write fails; the caller's transaction should be rolled back.
      */
-    private extractAndSyncDataAsync;
+    ApplyRefreshAsync(extraction: QueryExtractionResult, withAI: boolean): Promise<ChildRowWriteSummary | null>;
     /**
-     * Cleans up all extraction data when SQL is empty, then saves the updated UsesTemplate flag.
+     * Cleans up all extraction data when SQL is empty.
      */
     private cleanupEmptyQueryAsync;
     /**
@@ -103,9 +237,5 @@ export declare class MJQueryEntityServer extends MJQueryEntityExtended {
      * Creates or updates a QuerySQL record for the given dialect.
      */
     private upsertQuerySQLRecord;
-    /**
-     * Removes all QuerySQL records for this query. Called during cleanup operations.
-     */
-    private removeAllQuerySQLRecordsAsync;
 }
 //# sourceMappingURL=MJQueryEntityServer.server.d.ts.map

package/dist/custom/MJQueryEntityServer.server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MJQueryEntityServer.server.d.ts","sourceRoot":"","sources":["../../src/custom/MJQueryEntityServer.server.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,iBAAiB,EAGjB,qBAAqB,EAExB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAIH,qBAAqB,EAIxB,MAAM,+BAA+B,CAAC;AAcvC;;;;GAIG;AACH,qBACa,mBAAoB,SAAQ,qBAAqB;IAC1D;;;yEAGqE;IAC9D,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAI5C;;OAEG;cACsB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI5F;;;;;;;;;OASG;cACa,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B3D,gFAAgF;IAChF,OAAO,CAAC,cAAc;IAQP,IAAI,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAuDlE;;;;OAIG;YACW,6BAA6B;IAW3C,gFAAgF;YAClE,uBAAuB;IActB,MAAM,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBpE;;;OAGG;IACH,OAAO,KAAK,eAAe,GAE1B;IAED;;;;;;;;;;OAUG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;;;;;;;OAQG;IACH,OAAO,CAAC,4BAA4B;IAgBpC;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAexB;;;;;;;OAOG;IACU,eAAe,CAAC,gBAAgB,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrE;;;;;OAKG;YACW,uBAAuB;IAsBrC;;OAEG;YACW,sBAAsB;IAmBpC;;;OAGG;YACW,wBAAwB;IAiCtC;;OAEG;YACW,sBAAsB;IA4BpC;;OAEG;YACW,oBAAoB;IA4BlC;;OAEG;YACW,6BAA6B;CAgB9C"}
+{"version":3,"file":"MJQueryEntityServer.server.d.ts","sourceRoot":"","sources":["../../src/custom/MJQueryEntityServer.server.ts"],"names":[],"mappings":"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"}