graphile-llm 1.21.6 → 1.21.7

package/esm/embed-inputs.js

@@ -0,0 +1,277 @@
+/**
+ * Plan-time text-to-vector embedding.
+ *
+ * Under Grafast a field's `resolve()` runs after its plan has executed, so the
+ * SQL has already been built by the time a resolver wrapper could embed text.
+ * Instead, input fields that carry text to embed are tagged with an
+ * `EmbedRule` where they are declared, and `planTimeEmbedding` (run from a
+ * `finalize` hook) wraps the plan of every object field whose arguments can
+ * reach a tagged input field. The wrapper shadows `fieldArgs.getRaw` so every
+ * consumer of those arguments (connection-filter's `where` applyPlan, the
+ * create/update `args.apply`) reads a step that embeds the text first.
+ */
+import { access, ConstantStep, context, lambda, object } from 'grafast';
+import { llmConfigStore } from './embedder';
+export const EMBED_EXT = 'graphileLlmEmbed';
+export function embedField(rule, spec) {
+    return { ...spec, extensions: { ...spec.extensions, [EMBED_EXT]: rule } };
+}
+/**
+ * `build.llmEmbedder` resolves to `{ embedding }` from the providers and to
+ * `number[] | null` once the metering plugin has wrapped it.
+ */
+export function toVectorEmbedder(raw) {
+    if (typeof raw !== 'function')
+        return null;
+    return async (text) => {
+        const result = await raw(text);
+        const vector = Array.isArray(result) ? result : result?.embedding;
+        return Array.isArray(vector) && vector.length > 0 ? vector : null;
+    };
+}
+function isNonEmptyVector(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+export async function resolveConfigOverrides(graphqlContext) {
+    const ctx = graphqlContext?.constructive;
+    if (!ctx?.useLlm)
+        return null;
+    try {
+        const llm = await ctx.useLlm();
+        if (!llm?.embeddingModel)
+            return null;
+        return {
+            embeddingModel: llm.embeddingModel,
+            embeddingBaseUrl: llm.embeddingBaseUrl,
+            chatModel: llm.chatModel ?? undefined,
+            chatBaseUrl: llm.chatBaseUrl ?? undefined
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Binds the embedder to one request's per-database model overrides, resolved on first use. */
+function forRequest(embedder, graphqlContext) {
+    if (!embedder)
+        return null;
+    let overrides;
+    return async (text) => {
+        overrides ??= resolveConfigOverrides(graphqlContext);
+        const resolved = await overrides;
+        const startTime = Date.now();
+        const vector = await llmConfigStore.run(resolved, () => embedder(text));
+        if (vector) {
+            console.log(`[graphile-llm] embed: dims=${vector.length}, latency=${Date.now() - startTime}ms`);
+        }
+        return vector;
+    };
+}
+export function createEmbedIndex(graphql) {
+    const { getNamedType, isInputObjectType, isListType, isNonNullType } = graphql;
+    const reachesMemo = new WeakMap();
+    const inputObjectFields = (type) => Object.values(type.getFields());
+    const namedInputObject = (field) => {
+        const named = getNamedType(field.type);
+        return isInputObjectType(named) ? named : null;
+    };
+    // Filter types are cyclic (AND/OR/NOT, forward and backward relations), so
+    // reachability is a fixed point over everything reachable from `type`; a
+    // depth-first walk that memoizes a provisional answer mid-cycle gets it wrong.
+    function reaches(type) {
+        const start = getNamedType(type);
+        if (!isInputObjectType(start))
+            return false;
+        const known = reachesMemo.get(start);
+        if (known !== undefined)
+            return known;
+        const pending = [];
+        const stack = [start];
+        const seen = new Set();
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (seen.has(node) || reachesMemo.has(node))
+                continue;
+            seen.add(node);
+            pending.push(node);
+            for (const field of inputObjectFields(node)) {
+                const child = namedInputObject(field);
+                if (child)
+                    stack.push(child);
+            }
+        }
+        const hit = new Set(pending.filter((node) => inputObjectFields(node).some((f) => f.extensions?.[EMBED_EXT])));
+        const isHit = (node) => hit.has(node) || reachesMemo.get(node) === true;
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const node of pending) {
+                if (hit.has(node))
+                    continue;
+                if (inputObjectFields(node).some((f) => {
+                    const child = namedInputObject(f);
+                    return child !== null && isHit(child);
+                })) {
+                    hit.add(node);
+                    changed = true;
+                }
+            }
+        }
+        for (const node of pending)
+            reachesMemo.set(node, hit.has(node));
+        return reachesMemo.get(start);
+    }
+    async function applyRule(rule, fieldName, typeName, value, next, embed) {
+        const text = value[fieldName];
+        switch (rule.kind) {
+            case 'nearby': {
+                delete next[fieldName];
+                if (isNonEmptyVector(value[rule.into]))
+                    return;
+                if (typeof text !== 'string') {
+                    throw new Error(`${typeName}: provide either \`${rule.into}\` or \`${fieldName}\`.`);
+                }
+                if (!embed)
+                    return;
+                const vector = await embed(text);
+                if (vector) {
+                    next[rule.into] = vector;
+                }
+                else if (rule.onQuotaExceeded === 'throw') {
+                    throw new Error(`${typeName}: embedding failed (quota exceeded or provider unavailable). ` +
+                        'Upgrade your plan or adjust onQuotaExceeded to \'degrade\' for graceful fallback.');
+                }
+                return;
+            }
+            case 'unified': {
+                if (typeof text !== 'string' || text.trim().length === 0 || !embed)
+                    return;
+                const vector = await embed(text);
+                if (vector) {
+                    next[fieldName] = { __text: text, __vector: vector };
+                }
+                else if (rule.onQuotaExceeded === 'throw') {
+                    throw new Error(`${fieldName}: embedding failed (quota exceeded or provider unavailable). ` +
+                        'onQuotaExceeded is set to \'throw\'. ' +
+                        'Upgrade your plan or adjust onQuotaExceeded to \'degrade\' for text-only fallback.');
+                }
+                return;
+            }
+            case 'companion': {
+                delete next[fieldName];
+                if (isNonEmptyVector(value[rule.into]))
+                    return;
+                if (typeof text !== 'string') {
+                    if (rule.required) {
+                        throw new Error(`${typeName}: provide either \`${rule.into}\` or \`${fieldName}\`.`);
+                    }
+                    return;
+                }
+                if (!embed) {
+                    throw new Error(`EMBED_NOT_CONFIGURED: Cannot embed ${fieldName} — no embedding provider configured. ` +
+                        'Set defaultEmbedder in GraphileLlmPreset options or EMBEDDER_PROVIDER env var.');
+                }
+                const vector = await embed(text);
+                if (!vector) {
+                    throw new Error(`EMBED_QUOTA_EXCEEDED: Cannot embed ${fieldName} — embedding quota exceeded. ` +
+                        'Upgrade your plan or wait for the next billing period.');
+                }
+                next[rule.into] = vector;
+                return;
+            }
+        }
+    }
+    /** Returns `value` itself when its type cannot reach a tagged field. */
+    async function embedValue(type, value, embed) {
+        if (value == null)
+            return value;
+        const inner = isNonNullType(type) ? type.ofType : type;
+        if (isListType(inner)) {
+            if (!Array.isArray(value) || !reaches(inner.ofType))
+                return value;
+            return Promise.all(value.map((item) => embedValue(inner.ofType, item, embed)));
+        }
+        if (!isInputObjectType(inner) || !reaches(inner))
+            return value;
+        const next = { ...value };
+        const jobs = [];
+        for (const [name, field] of Object.entries(inner.getFields())) {
+            const rule = field.extensions?.[EMBED_EXT];
+            if (rule) {
+                jobs.push(applyRule(rule, name, inner.name, value, next, embed));
+            }
+            else if (value[name] != null && reaches(field.type)) {
+                jobs.push(embedValue(field.type, value[name], embed).then((embedded) => { next[name] = embedded; }));
+            }
+        }
+        await Promise.all(jobs);
+        return next;
+    }
+    return { reaches, embedValue };
+}
+function withEmbeddedArgs(originalPlan, argNames, embeddable, index, embedder) {
+    return function planWithEmbeddedArgs(parent, fieldArgs, info) {
+        const originalGetRaw = fieldArgs.getRaw;
+        const roots = new Map();
+        const rootStep = (argName) => {
+            let $root = roots.get(argName);
+            if ($root)
+                return $root;
+            const $raw = originalGetRaw.call(fieldArgs, argName);
+            const absent = $raw instanceof ConstantStep && $raw.data === undefined;
+            if (absent || !embeddable.has(argName)) {
+                $root = $raw;
+            }
+            else {
+                const type = fieldArgs.typeAt(argName);
+                $root = $raw.withLayerPlan(() => lambda({ raw: $raw, ctx: context() }, ({ raw, ctx }) => index.embedValue(type, raw, forRequest(embedder, ctx))));
+            }
+            roots.set(argName, $root);
+            return $root;
+        };
+        // grafast reads `fieldArgs.getRaw` through the object (apply, processAfter,
+        // `$arg` getters, getBaked), so shadowing it here reaches every consumer.
+        fieldArgs.getRaw = function getRawEmbedded(path) {
+            if (path === undefined) {
+                const steps = Object.fromEntries(argNames.map((n) => [n, rootStep(n)]));
+                return steps[argNames[0]].withLayerPlan(() => object(steps));
+            }
+            const [argName, ...rest] = typeof path === 'string' ? [path] : path;
+            if (!embeddable.has(argName))
+                return originalGetRaw.call(fieldArgs, path);
+            const $root = rootStep(argName);
+            return (rest.length === 0 ? $root : $root.withLayerPlan(() => access($root, rest)));
+        };
+        return originalPlan(parent, fieldArgs, info);
+    };
+}
+const processedSchemas = new WeakSet();
+/**
+ * Wraps the plan of every object field whose arguments reach a tagged input
+ * field. Runs in `finalize` because args are attached after the
+ * `GraphQLObjectType_fields_field` hook. Idempotent per schema, so every plugin
+ * that tags fields can call it without depending on the others being loaded.
+ */
+export function planTimeEmbedding(schema, build) {
+    if (processedSchemas.has(schema))
+        return schema;
+    processedSchemas.add(schema);
+    const { graphql } = build;
+    const index = createEmbedIndex(graphql);
+    const embedder = toVectorEmbedder(build.llmEmbedder);
+    for (const type of Object.values(schema.getTypeMap())) {
+        if (!graphql.isObjectType(type) || type.name.startsWith('__'))
+            continue;
+        for (const field of Object.values(type.getFields())) {
+            const grafastExt = field.extensions?.grafast;
+            if (typeof grafastExt?.plan !== 'function')
+                continue;
+            const embeddable = new Set(field.args.filter((a) => index.reaches(a.type)).map((a) => a.name));
+            if (embeddable.size === 0)
+                continue;
+            const argNames = field.args.map((a) => a.name);
+            grafastExt.plan = withEmbeddedArgs(grafastExt.plan, argNames, embeddable, index, embedder);
+        }
+    }
+    return schema;
+}

package/esm/embedder.d.ts

@@ -5,7 +5,7 @@
  * embeddings. Currently supports Ollama via @agentic-kit/ollama.
  *
  * Per-request model/baseUrl overrides are read from AsyncLocalStorage
- * (`llmConfigStore`). The text-search-plugin sets these overrides from
+ * (`llmConfigStore`). embed-inputs.ts sets these overrides from
  * the database's `llm_module` config via `ctx.useLlm()`. This means
  * the same embedder function — and its metering wrapper — handle every
  * request, regardless of which tenant's model config applies.
@@ -25,7 +25,7 @@ export interface LlmConfigOverrides {
 /**
  * AsyncLocalStorage for per-request LLM config overrides.
  *
- * Set by the text-search-plugin resolver wrapper (from ctx.useLlm()),
+ * Set by the plan-time embedding step in embed-inputs.ts (from ctx.useLlm()),
  * read by the embedder at call time. The metering wrapper sits between
  * them and is completely unaware — it just wraps the same function.
  */

package/esm/embedder.js

@@ -5,7 +5,7 @@
  * embeddings. Currently supports Ollama via @agentic-kit/ollama.
  *
  * Per-request model/baseUrl overrides are read from AsyncLocalStorage
- * (`llmConfigStore`). The text-search-plugin sets these overrides from
+ * (`llmConfigStore`). embed-inputs.ts sets these overrides from
  * the database's `llm_module` config via `ctx.useLlm()`. This means
  * the same embedder function — and its metering wrapper — handle every
  * request, regardless of which tenant's model config applies.
@@ -16,7 +16,7 @@ import { getLlmEnvOptions } from './env';
 /**
  * AsyncLocalStorage for per-request LLM config overrides.
  *
- * Set by the text-search-plugin resolver wrapper (from ctx.useLlm()),
+ * Set by the plan-time embedding step in embed-inputs.ts (from ctx.useLlm()),
  * read by the embedder at call time. The metering wrapper sits between
  * them and is completely unaware — it just wraps the same function.
  */

package/esm/index.d.ts

@@ -36,6 +36,8 @@ export { createLlmModulePlugin } from './plugins/llm-module-plugin';
 export { createLlmRagPlugin } from './plugins/rag-plugin';
 export { createLlmTextMutationPlugin } from './plugins/text-mutation-plugin';
 export { createLlmTextSearchPlugin, embedTextInWhere } from './plugins/text-search-plugin';
+export type { EmbedRule } from './embed-inputs';
+export { embedField, planTimeEmbedding } from './embed-inputs';
 export { createLlmMeteringPlugin } from './plugins/metering-plugin';
 export type { AgentDiscovery, AgentTableInfo } from './plugins/agent-discovery-plugin';
 export { clearAgentDiscoveryCache, getAgentDiscovery } from './plugins/agent-discovery-plugin';

package/esm/index.js

@@ -37,6 +37,7 @@ export { createLlmModulePlugin } from './plugins/llm-module-plugin';
 export { createLlmRagPlugin } from './plugins/rag-plugin';
 export { createLlmTextMutationPlugin } from './plugins/text-mutation-plugin';
 export { createLlmTextSearchPlugin, embedTextInWhere } from './plugins/text-search-plugin';
+export { embedField, planTimeEmbedding } from './embed-inputs';
 // Metering plugin (opt-in billing integration)
 export { createLlmMeteringPlugin } from './plugins/metering-plugin';
 export { clearAgentDiscoveryCache, getAgentDiscovery } from './plugins/agent-discovery-plugin';

package/esm/plugins/llm-module-plugin.d.ts

@@ -17,7 +17,7 @@
  *
  * Per-database model/baseUrl overrides (from `llm_module` via `ctx.useLlm()`)
  * are applied at request time via `llmConfigStore` (AsyncLocalStorage) in
- * the text-search-plugin resolver wrapper. The same embedder function — and
+ * the plan-time embedding step (embed-inputs.ts). The same embedder function — and
  * its metering wrapper — handles every request; only the model name and
  * base URL parameters change per-tenant.
  *

package/esm/plugins/llm-module-plugin.js

@@ -17,7 +17,7 @@
  *
  * Per-database model/baseUrl overrides (from `llm_module` via `ctx.useLlm()`)
  * are applied at request time via `llmConfigStore` (AsyncLocalStorage) in
- * the text-search-plugin resolver wrapper. The same embedder function — and
+ * the plan-time embedding step (embed-inputs.ts). The same embedder function — and
  * its metering wrapper — handles every request; only the model name and
  * base URL parameters change per-tenant.
  *

package/esm/plugins/text-mutation-plugin.d.ts

@@ -17,9 +17,10 @@
  * filter/query-side text-to-vector). Together they let clients work entirely
  * with text/prompts instead of raw float vectors.
  *
- * Runtime embedding uses the v4-style resolver wrapping approach (same as
- * graphile-upload-plugin and graphile-bucket-provisioner-plugin). grafserv v5
- * supports this through its backwards-compatibility layer.
+ * The text is embedded while the mutation is planned (see embed-inputs.ts),
+ * before the INSERT/UPDATE is built. On a create input for a NOT NULL vector
+ * column the vector field becomes optional, and one of `{col}` or `{col}Text`
+ * is required at execution time. If both are given, the vector is used.
  *
  * The companion fields are only added when the LLM plugin is loaded.
  * If no embedder is configured, the fields are still registered for schema
@@ -39,10 +40,7 @@ declare global {
  * Creates the LlmTextMutationPlugin.
  *
  * Hooks into GraphQLInputObjectType_fields for create/update input types
- * and adds `{columnName}Text: String` for each vector column.
- *
- * Also wraps mutation resolvers via GraphQLObjectType_fields_field to
- * intercept `*Text` companion field values, embed them, and inject the
- * resulting vectors before the mutation executes.
+ * and adds `{columnName}Text: String` for each vector column, tagged for
+ * plan-time embedding.
  */
 export declare function createLlmTextMutationPlugin(): GraphileConfig.Plugin;

package/esm/plugins/text-mutation-plugin.js

@@ -17,9 +17,10 @@
  * filter/query-side text-to-vector). Together they let clients work entirely
  * with text/prompts instead of raw float vectors.
  *
- * Runtime embedding uses the v4-style resolver wrapping approach (same as
- * graphile-upload-plugin and graphile-bucket-provisioner-plugin). grafserv v5
- * supports this through its backwards-compatibility layer.
+ * The text is embedded while the mutation is planned (see embed-inputs.ts),
+ * before the INSERT/UPDATE is built. On a create input for a NOT NULL vector
+ * column the vector field becomes optional, and one of `{col}` or `{col}Text`
+ * is required at execution time. If both are given, the vector is used.
  *
  * The companion fields are only added when the LLM plugin is loaded.
  * If no embedder is configured, the fields are still registered for schema
@@ -27,51 +28,24 @@
  */
 import 'graphile-build';
 import 'graphile-build-pg';
+import { embedField, planTimeEmbedding } from '../embed-inputs';
 /**
  * Check if a codec is the pgvector `vector` type.
  */
 function isVectorCodec(codec) {
     return codec?.name === 'vector';
 }
-/**
- * Collect the text→vector field mapping for a codec's vector columns.
- * Returns a map of textFieldName → vectorFieldName.
- */
-function getTextToVectorMapping(pgCodec, build) {
-    const mapping = {};
-    if (!pgCodec?.attributes)
-        return mapping;
-    const attributeFieldNames = new Set(Object.keys(pgCodec.attributes).map((attributeName) => build.inflection.attribute({ codec: pgCodec, attributeName })));
-    for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
-        if (isVectorCodec(attribute.codec)) {
-            const fieldName = build.inflection.attribute({
-                codec: pgCodec,
-                attributeName
-            });
-            const textFieldName = `${fieldName}Text`;
-            // Skip when a physical column already inflects to the companion name
-            // (e.g. `embedding_text` next to `embedding`) — the physical field owns it.
-            if (attributeFieldNames.has(textFieldName))
-                continue;
-            mapping[textFieldName] = fieldName;
-        }
-    }
-    return mapping;
-}
 /**
  * Creates the LlmTextMutationPlugin.
  *
  * Hooks into GraphQLInputObjectType_fields for create/update input types
- * and adds `{columnName}Text: String` for each vector column.
- *
- * Also wraps mutation resolvers via GraphQLObjectType_fields_field to
- * intercept `*Text` companion field values, embed them, and inject the
- * resulting vectors before the mutation executes.
+ * and adds `{columnName}Text: String` for each vector column, tagged for
+ * plan-time embedding.
  */
 export function createLlmTextMutationPlugin() {
     return {
         name: 'LlmTextMutationPlugin',
-        version: '0.2.0',
+        version: '0.3.0',
         description: 'Adds text companion fields on mutation inputs for vector columns — ' +
             'text is embedded server-side before storing',
         after: [
@@ -106,7 +80,7 @@ export function createLlmTextMutationPlugin() {
                     if (!hasExplicitMutationScope && (!looksLikeMutationInput || isFilterOrCondition)) {
                         return fields;
                     }
-                    const { graphql: { GraphQLString } } = build;
+                    const { graphql: { GraphQLString, getNullableType, isNonNullType } } = build;
                     // Find vector columns on this table
                     const vectorColumns = [];
                     for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
@@ -131,94 +105,27 @@ export function createLlmTextMutationPlugin() {
                         if (textFieldName in newFields) {
                             continue;
                         }
+                        const vectorField = newFields[fieldName];
+                        const required = !!vectorField && isNonNullType(vectorField.type);
+                        if (required) {
+                            newFields = {
+                                ...newFields,
+                                [fieldName]: { ...vectorField, type: getNullableType(vectorField.type) }
+                            };
+                        }
                         newFields = build.extend(newFields, {
-                            [textFieldName]: {
+                            [textFieldName]: embedField({ kind: 'companion', into: fieldName, required }, {
                                 type: GraphQLString,
                                 description: `Natural language text to embed server-side into the \`${fieldName}\` vector column. ` +
-                                    `Mutually exclusive with \`${fieldName}\` — provide one or the other. ` +
+                                    `Provide \`${fieldName}\` or \`${textFieldName}\`; if both are given, \`${fieldName}\` is used. ` +
                                     'Requires the LLM plugin to be configured with an embedding provider.'
-                            }
+                            })
                         }, `LlmTextMutationPlugin adding ${textFieldName} companion field for vector column '${columnName}'`);
                     }
                     return newFields;
                 },
-                /**
-                 * Wrap create/update mutation resolvers to intercept `*Text` companion
-                 * field values, embed them using the configured embedder, and inject
-                 * the resulting vector into the corresponding vector field.
-                 *
-                 * Uses the same v4-style resolver wrapping pattern as graphile-upload-plugin
-                 * and graphile-bucket-provisioner-plugin. grafserv v5 supports this through
-                 * its backwards-compatibility layer.
-                 *
-                 * If the embedder returns null (e.g. quota exceeded), throws an error.
-                 */
-                GraphQLObjectType_fields_field(field, build, context) {
-                    const { scope: { isRootMutation, fieldName, pgCodec } } = context;
-                    // Only wrap root mutation fields on tables with attributes
-                    if (!isRootMutation || !pgCodec || !pgCodec.attributes) {
-                        return field;
-                    }
-                    // Only wrap create/update mutations
-                    const isCreate = fieldName.startsWith('create');
-                    const isUpdate = fieldName.startsWith('update');
-                    if (!isCreate && !isUpdate) {
-                        return field;
-                    }
-                    // Build the text→vector mapping for this codec
-                    const textToVectorMap = getTextToVectorMapping(pgCodec, build);
-                    if (Object.keys(textToVectorMap).length === 0) {
-                        return field;
-                    }
-                    const embedder = build.llmEmbedder;
-                    const defaultResolver = (obj) => obj[fieldName];
-                    const { resolve: oldResolve = defaultResolver, ...rest } = field;
-                    return {
-                        ...rest,
-                        async resolve(source, args, graphqlContext, info) {
-                            // Walk through the input args and embed any *Text companion fields
-                            async function embedTextFields(obj) {
-                                if (!obj || typeof obj !== 'object')
-                                    return;
-                                const pending = [];
-                                for (const key of Object.keys(obj)) {
-                                    const value = obj[key];
-                                    // Check if this key is a *Text companion field
-                                    if (key in textToVectorMap && typeof value === 'string') {
-                                        const vectorFieldName = textToVectorMap[key];
-                                        pending.push((async () => {
-                                            if (!embedder) {
-                                                throw new Error(`EMBED_NOT_CONFIGURED: Cannot embed ${key} — no embedding provider configured. ` +
-                                                    'Set defaultEmbedder in GraphileLlmPreset options or EMBEDDER_PROVIDER env var.');
-                                            }
-                                            const startTime = Date.now();
-                                            const vector = await embedder(value);
-                                            const latencyMs = Date.now() - startTime;
-                                            if (vector === null) {
-                                                throw new Error(`EMBED_QUOTA_EXCEEDED: Cannot embed ${key} — embedding quota exceeded. ` +
-                                                    'Upgrade your plan or wait for the next billing period.');
-                                            }
-                                            console.log(`[graphile-llm] Mutation embed: field=${key}, dims=${vector.length}, latency=${latencyMs}ms`);
-                                            // Inject the vector into the corresponding field
-                                            obj[vectorFieldName] = vector;
-                                            // Remove the consumed *Text field
-                                            delete obj[key];
-                                        })());
-                                        continue;
-                                    }
-                                    // Recurse into nested objects (e.g. input.article.embeddingText)
-                                    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
-                                        pending.push(embedTextFields(value));
-                                    }
-                                }
-                                if (pending.length > 0) {
-                                    await Promise.all(pending);
-                                }
-                            }
-                            await embedTextFields(args);
-                            return oldResolve(source, args, graphqlContext, info);
-                        }
-                    };
+                finalize(schema, build) {
+                    return planTimeEmbedding(schema, build);
                 }
             }
         }

package/esm/plugins/text-search-plugin.d.ts

@@ -10,24 +10,21 @@
  * accepts a compound input (point + distance) and the plugin handles
  * the conversion to SQL internally.
  *
- * The `text` field is mutually exclusive with `vector`: clients provide
- * one or the other. When `text` is provided, the plugin embeds it and
- * injects the resulting vector into the normal pgvector pipeline.
+ * Clients provide `text` or `vector`; `vector` becomes optional. When both
+ * are given the vector wins. `unifiedSearch` text is embedded too, so pgvector
+ * participates alongside the text adapters.
  *
- * Runtime embedding for query filters uses the v4-style resolver wrapping
- * approach (same as graphile-upload-plugin). When a connection query's
- * `where` argument includes a VectorNearbyInput with `text`, the resolver
- * wrapper embeds the text and replaces it with the resulting vector before
- * the plan executes.
+ * The text is embedded while the operation is planned (see embed-inputs.ts),
+ * before SQL is built.
  *
- * If the embedder is not configured, the `text` field is still registered
- * (so the schema is stable) but will return a clear error at execution time.
+ * If no embedder is configured, `text` is ignored and `unifiedSearch` runs
+ * on the text adapters only.
  *
  * If the embedder returns null (e.g. quota exceeded when the metering
  * plugin is loaded), behavior depends on `onQuotaExceeded`:
- * - `'degrade'` (default): silently removes the text field and continues
- *   with text-only search as a graceful fallback.
- * - `'throw'`: always throws an error, even if text adapters could handle it.
+ * - `'degrade'` (default): drops the text and continues without the vector
+ *   filter (text-only search for `unifiedSearch`).
+ * - `'throw'`: throws an error.
  */
 import type { GraphileConfig } from 'graphile-config';
 declare global {
@@ -43,14 +40,18 @@ declare global {
  *
  * If the embedder returns null (e.g. quota exceeded), the text field is
  * removed so the pgvector filter is skipped — graceful text-only fallback.
+ *
+ * @deprecated The plugins no longer call this: under Grafast a resolver runs
+ * after the plan's SQL, so embedding there is too late. They embed at plan
+ * time through `embedField` and `planTimeEmbedding` instead.
  */
 export declare function embedTextInWhere(obj: any, embedder: (text: string) => Promise<number[] | null>, hasTextAdapters: boolean, onQuotaExceeded?: 'degrade' | 'throw'): Promise<void>;
 /**
  * Creates the LlmTextSearchPlugin.
  *
  * Hooks into VectorNearbyInput to add a `text` field alongside the
- * existing `vector` field. When a user provides `text`, the plugin's
- * resolver wrapper embeds it before passing to pgvector.
+ * existing `vector` field, and tags `text` and `unifiedSearch` for
+ * plan-time embedding.
  */
 export declare function createLlmTextSearchPlugin(options?: {
     onQuotaExceeded?: 'degrade' | 'throw';