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

package/dist/custom/query-extraction/descriptionPass.d.ts

@@ -0,0 +1,23 @@
+import type { IMetadataProvider, IRunViewProvider, UserInfo } from "@memberjunction/core";
+/** What the description pass works on. */
+export interface DescriptionPassRequest {
+    readonly QueryID: string;
+    readonly QueryName: string;
+    /** The query's SQL, as the prompt reads it. */
+    readonly SQL: string;
+    readonly Provider: IMetadataProvider & IRunViewProvider;
+    /** The user the rows are written as. */
+    readonly User: UserInfo;
+}
+/**
+ * Asks the LLM for descriptions of the query's fields and parameters whose description is still
+ * empty, and writes only those descriptions. It never sets a name, type, source or any other fact,
+ * and never replaces a description that is already there (authored, from a doc comment, or
+ * written earlier).
+ *
+ * Meant to run after the save's transaction commits (`RunAfterCommit`), so no LLM call is made
+ * while a transaction is open. A failure is recorded on the query: `ExtractionMessage` gets the
+ * reason and an `OK` status becomes `Warning`. Never throws.
+ */
+export declare function RunDescriptionPass(request: DescriptionPassRequest): Promise<void>;
+//# sourceMappingURL=descriptionPass.d.ts.map

package/dist/custom/query-extraction/descriptionPass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptionPass.d.ts","sourceRoot":"","sources":["../../../src/custom/query-extraction/descriptionPass.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAc,iBAAiB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAmBtG,0CAA0C;AAC1C,MAAM,WAAW,sBAAsB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IACxD,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvF"}

package/dist/custom/query-extraction/descriptionPass.js

@@ -0,0 +1,95 @@
+import { AIEngine } from "@memberjunction/aiengine";
+import { AIPromptRunner } from "@memberjunction/ai-prompts";
+import { AIPromptParams } from "@memberjunction/ai-core-plus";
+import { LogError, RunMaybeSerial } from "@memberjunction/core";
+import { EscapeSQLString } from "@memberjunction/global";
+const PROMPT_NAME = 'SQL Query Parameter Extraction';
+const PROMPT_CATEGORY = 'MJ: System';
+/**
+ * Asks the LLM for descriptions of the query's fields and parameters whose description is still
+ * empty, and writes only those descriptions. It never sets a name, type, source or any other fact,
+ * and never replaces a description that is already there (authored, from a doc comment, or
+ * written earlier).
+ *
+ * Meant to run after the save's transaction commits (`RunAfterCommit`), so no LLM call is made
+ * while a transaction is open. A failure is recorded on the query: `ExtractionMessage` gets the
+ * reason and an `OK` status becomes `Warning`. Never throws.
+ */
+export async function RunDescriptionPass(request) {
+    try {
+        const [fields, parameters] = await loadUndescribedRows(request);
+        if (fields.length === 0 && parameters.length === 0)
+            return;
+        const described = await askForDescriptions(request, fields, parameters);
+        const writes = [...applyDescriptions(fields, described.fields), ...applyDescriptions(parameters, described.parameters)];
+        const outcomes = await RunMaybeSerial(request.Provider, writes);
+        if (outcomes.some(ok => !ok))
+            throw new Error('some descriptions could not be saved');
+    }
+    catch (e) {
+        await recordFailure(request, e instanceof Error ? e.message : String(e));
+    }
+}
+/** The field and parameter rows whose description is empty, read from the database. */
+async function loadUndescribedRows(request) {
+    const filter = `QueryID='${EscapeSQLString(request.QueryID)}' AND (Description IS NULL OR Description = '')`;
+    const load = async (entityName) => {
+        const result = await request.Provider.RunView({ EntityName: entityName, ExtraFilter: filter, ResultType: 'entity_object', BypassCache: true, IgnoreMaxRows: true }, request.User);
+        if (!result.Success)
+            throw new Error(`could not read the ${entityName}: ${result.ErrorMessage}`);
+        return result.Results ?? [];
+    };
+    return Promise.all([load('MJ: Query Fields'), load('MJ: Query Parameters')]);
+}
+async function askForDescriptions(request, fields, parameters) {
+    await AIEngine.Instance.Config(false, request.User, request.Provider);
+    const prompt = AIEngine.Instance.Prompts.find(p => p.Name === PROMPT_NAME && p.Category === PROMPT_CATEGORY);
+    if (!prompt)
+        throw new Error(`the prompt "${PROMPT_NAME}" was not found`);
+    const params = new AIPromptParams();
+    params.prompt = prompt;
+    params.contextUser = request.User;
+    params.data = {
+        templateText: request.SQL,
+        fields: fields.map(f => ({ name: f.Name, type: f.SQLFullType, source: f.SourceEntityField ?? f.SourceObjectName ?? null, isComputed: f.IsComputed })),
+        parameters: parameters.map(p => ({ name: p.Name, type: p.Type, isRequired: p.IsRequired === true })),
+    };
+    const result = await new AIPromptRunner().ExecutePrompt(params);
+    if (!result.success || !result.result)
+        throw new Error(result.errorMessage || 'the prompt returned no result');
+    return result.result;
+}
+/** Writes for the rows the result describes; a row whose description was filled meanwhile is left alone. */
+function applyDescriptions(rows, described) {
+    const byName = new Map((described ?? []).filter(d => typeof d?.description === 'string' && d.description.trim()).map(d => [String(d.name).toLowerCase(), d.description.trim()]));
+    const writes = [];
+    for (const row of rows) {
+        const description = byName.get(row.Name.toLowerCase());
+        if (!description)
+            continue;
+        row.Description = description;
+        if ('SQLFullType' in row && row.DetectionMethod === 'Database')
+            row.DetectionMethod = 'AI';
+        writes.push(() => row.Save());
+    }
+    return writes;
+}
+/** Records a failed pass on the query: the reason in `ExtractionMessage`, and `OK` raised to `Warning`. */
+async function recordFailure(request, reason) {
+    try {
+        const query = await request.Provider.GetEntityObject('MJ: Queries', request.User);
+        if (!await query.Load(request.QueryID))
+            return;
+        const line = `The LLM description pass failed: ${reason.trim().replace(/\.+$/, '')}. Empty descriptions were left empty.`;
+        query.ExtractionMessage = query.ExtractionMessage ? `${query.ExtractionMessage}\n${line}` : line;
+        if (query.ExtractionStatus === 'OK' || query.ExtractionStatus === null)
+            query.ExtractionStatus = 'Warning';
+        if (!await query.Save({ SkipEntityAIActions: true })) {
+            LogError(`[QueryExtraction] Could not record the description-pass failure on query "${request.QueryName}": ${query.LatestResult?.CompleteMessage}`);
+        }
+    }
+    catch (e) {
+        LogError(`[QueryExtraction] Could not record the description-pass failure on query "${request.QueryName}": ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+//# sourceMappingURL=descriptionPass.js.map

package/dist/custom/query-extraction/descriptionPass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptionPass.js","sourceRoot":"","sources":["../../../src/custom/query-extraction/descriptionPass.ts"],"names":[],"mappings":"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"}

package/dist/custom/query-extraction/extractQuery.d.ts

@@ -0,0 +1,25 @@
+import type { DatabasePlatform } from "@memberjunction/core";
+import type { QueryExtractionInput, QueryExtractionResult } from "./extractionTypes.js";
+/**
+ * Establishes a query's facts from its SQL and the database server, without writing anything:
+ *
+ * - from MJ's parser: whether it is a template, its parameters (with composition pass-throughs),
+ *   its compositions, the entities it reads, its doc comments and the save-time rules;
+ * - from the server: its output columns (name, order, exact type, nullability, source), for the
+ *   base render and every branch render, mapped through MJ metadata.
+ *
+ * In `Save` mode a save-time rule error or a repeated output name refuses the save
+ * (`Refusal`); in `Refresh` mode they are recorded with status `Error`. An external-data-source
+ * query is not described (`Skipped`); a describe failure keeps the stored fields (`Error`). A
+ * query that reads a table named by a template parameter is not described either: its output
+ * depends on the arguments, so its stored (declared) fields are kept and a note says why.
+ */
+export declare function ComputeQueryExtraction(input: QueryExtractionInput): Promise<QueryExtractionResult>;
+/** Why the fields of a query that reads a parameter-named table are not taken from a describe. */
+export declare const PARAMETER_NAMED_SOURCE_NOTE: string;
+/**
+ * The hash of the SQL the child rows are extracted from: SHA-256 (hex) of the dialect key and
+ * the platform SQL, so the same text on another platform hashes differently.
+ */
+export declare function ExtractionSQLHash(sql: string, platform: DatabasePlatform): string;
+//# sourceMappingURL=extractQuery.d.ts.map

package/dist/custom/query-extraction/extractQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractQuery.d.ts","sourceRoot":"","sources":["../../../src/custom/query-extraction/extractQuery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAO7D,OAAO,KAAK,EACR,oBAAoB,EACpB,qBAAqB,EAGxB,MAAM,mBAAmB,CAAC;AAS3B;;;;;;;;;;;;;GAaG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAsBxG;AAED,kGAAkG;AAClG,eAAO,MAAM,2BAA2B,QAC4E,CAAC;AAErH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAEjF"}

package/dist/custom/query-extraction/extractQuery.js

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { AnalyzeQueryTemplate, DescribeDiagnostic } from "./templateFacts.js";
+import { DescribeQueryOutput, FindUnsafeRender } from "./describeFacts.js";
+import { BindColumnSource, EntityObjectIndex } from "./sourceBinding.js";
+/**
+ * Establishes a query's facts from its SQL and the database server, without writing anything:
+ *
+ * - from MJ's parser: whether it is a template, its parameters (with composition pass-throughs),
+ *   its compositions, the entities it reads, its doc comments and the save-time rules;
+ * - from the server: its output columns (name, order, exact type, nullability, source), for the
+ *   base render and every branch render, mapped through MJ metadata.
+ *
+ * In `Save` mode a save-time rule error or a repeated output name refuses the save
+ * (`Refusal`); in `Refresh` mode they are recorded with status `Error`. An external-data-source
+ * query is not described (`Skipped`); a describe failure keeps the stored fields (`Error`). A
+ * query that reads a table named by a template parameter is not described either: its output
+ * depends on the arguments, so its stored (declared) fields are kept and a note says why.
+ */
+export async function ComputeQueryExtraction(input) {
+    const analysis = AnalyzeQueryTemplate(input);
+    const findings = { Errors: [], Warnings: [], Notes: [] };
+    const refusal = saveRefusal(input, analysis.Errors.map(d => DescribeDiagnostic(d, input.SQL)), analysis.DuplicateOutputNames);
+    if (refusal)
+        return resultOf(input, analysis, null, findings, refusal);
+    recordAnalysis(input, analysis, findings);
+    const unsafe = input.IsExternal ? null : FindUnsafeRender(input, analysis.Template, analysis.Parameters);
+    if (unsafe !== null)
+        return unsafeResult(input, analysis, findings, unsafe);
+    if (input.IsExternal) {
+        return { ...resultOf(input, analysis, null, findings, null), Entities: null, Status: 'Skipped',
+            Messages: ['The query reads an external data source, which the database server cannot describe; its fields and entities were left as they are.', ...messagesOf(findings)] };
+    }
+    if (analysis.ReadsParameterNamedSource) {
+        findings.Notes.push(PARAMETER_NAMED_SOURCE_NOTE);
+        return resultOf(input, analysis, null, findings, null);
+    }
+    const output = await DescribeQueryOutput(input, analysis.Template, analysis.Parameters);
+    const outputRefusal = saveRefusal(input, [], output.DuplicateNames);
+    if (outputRefusal)
+        return resultOf(input, analysis, null, findings, outputRefusal);
+    recordOutput(output, analysis, findings);
+    const fields = output.Failure === null ? fieldFacts(output.Columns, analysis, input, findings) : null;
+    return resultOf(input, analysis, fields, findings, null);
+}
+/** Why the fields of a query that reads a parameter-named table are not taken from a describe. */
+export const PARAMETER_NAMED_SOURCE_NOTE = 'The query reads a table or view named by a template parameter, so its output columns depend on the arguments ' +
+    'and no sample render describes them; its fields were left as they are (declare them in the query\'s metadata).';
+/**
+ * The hash of the SQL the child rows are extracted from: SHA-256 (hex) of the dialect key and
+ * the platform SQL, so the same text on another platform hashes differently.
+ */
+export function ExtractionSQLHash(sql, platform) {
+    return createHash('sha256').update(`${platform}\n${sql}`).digest('hex');
+}
+/**
+ * A query a render of which may not run: a new or edited one is refused; a refresh records the
+ * reason as an error and keeps the stored fields. Nothing is described, so the database server is
+ * never handed the statement.
+ */
+function unsafeResult(input, analysis, findings, reason) {
+    const refusal = saveRefusal(input, [reason], []);
+    if (refusal)
+        return resultOf(input, analysis, null, findings, refusal);
+    findings.Errors.push(`${reason} The stored fields were left as they are.`);
+    return resultOf(input, analysis, null, findings, null);
+}
+/** Why a new or edited query must be refused; `null` when it may be saved or this is a refresh. */
+function saveRefusal(input, errors, duplicates) {
+    const reasons = [...errors];
+    if (duplicates.length > 0)
+        reasons.push(duplicateMessage(duplicates));
+    if (input.Mode !== 'Save' || reasons.length === 0)
+        return null;
+    return `Query "${input.QueryName}" was not saved:\n${reasons.join('\n')}`;
+}
+function duplicateMessage(duplicates) {
+    return `The query returns more than one column named ${duplicates.map(d => `"${d}"`).join(', ')} (names compare without case). ` +
+        'Give each output column its own name, for example with an alias.';
+}
+/** Records what the template analysis found: refresh-mode rule errors, warnings, unread facts, orphaned authored parameters. */
+function recordAnalysis(input, analysis, findings) {
+    findings.Errors.push(...analysis.Errors.map(d => DescribeDiagnostic(d, input.SQL)));
+    if (analysis.DuplicateOutputNames.length > 0)
+        findings.Errors.push(duplicateMessage(analysis.DuplicateOutputNames));
+    findings.Warnings.push(...analysis.Warnings.map(d => DescribeDiagnostic(d, input.SQL)), ...analysis.Notes);
+    const used = new Set(analysis.Parameters.map(p => p.Name.toLowerCase()));
+    for (const known of input.KnownParameters) {
+        if (known.IsAuthored && !used.has(known.Name.toLowerCase())) {
+            findings.Warnings.push(`The authored parameter "${known.Name}" is not used by the SQL. It is kept, and a value passed for it is accepted and ignored.`);
+        }
+    }
+}
+/** Records the describe outcome: a failure, refresh-mode duplicates the parser did not already report, branch-only columns. */
+function recordOutput(output, analysis, findings) {
+    if (output.Failure !== null)
+        findings.Errors.push(`${output.Failure.trim().replace(/[.;]?$/, '.')} The stored fields were left as they are.`);
+    const reported = new Set(analysis.DuplicateOutputNames.map(n => n.toLowerCase()));
+    const duplicates = output.DuplicateNames.filter(n => !reported.has(n.toLowerCase()));
+    if (duplicates.length > 0)
+        findings.Errors.push(duplicateMessage(duplicates));
+    if (output.BranchOnlyColumns.length > 0) {
+        findings.Notes.push(`Columns only some branches of the template return: ${output.BranchOnlyColumns.join(', ')}.`);
+    }
+}
+/** The field facts of the described output, in order; unnamed columns are skipped and reported. */
+function fieldFacts(columns, analysis, input, findings) {
+    const index = new EntityObjectIndex(input.Entities);
+    const facts = [];
+    for (const column of columns) {
+        if (column.Name.trim().length === 0) {
+            findings.Warnings.push(`Output column ${column.Ordinal} has no name, so it has no field row. Give it an alias.`);
+            continue;
+        }
+        const source = BindColumnSource(column.Source, index);
+        facts.push({
+            Name: column.Name, Sequence: facts.length + 1, SQLBaseType: column.SQLBaseType, SQLFullType: column.SQLFullType,
+            IsNullable: column.IsNullable, IsComputed: column.IsComputed,
+            SourceEntityID: source.SourceEntityID, SourceEntityFieldID: source.SourceEntityFieldID,
+            SourceFieldName: source.SourceFieldName, SourceObjectName: source.SourceObjectName,
+            DocDescription: analysis.FieldDocs.get(column.Name.toLowerCase()) ?? null, SourceDescription: source.SourceDescription,
+        });
+    }
+    return facts;
+}
+function resultOf(input, analysis, fields, findings, refusal) {
+    return {
+        UsesTemplate: analysis.UsesTemplate,
+        Refusal: refusal,
+        Status: statusOf(findings),
+        Messages: messagesOf(findings),
+        Hash: ExtractionSQLHash(input.SQL, input.Platform),
+        Fields: fields,
+        Parameters: analysis.Parameters,
+        Entities: analysis.Entities,
+        Dependencies: analysis.Dependencies,
+    };
+}
+function statusOf(findings) {
+    if (findings.Errors.length > 0)
+        return 'Error';
+    return findings.Warnings.length > 0 ? 'Warning' : 'OK';
+}
+function messagesOf(findings) {
+    return [...findings.Errors, ...findings.Warnings, ...findings.Notes];
+}
+//# sourceMappingURL=extractQuery.js.map

package/dist/custom/query-extraction/extractQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractQuery.js","sourceRoot":"","sources":["../../../src/custom/query-extraction/extractQuery.ts"],"names":[],"mappings":"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"}

package/dist/custom/query-extraction/extractionTypes.d.ts

@@ -0,0 +1,133 @@
+import type { DatabasePlatform, EntityInfo, QueryDependencySpec, UserInfo } from "@memberjunction/core";
+import type { CompositionCandidate } from "./compositionTargets.js";
+import type { DescribeStatementResult } from "@memberjunction/generic-database-provider";
+/**
+ * What a query save does about extraction, set per save on the query entity
+ * (`MJQueryEntityServer.ExtractionOverride`).
+ *
+ * - `Auto`: extract when the query is new or its SQL changed.
+ * - `Skip`: do not extract on this save, even when the SQL changed. The save-time rules are not
+ *   applied; the stored child rows, the Extraction columns and `UsesTemplate` stay as they are.
+ * - `Force`: extract on this save even when the SQL did not change (a refresh).
+ */
+export type QueryExtractionOverride = 'Auto' | 'Skip' | 'Force';
+/** The outcome of an extraction run, as stored in `MJ: Queries.ExtractionStatus`. */
+export type QueryExtractionStatus = 'OK' | 'Warning' | 'Error' | 'Skipped';
+/**
+ * Which save-time rules apply: `Save` for a new or edited query (errors refuse the save),
+ * `Refresh` for re-extracting a query whose SQL did not change (errors are recorded, never refused).
+ */
+export type QueryExtractionMode = 'Save' | 'Refresh';
+/** A parameter type the `MJ: Query Parameters` table stores. */
+export type QueryParameterType = 'string' | 'number' | 'date' | 'boolean' | 'array';
+/**
+ * A parameter row extraction knows about before it runs: a row the save declares, or a row
+ * already stored. Its type, sample and server-set flag drive the renders that are described.
+ */
+export interface KnownQueryParameter {
+    readonly Name: string;
+    readonly Type: QueryParameterType;
+    readonly IsRequired: boolean;
+    readonly IsServerSet: boolean;
+    readonly SampleValue: string | null;
+    readonly DefaultValue: string | null;
+    readonly ValidationFilters: string | null;
+    /** Whether a person wrote the row (`DetectionMethod` `Manual`). */
+    readonly IsAuthored: boolean;
+}
+/** Everything one extraction run reads. Independent of the entity object, so it can be tested alone. */
+export interface QueryExtractionInput {
+    /** The query's ID; `null` for a query not saved yet. */
+    readonly QueryID: string | null;
+    readonly QueryName: string;
+    /** The query's full path (category path and name), for composition cycle detection. */
+    readonly QueryPath: string;
+    /** The SQL to extract from: the query's SQL for the platform described on. */
+    readonly SQL: string;
+    /** The platform the SQL is rendered for and described on. */
+    readonly Platform: DatabasePlatform;
+    readonly Mode: QueryExtractionMode;
+    /** Whether the query reads an external data source, which the database server cannot describe. */
+    readonly IsExternal: boolean;
+    readonly KnownParameters: readonly KnownQueryParameter[];
+    /** Tested sample values a caller supplied (`ParameterHints`), by parameter name. */
+    readonly ParameterHints?: ReadonlyMap<string, string>;
+    /** The user the renders are made for (composed queries must be runnable by them). */
+    readonly ContextUser: UserInfo;
+    /** The entity catalog sources and table references are mapped through. */
+    readonly Entities: readonly EntityInfo[];
+    /** The saved queries compositions resolve against. */
+    readonly Queries: readonly CompositionCandidate[];
+    /**
+     * Render specs for composed queries the shared query cache does not hold yet (saved earlier in
+     * the same transaction), searched before the cache when the describe renders compose them.
+     */
+    readonly CompositionDependencies?: readonly QueryDependencySpec[];
+    /** Describes a rendered statement on the database server; `null` when the provider cannot. */
+    readonly Describe: ((sql: string) => Promise<DescribeStatementResult>) | null;
+}
+/** The facts of one output column: what the server reports, mapped through MJ metadata. */
+export interface QueryFieldFact {
+    readonly Name: string;
+    readonly Sequence: number;
+    readonly SQLBaseType: string;
+    readonly SQLFullType: string;
+    readonly IsNullable: boolean | null;
+    readonly IsComputed: boolean;
+    readonly SourceEntityID: string | null;
+    readonly SourceEntityFieldID: string | null;
+    readonly SourceFieldName: string | null;
+    readonly SourceObjectName: string | null;
+    /** A doc-comment description: an authored annotation. */
+    readonly DocDescription: string | null;
+    /** The source entity field's description, used for a new row with no other description. */
+    readonly SourceDescription: string | null;
+}
+/** The facts of one parameter the template reads. */
+export interface QueryParameterFact {
+    readonly Name: string;
+    /** The type the template's filters imply; `null` when they imply none. */
+    readonly Type: QueryParameterType | null;
+    readonly IsRequired: boolean;
+    readonly DefaultValue: string | null;
+    /** A sample for a new row: the caller's hint, or the value a composed query's parameter has. */
+    readonly SampleValue: string | null;
+    /** A doc-comment description: an authored annotation. */
+    readonly DocDescription: string | null;
+    /** A description inherited from the composed query's parameter this one is passed to. */
+    readonly InheritedDescription: string | null;
+}
+/** An entity the query reads, through its base view, base table or an alternate base view. */
+export interface QueryEntityFact {
+    readonly EntityID: string;
+    readonly AlternateBaseViewID: string | null;
+}
+/** A query this query composes. */
+export interface QueryDependencyFact {
+    readonly DependsOnQueryID: string;
+    /** The full path as the composition writes it. */
+    readonly ReferencePath: string;
+    readonly Alias: string | null;
+    /** The arguments, as JSON (`{"Region":"@Region","Year":"2024"}`), or `null` when there are none. */
+    readonly ParameterMapping: string | null;
+}
+/**
+ * The result of one extraction run. A `null` collection means its facts could not be established
+ * (a describe failure, an external source, SQL that could not be read): its stored rows are kept.
+ */
+export interface QueryExtractionResult {
+    /** Whether the SQL holds any template tag outside SQL comments: a lexer fact. */
+    readonly UsesTemplate: boolean;
+    /** Set when the save must be refused (save-time rule errors, duplicate output names); the reason. */
+    readonly Refusal: string | null;
+    readonly Status: QueryExtractionStatus;
+    /** Diagnostics for `ExtractionMessage`, one per line. */
+    readonly Messages: readonly string[];
+    /** SHA-256 of the platform SQL and the dialect key. */
+    readonly Hash: string;
+    readonly Fields: readonly QueryFieldFact[] | null;
+    readonly Parameters: readonly QueryParameterFact[];
+    readonly Entities: readonly QueryEntityFact[] | null;
+    readonly Dependencies: readonly QueryDependencyFact[] | null;
+}
+//# sourceMappingURL=extractionTypes.d.ts.map

package/dist/custom/query-extraction/extractionTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractionTypes.d.ts","sourceRoot":"","sources":["../../../src/custom/query-extraction/extractionTypes.ts"],"names":[],"mappings":"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"}

package/dist/custom/query-extraction/extractionTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=extractionTypes.js.map

package/dist/custom/query-extraction/extractionTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractionTypes.js","sourceRoot":"","sources":["../../../src/custom/query-extraction/extractionTypes.ts"],"names":[],"mappings":""}

package/dist/custom/query-extraction/index.d.ts

@@ -1,3 +1,17 @@
+export { ComputeQueryExtraction, ExtractionSQLHash } from "./extractQuery.js";
+export { WriteExtractedChildRows, ApplyFieldFacts } from "./childRowWriter.js";
+export type { ChildRowWriteContext, ChildRowWriteSummary, ChildRowChange, QueryChildCollection } from "./childRowWriter.js";
+export { RunDescriptionPass } from "./descriptionPass.js";
+export type { DescriptionPassRequest } from "./descriptionPass.js";
+export { AnalyzeQueryTemplate, SQLUsesTemplate, DescribeDiagnostic } from "./templateFacts.js";
+export { ReadCompositionTargetsAsync, MergeCompositionCandidates } from "./compositionTargets.js";
+export type { CompositionCandidate, CompositionCandidateParameter, CompositionTargetRead } from "./compositionTargets.js";
+export type { TemplateAnalysis } from "./templateFacts.js";
+export { DescribeQueryOutput, SampleValueFor } from "./describeFacts.js";
+export type { DescribedOutput } from "./describeFacts.js";
+export { EntityObjectIndex, BindColumnSource, BindTableReferences } from "./sourceBinding.js";
+export type { BoundColumnSource } from "./sourceBinding.js";
+export type { QueryExtractionOverride, QueryExtractionStatus, QueryExtractionMode, QueryParameterType, KnownQueryParameter, QueryExtractionInput, QueryFieldFact, QueryParameterFact, QueryEntityFact, QueryDependencyFact, QueryExtractionResult, } from "./extractionTypes.js";
 export { RunExtractionPipeline, CleanupQueryData } from "./pipeline.js";
 export type { PipelineResult } from "./pipeline.js";
 export type { ExtractedParameter, ExtractedField, ParameterExtractionResult, PassthroughParamContext, ResolvedCompositionReference, EntityMetadataEntry, ParseResult, ResolveResult, QuerySyncContext, } from "./types.js";
@@ -5,5 +19,7 @@ export { ParseQuerySQL, parseQuerySQL } from "./parse.js";
 export { ResolveCompositionReferences, ResolveQueryByNameAndCategory, BuildParameterMappings, ExtractAliasFromSQL, BuildPassthroughParams, MergePassthroughParams, MapQueryParamTypeToParserType, BuildFieldsForSelectStar, EnrichFieldTypesFromCompositions, EnrichFieldTypesFromEntityMetadata, ExpandWildcardFields, ExtractEntityMetadataFromSQL, DetectDependencyCycles, FindEntityByName, } from "./resolve.js";
 export { RunLLMEnrichment, MergeParametersWithLLM, GenerateParameterDescription, BuildPassthroughDescription, GenerateSampleValue, } from "./enrich.js";
 export { SyncParameters, SyncFields, SyncEntities, SyncDependencies, RemoveAllRecords } from "./sync.js";
+export { CollectDeclaredQueryChildren, HasDeclaredQueryChildren, FindReplacedRows, QueueReplacedRowDeletion, QueryChildNameKey, QueryEntityKey, NO_DECLARED_QUERY_CHILDREN, } from "./declared.js";
+export type { DeclaredQueryChildren, DeclaredQueryCollections } from "./declared.js";
 export { ConvertTSQLToPostgreSQL } from "./dialect.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/custom/query-extraction/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/custom/query-extraction/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,YAAY,EACR,kBAAkB,EAClB,cAAc,EACd,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,gBAAgB,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGvD,OAAO,EACH,4BAA4B,EAC5B,6BAA6B,EAC7B,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,wBAAwB,EACxB,gCAAgC,EAChC,kCAAkC,EAClC,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,gBAAgB,GACnB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACH,gBAAgB,EAChB,sBAAsB,EACtB,4BAA4B,EAC5B,2BAA2B,EAC3B,mBAAmB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGtG,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/custom/query-extraction/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC5E,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACzH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAC/F,YAAY,EAAE,oBAAoB,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACvH,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC3F,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EACR,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,GACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACrE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,YAAY,EACR,kBAAkB,EAClB,cAAc,EACd,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,gBAAgB,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGvD,OAAO,EACH,4BAA4B,EAC5B,6BAA6B,EAC7B,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,wBAAwB,EACxB,gCAAgC,EAChC,kCAAkC,EAClC,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,gBAAgB,GACnB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACH,gBAAgB,EAChB,sBAAsB,EACtB,4BAA4B,EAC5B,2BAA2B,EAC3B,mBAAmB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGtG,OAAO,EACH,4BAA4B,EAC5B,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,0BAA0B,GAC7B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAGlF,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC"}

package/dist/custom/query-extraction/index.js

@@ -1,6 +1,14 @@
 // Query Extraction Pipeline — barrel exports
 // Re-exports the public API for the query extraction subsystem.
-// Pipeline orchestrator
+// Extraction (describe-based): facts, child-row writes, the post-commit description pass
+export { ComputeQueryExtraction, ExtractionSQLHash } from "./extractQuery.js";
+export { WriteExtractedChildRows, ApplyFieldFacts } from "./childRowWriter.js";
+export { RunDescriptionPass } from "./descriptionPass.js";
+export { AnalyzeQueryTemplate, SQLUsesTemplate, DescribeDiagnostic } from "./templateFacts.js";
+export { ReadCompositionTargetsAsync, MergeCompositionCandidates } from "./compositionTargets.js";
+export { DescribeQueryOutput, SampleValueFor } from "./describeFacts.js";
+export { EntityObjectIndex, BindColumnSource, BindTableReferences } from "./sourceBinding.js";
+// Legacy pipeline orchestrator (kept as a façade; saves use ComputeQueryExtraction)
 export { RunExtractionPipeline, CleanupQueryData } from "./pipeline.js";
 // Parse stage
 export { ParseQuerySQL, parseQuerySQL } from "./parse.js";
@@ -10,6 +18,8 @@ export { ResolveCompositionReferences, ResolveQueryByNameAndCategory, BuildParam
 export { RunLLMEnrichment, MergeParametersWithLLM, GenerateParameterDescription, BuildPassthroughDescription, GenerateSampleValue, } from "./enrich.js";
 // Sync engine
 export { SyncParameters, SyncFields, SyncEntities, SyncDependencies, RemoveAllRecords } from "./sync.js";
+// Declared child rows (graph saves)
+export { CollectDeclaredQueryChildren, HasDeclaredQueryChildren, FindReplacedRows, QueueReplacedRowDeletion, QueryChildNameKey, QueryEntityKey, NO_DECLARED_QUERY_CHILDREN, } from "./declared.js";
 // Dialect conversion
 export { ConvertTSQLToPostgreSQL } from "./dialect.js";
 //# sourceMappingURL=index.js.map

package/dist/custom/query-extraction/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/custom/query-extraction/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,gEAAgE;AAEhE,wBAAwB;AACxB,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAgBrE,cAAc;AACd,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEvD,sDAAsD;AACtD,OAAO,EACH,4BAA4B,EAC5B,6BAA6B,EAC7B,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,wBAAwB,EACxB,gCAAgC,EAChC,kCAAkC,EAClC,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,gBAAgB,GACnB,MAAM,WAAW,CAAC;AAEnB,sCAAsC;AACtC,OAAO,EACH,gBAAgB,EAChB,sBAAsB,EACtB,4BAA4B,EAC5B,2BAA2B,EAC3B,mBAAmB,GACtB,MAAM,UAAU,CAAC;AAElB,cAAc;AACd,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEtG,qBAAqB;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/custom/query-extraction/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,gEAAgE;AAEhE,yFAAyF;AACzF,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAE5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAG/F,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAgB3F,oFAAoF;AACpF,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAgBrE,cAAc;AACd,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEvD,sDAAsD;AACtD,OAAO,EACH,4BAA4B,EAC5B,6BAA6B,EAC7B,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,wBAAwB,EACxB,gCAAgC,EAChC,kCAAkC,EAClC,oBAAoB,EACpB,4BAA4B,EAC5B,sBAAsB,EACtB,gBAAgB,GACnB,MAAM,WAAW,CAAC;AAEnB,sCAAsC;AACtC,OAAO,EACH,gBAAgB,EAChB,sBAAsB,EACtB,4BAA4B,EAC5B,2BAA2B,EAC3B,mBAAmB,GACtB,MAAM,UAAU,CAAC;AAElB,cAAc;AACd,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEtG,oCAAoC;AACpC,OAAO,EACH,4BAA4B,EAC5B,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,0BAA0B,GAC7B,MAAM,YAAY,CAAC;AAGpB,qBAAqB;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC"}

package/dist/custom/query-extraction/pipeline.d.ts

@@ -1,7 +1,7 @@
 import type { QuerySyncContext } from "./types.js";
 /**
- * Result of running the full extraction pipeline.
- * The caller uses `usesTemplate` to update the entity's UsesTemplate flag.
+ * Result of running the full extraction pipeline. `UsesTemplate` is a lexical fact: whether the
+ * SQL holds any template tag outside SQL comments.
  */
 export interface PipelineResult {
     UsesTemplate: boolean;
@@ -15,6 +15,10 @@ export interface PipelineResult {
  *   5. SYNC — parallel database writes
  *
  * Throws on invalid composition references (non-existent, non-Reusable, circular).
+ *
+ * @deprecated Saves extract with `ComputeQueryExtraction` (the database server describes the
+ * output) and `WriteExtractedChildRows` (facts corrected, authored annotations kept). This
+ * LLM-assisted pipeline is kept for callers of the package API.
  */
 export declare function RunExtractionPipeline(ctx: QuerySyncContext): Promise<PipelineResult>;
 /**

package/dist/custom/query-extraction/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../src/custom/query-extraction/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAiC,MAAM,SAAS,CAAC;AAkB/E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC3B,YAAY,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqB1F;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ3E"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../src/custom/query-extraction/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAiC,MAAM,SAAS,CAAC;AAoB/E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC3B,YAAY,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqB1F;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ3E"}