@jamesaphoenix/tx-core 0.4.2 → 0.4.4

package/dist/services/query-expansion-service.d.ts

@@ -1,4 +1,5 @@
 import { Context, Effect, Layer } from "effect";
+import { LlmService } from "./llm-service.js";
 declare const QueryExpansionUnavailableError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
     readonly _tag: "QueryExpansionUnavailableError";
 } & Readonly<A>;
@@ -13,6 +14,14 @@ export declare class QueryExpansionUnavailableError extends QueryExpansionUnavai
 /**
  * Result of query expansion.
  */
+export declare const QueryExpansionResultSchema: {
+    /** Original query */
+    original: string;
+    /** Expanded queries (includes original plus alternatives) */
+    expanded: readonly string[];
+    /** Whether expansion was performed (false if using noop) */
+    wasExpanded: boolean;
+};
 export interface QueryExpansionResult {
     /** Original query */
     readonly original: string;
@@ -21,6 +30,10 @@ export interface QueryExpansionResult {
     /** Whether expansion was performed (false if using noop) */
     readonly wasExpanded: boolean;
 }
+/** Maximum number of expanded queries (excluding original) to prevent unbounded generation */
+export declare const MAX_EXPANSION_QUERIES = 5;
+/** Maximum character length for any single expanded query */
+export declare const MAX_QUERY_LENGTH = 200;
 declare const QueryExpansionService_base: Context.TagClass<QueryExpansionService, "QueryExpansionService", {
     /** Expand a search query into multiple alternative phrasings */
     readonly expand: (query: string) => Effect.Effect<QueryExpansionResult, QueryExpansionUnavailableError>;
@@ -31,25 +44,33 @@ declare const QueryExpansionService_base: Context.TagClass<QueryExpansionService
  * QueryExpansionService uses an LLM to generate alternative phrasings of search queries.
  * This improves recall by searching for semantically equivalent but differently worded queries.
  *
- * Design: Following DD-006 patterns for LLM integration.
- * The service gracefully degrades when ANTHROPIC_API_KEY is not set.
+ * Design: Following DD-006 patterns for LLM integration, DD-022 for centralized LLM service.
+ * The service gracefully degrades when no LLM backend is available.
  */
 export declare class QueryExpansionService extends QueryExpansionService_base {
 }
+/**
+ * Validate and limit expanded query alternatives.
+ * Filters out empty, overly long, duplicate, and non-string entries,
+ * then caps the total number of expansions.
+ *
+ * @returns Array with original query first, followed by up to MAX_EXPANSION_QUERIES alternatives
+ */
+export declare const validateExpansions: (query: string, alternatives: unknown[]) => string[];
 /**
  * Noop implementation - returns original query only.
- * Used when ANTHROPIC_API_KEY is not set or LLM features are disabled.
+ * Used when no LLM backend is available or LLM features are disabled.
  */
 export declare const QueryExpansionServiceNoop: Layer.Layer<QueryExpansionService, never, never>;
 /**
- * Live implementation using Anthropic Claude API.
- * Lazy-loads the SDK and caches the client.
+ * Live implementation using centralized LlmService (DD-022).
+ * Delegates all LLM calls to LlmService instead of calling Anthropic SDK directly.
  */
-export declare const QueryExpansionServiceLive: Layer.Layer<QueryExpansionService, QueryExpansionUnavailableError, never>;
+export declare const QueryExpansionServiceLive: Layer.Layer<QueryExpansionService, never, LlmService>;
 /**
- * Auto-detecting layer that uses Live if ANTHROPIC_API_KEY is set, Noop otherwise.
- * This allows graceful degradation when the API key is not configured.
+ * Auto-detecting layer that uses Live if LlmService is available, Noop otherwise.
+ * This allows graceful degradation when no LLM backend is configured.
  */
-export declare const QueryExpansionServiceAuto: Layer.Layer<QueryExpansionService, QueryExpansionUnavailableError, never>;
+export declare const QueryExpansionServiceAuto: Layer.Layer<QueryExpansionService, never, LlmService>;
 export {};
 //# sourceMappingURL=query-expansion-service.d.ts.map

package/dist/services/query-expansion-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-expansion-service.d.ts","sourceRoot":"","sources":["../../src/services/query-expansion-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAkB,MAAM,QAAQ,CAAA;;;;AAG/D;;GAEG;AACH,qBAAa,8BAA+B,SAAQ,oCAAmD;IACrG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAC;IACA,IAAI,OAAO,WAEV;CACF;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC9B;;IA2BG,gEAAgE;qBAC/C,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,8BAA8B,CAAC;IACvG,4CAA4C;0BACtB,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;;AAbtD;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,0BAQxC;CAAG;AAyDN;;;GAGG;AACH,eAAO,MAAM,yBAAyB,kDAUrC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,2EAmFrC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,2EAUrC,CAAA"}
+{"version":3,"file":"query-expansion-service.d.ts","sourceRoot":"","sources":["../../src/services/query-expansion-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;;;;AAE7C;;GAEG;AACH,qBAAa,8BAA+B,SAAQ,oCAAmD;IACrG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAC;IACA,IAAI,OAAO,WAEV;CACF;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B;IACrC,qBAAqB;cACL,MAAM;IACtB,6DAA6D;cAC7C,SAAS,MAAM,EAAE;IACjC,4DAA4D;iBACtC,OAAO;CAC9B,CAAA;AAGD,MAAM,WAAW,oBAAoB;IACnC,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC9B;AAED,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,MAAM,CAAA;;IAY/B,gEAAgE;qBAC/C,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE,8BAA8B,CAAC;IACvG,4CAA4C;0BACtB,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;;AAbtD;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,0BAQxC;CAAG;AAyDN;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,MAAM,EACb,cAAc,OAAO,EAAE,KACtB,MAAM,EAYR,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,kDAUrC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,uDAwCrC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,uDAMrC,CAAA"}

package/dist/services/query-expansion-service.js

@@ -1,5 +1,6 @@
-import { Context, Effect, Layer, Config, Option } from "effect";
+import { Context, Effect, Layer } from "effect";
 import { Data } from "effect";
+import { LlmService } from "./llm-service.js";
 /**
  * Error indicating query expansion is unavailable.
  */
@@ -8,12 +9,27 @@ export class QueryExpansionUnavailableError extends Data.TaggedError("QueryExpan
         return `Query expansion unavailable: ${this.reason}`;
     }
 }
+/**
+ * Result of query expansion.
+ */
+export const QueryExpansionResultSchema = {
+    /** Original query */
+    original: "",
+    /** Expanded queries (includes original plus alternatives) */
+    expanded: [],
+    /** Whether expansion was performed (false if using noop) */
+    wasExpanded: false
+};
+/** Maximum number of expanded queries (excluding original) to prevent unbounded generation */
+export const MAX_EXPANSION_QUERIES = 5;
+/** Maximum character length for any single expanded query */
+export const MAX_QUERY_LENGTH = 200;
 /**
  * QueryExpansionService uses an LLM to generate alternative phrasings of search queries.
  * This improves recall by searching for semantically equivalent but differently worded queries.
  *
- * Design: Following DD-006 patterns for LLM integration.
- * The service gracefully degrades when ANTHROPIC_API_KEY is not set.
+ * Design: Following DD-006 patterns for LLM integration, DD-022 for centralized LLM service.
+ * The service gracefully degrades when no LLM backend is available.
  */
 export class QueryExpansionService extends Context.Tag("QueryExpansionService")() {
 }
@@ -78,9 +94,26 @@ const parseLlmJson = (raw) => {
     }
     return null;
 };
+/**
+ * Validate and limit expanded query alternatives.
+ * Filters out empty, overly long, duplicate, and non-string entries,
+ * then caps the total number of expansions.
+ *
+ * @returns Array with original query first, followed by up to MAX_EXPANSION_QUERIES alternatives
+ */
+export const validateExpansions = (query, alternatives) => {
+    const uniqueAlternatives = [...new Set(alternatives
+            .filter((alt) => typeof alt === "string" && alt.trim().length > 0)
+            .map(alt => alt.trim())
+            .filter(alt => alt.length <= MAX_QUERY_LENGTH))];
+    return [query, ...uniqueAlternatives
+            .filter(alt => alt.toLowerCase() !== query.toLowerCase())
+            .slice(0, MAX_EXPANSION_QUERIES)
+    ];
+};
 /**
  * Noop implementation - returns original query only.
- * Used when ANTHROPIC_API_KEY is not set or LLM features are disabled.
+ * Used when no LLM backend is available or LLM features are disabled.
  */
 export const QueryExpansionServiceNoop = Layer.succeed(QueryExpansionService, {
     expand: (query) => Effect.succeed({
@@ -91,84 +124,42 @@ export const QueryExpansionServiceNoop = Layer.succeed(QueryExpansionService, {
     isAvailable: () => Effect.succeed(false)
 });
 /**
- * Live implementation using Anthropic Claude API.
- * Lazy-loads the SDK and caches the client.
+ * Live implementation using centralized LlmService (DD-022).
+ * Delegates all LLM calls to LlmService instead of calling Anthropic SDK directly.
  */
 export const QueryExpansionServiceLive = Layer.effect(QueryExpansionService, Effect.gen(function* () {
-    // Read API key from environment
-    const apiKey = yield* Config.string("ANTHROPIC_API_KEY").pipe(Effect.mapError(() => new QueryExpansionUnavailableError({
-        reason: "ANTHROPIC_API_KEY environment variable is not set"
-    })));
-    // Lazy-load client
-    let client = null;
-    const ensureClient = Effect.gen(function* () {
-        if (client)
-            return client;
-        // Dynamic import of Anthropic SDK (optional peer dependency)
-        const Anthropic = yield* Effect.tryPromise({
-            try: async () => {
-                // @ts-expect-error - @anthropic-ai/sdk is an optional peer dependency
-                const mod = await import("@anthropic-ai/sdk");
-                return mod.default;
-            },
-            catch: () => new QueryExpansionUnavailableError({
-                reason: "@anthropic-ai/sdk is not installed"
-            })
-        });
-        client = new Anthropic({ apiKey });
-        return client;
-    });
+    const llm = yield* LlmService;
     return {
         expand: (query) => Effect.gen(function* () {
-            const anthropic = yield* ensureClient;
-            const response = yield* Effect.tryPromise({
-                try: () => anthropic.messages.create({
-                    model: "claude-haiku-4-20250514",
-                    max_tokens: 256,
-                    messages: [{
-                            role: "user",
-                            content: EXPANSION_PROMPT + JSON.stringify(query)
-                        }]
-                }),
-                catch: (e) => new QueryExpansionUnavailableError({
-                    reason: `API call failed: ${String(e)}`
-                })
-            });
-            // Extract text from response
-            const textContent = response.content.find(c => c.type === "text");
-            if (!textContent || !textContent.text) {
+            const text = yield* llm.complete(EXPANSION_PROMPT + JSON.stringify(query), { model: "claude-haiku-4-5-20251001", maxTokens: 256 }).pipe(Effect.mapError((e) => new QueryExpansionUnavailableError({
+                reason: e.reason
+            })));
+            if (!text) {
                 return { original: query, expanded: [query], wasExpanded: false };
             }
             // Parse the JSON array of expanded queries
-            const alternatives = parseLlmJson(textContent.text);
+            const alternatives = parseLlmJson(text);
             if (!alternatives || !Array.isArray(alternatives)) {
                 return { original: query, expanded: [query], wasExpanded: false };
             }
-            // Filter out empty strings and duplicates
-            const uniqueAlternatives = [...new Set(alternatives
-                    .filter((alt) => typeof alt === "string" && alt.trim().length > 0)
-                    .map(alt => alt.trim()))];
-            // Always include original query first
-            const expanded = [query, ...uniqueAlternatives.filter(alt => alt.toLowerCase() !== query.toLowerCase())];
+            // Validate and limit expansion results
+            const expanded = validateExpansions(query, alternatives);
             return {
                 original: query,
                 expanded,
-                wasExpanded: true
+                wasExpanded: expanded.length > 1
             };
         }),
-        isAvailable: () => Effect.succeed(true)
+        isAvailable: () => llm.isAvailable()
     };
 }));
 /**
- * Auto-detecting layer that uses Live if ANTHROPIC_API_KEY is set, Noop otherwise.
- * This allows graceful degradation when the API key is not configured.
+ * Auto-detecting layer that uses Live if LlmService is available, Noop otherwise.
+ * This allows graceful degradation when no LLM backend is configured.
  */
 export const QueryExpansionServiceAuto = Layer.unwrapEffect(Effect.gen(function* () {
-    // Check if API key is available
-    const apiKey = yield* Config.string("ANTHROPIC_API_KEY").pipe(Effect.option);
-    if (Option.isSome(apiKey) && apiKey.value.trim().length > 0) {
-        return QueryExpansionServiceLive;
-    }
-    return QueryExpansionServiceNoop;
+    const llm = yield* LlmService;
+    const available = yield* llm.isAvailable();
+    return available ? QueryExpansionServiceLive : QueryExpansionServiceNoop;
 }));
 //# sourceMappingURL=query-expansion-service.js.map

package/dist/services/query-expansion-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-expansion-service.js","sourceRoot":"","sources":["../../src/services/query-expansion-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query-expansion-service.js","sourceRoot":"","sources":["../../src/services/query-expansion-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C;;GAEG;AACH,MAAM,OAAO,8BAA+B,SAAQ,IAAI,CAAC,WAAW,CAAC,gCAAgC,CAEnG;IACA,IAAI,OAAO;QACT,OAAO,gCAAgC,IAAI,CAAC,MAAM,EAAE,CAAA;IACtD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,qBAAqB;IACrB,QAAQ,EAAE,EAAY;IACtB,6DAA6D;IAC7D,QAAQ,EAAE,EAAuB;IACjC,4DAA4D;IAC5D,WAAW,EAAE,KAAgB;CAC9B,CAAA;AAYD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAA;AAEtC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAEnC;;;;;;GAMG;AACH,MAAM,OAAO,qBAAsB,SAAQ,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,EAQ5E;CAAG;AAEN;;;GAGG;AACH,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;CAiBxB,CAAA;AAED;;;GAGG;AACH,MAAM,YAAY,GAAG,CAAI,GAAW,EAAY,EAAE;IAChD,2BAA2B;IAC3B,IAAI,CAAC;QAAC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;IAEvD,qCAAqC;IACrC,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAA;IAC/D,IAAI,UAAU,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QAChC,IAAI,CAAC;YAAC,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;IAC1E,CAAC;IAED,iDAAiD;IACjD,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACpC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnB,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QACtC,IAAI,CAAC;YAAC,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;QAE7D,4CAA4C;QAC5C,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;QAC7B,MAAM,SAAS,GAAG,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAA;QAC9C,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC,CAAA;QAClD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAClB,IAAI,CAAC;gBAAC,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC,CAAA;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,KAAa,EACb,YAAuB,EACb,EAAE;IACZ,MAAM,kBAAkB,GAAG,CAAC,GAAG,IAAI,GAAG,CACpC,YAAY;aACT,MAAM,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;aAChF,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;aACtB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,gBAAgB,CAAC,CACjD,CAAC,CAAA;IAEF,OAAO,CAAC,KAAK,EAAE,GAAG,kBAAkB;aACjC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC;aACxD,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC;KACjC,CAAA;AACH,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC,OAAO,CACpD,qBAAqB,EACrB;IACE,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC;QACxC,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,CAAC,KAAK,CAAC;QACjB,WAAW,EAAE,KAAK;KACnB,CAAC;IACF,WAAW,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;CACzC,CACF,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC,MAAM,CACnD,qBAAqB,EACrB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,UAAU,CAAA;IAE7B,OAAO;QACL,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CACxB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAClB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,QAAQ,CAC9B,gBAAgB,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EACxC,EAAE,KAAK,EAAE,2BAA2B,EAAE,SAAS,EAAE,GAAG,EAAE,CACvD,CAAC,IAAI,CACJ,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,8BAA8B,CAAC;gBACxD,MAAM,EAAE,CAAC,CAAC,MAAM;aACjB,CAAC,CAAC,CACJ,CAAA;YAED,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;YACnE,CAAC;YAED,2CAA2C;YAC3C,MAAM,YAAY,GAAG,YAAY,CAAW,IAAI,CAAC,CAAA;YACjD,IAAI,CAAC,YAAY,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;gBAClD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;YACnE,CAAC;YAED,uCAAuC;YACvC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAA;YAExD,OAAO;gBACL,QAAQ,EAAE,KAAK;gBACf,QAAQ;gBACR,WAAW,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC;aACjC,CAAA;QACH,CAAC,CAAC;QAEJ,WAAW,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE;KACrC,CAAA;AACH,CAAC,CAAC,CACH,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,KAAK,CAAC,YAAY,CACzD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,UAAU,CAAA;IAC7B,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,CAAA;IAC1C,OAAO,SAAS,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,yBAAyB,CAAA;AAC1E,CAAC,CAAC,CACH,CAAA"}

package/dist/services/ready-service.d.ts

@@ -3,9 +3,29 @@ import { TaskRepository } from "../repo/task-repo.js";
 import { DependencyRepository } from "../repo/dep-repo.js";
 import { DatabaseError } from "../errors.js";
 import type { Task, TaskId, TaskWithDeps } from "@jamesaphoenix/tx-types";
+/**
+ * Result of checking whether a task is ready to be worked on.
+ * Replaces silent `false` with an explicit reason for not-ready states.
+ */
+export type ReadyCheckResult = {
+    readonly _tag: "Ready";
+} | {
+    readonly _tag: "TaskNotFound";
+    readonly id: TaskId;
+} | {
+    readonly _tag: "WrongStatus";
+    readonly id: TaskId;
+    readonly status: string;
+} | {
+    readonly _tag: "Blocked";
+    readonly id: TaskId;
+    readonly pendingBlockerIds: readonly string[];
+};
+/** Helper to check if a ReadyCheckResult indicates the task is ready. */
+export declare const isReadyResult: (result: ReadyCheckResult) => boolean;
 declare const ReadyService_base: Context.TagClass<ReadyService, "ReadyService", {
     readonly getReady: (limit?: number) => Effect.Effect<readonly TaskWithDeps[], DatabaseError>;
-    readonly isReady: (id: TaskId) => Effect.Effect<boolean, DatabaseError>;
+    readonly isReady: (id: TaskId) => Effect.Effect<ReadyCheckResult, DatabaseError>;
     readonly getBlockers: (id: TaskId) => Effect.Effect<readonly Task[], DatabaseError>;
     readonly getBlocking: (id: TaskId) => Effect.Effect<readonly Task[], DatabaseError>;
 }>;

package/dist/services/ready-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ready-service.d.ts","sourceRoot":"","sources":["../../src/services/ready-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;;uBAKlD,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,YAAY,EAAE,EAAE,aAAa,CAAC;sBAC1E,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC;0BACjD,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,EAAE,aAAa,CAAC;0BAC7D,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,EAAE,aAAa,CAAC;;AANvF,qBAAa,YAAa,SAAQ,iBAQ/B;CAAG;AAEN,eAAO,MAAM,gBAAgB,yEA2E5B,CAAA"}
+{"version":3,"file":"ready-service.d.ts","sourceRoot":"","sources":["../../src/services/ready-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAEzE;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAA;AAEpG,yEAAyE;AACzE,eAAO,MAAM,aAAa,GAAI,QAAQ,gBAAgB,KAAG,OAAkC,CAAA;;uBAKpE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,YAAY,EAAE,EAAE,aAAa,CAAC;sBAC1E,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,aAAa,CAAC;0BAC1D,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,EAAE,aAAa,CAAC;0BAC7D,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,EAAE,aAAa,CAAC;;AANvF,qBAAa,YAAa,SAAQ,iBAQ/B;CAAG;AAEN,eAAO,MAAM,gBAAgB,yEAqG5B,CAAA"}

package/dist/services/ready-service.js

@@ -1,6 +1,8 @@
 import { Context, Effect, Layer } from "effect";
 import { TaskRepository } from "../repo/task-repo.js";
 import { DependencyRepository } from "../repo/dep-repo.js";
+/** Helper to check if a ReadyCheckResult indicates the task is ready. */
+export const isReadyResult = (result) => result._tag === "Ready";
 export class ReadyService extends Context.Tag("ReadyService")() {
 }
 export const ReadyServiceLive = Layer.effect(ReadyService, Effect.gen(function* () {
@@ -8,26 +10,41 @@ export const ReadyServiceLive = Layer.effect(ReadyService, Effect.gen(function*
     const depRepo = yield* DependencyRepository;
     return {
         getReady: (limit = 100) => Effect.gen(function* () {
+            // 1. Single query: get all candidate tasks (excluding actively claimed)
+            // The excludeClaimed filter prevents the thundering herd problem where
+            // multiple workers all see the same tasks and race to claim them.
             const candidates = yield* taskRepo.findAll({
-                status: ["backlog", "ready", "planning"]
+                status: ["backlog", "ready", "planning"],
+                excludeClaimed: true
             });
+            if (candidates.length === 0) {
+                return [];
+            }
+            const candidateIds = candidates.map(t => t.id);
+            // 2-4. Batch queries: get all dependency info in 3 queries instead of 3*N
+            const blockerIdsMap = yield* depRepo.getBlockerIdsForMany(candidateIds);
+            const blockingIdsMap = yield* depRepo.getBlockingIdsForMany(candidateIds);
+            const childIdsMap = yield* taskRepo.getChildIdsForMany(candidateIds);
+            // 5. Single query: get all unique blocker tasks to check their status
+            const allBlockerIds = new Set();
+            for (const blockerIds of blockerIdsMap.values()) {
+                for (const id of blockerIds) {
+                    allBlockerIds.add(id);
+                }
+            }
+            const blockerTasks = allBlockerIds.size > 0
+                ? yield* taskRepo.findByIds([...allBlockerIds])
+                : [];
+            const blockerStatusMap = new Map(blockerTasks.map(t => [t.id, t.status]));
+            // Process in memory (no more queries)
             const ready = [];
             for (const task of candidates) {
-                const blockerIds = yield* depRepo.getBlockerIds(task.id);
-                const blockingIds = yield* depRepo.getBlockingIds(task.id);
-                const childIds = yield* taskRepo.getChildIds(task.id);
-                if (blockerIds.length === 0) {
-                    ready.push({
-                        ...task,
-                        blockedBy: [],
-                        blocks: blockingIds,
-                        children: childIds,
-                        isReady: true
-                    });
-                    continue;
-                }
-                const blockers = yield* taskRepo.findByIds(blockerIds);
-                const allDone = blockers.every(b => b.status === "done");
+                const blockerIds = blockerIdsMap.get(task.id) ?? [];
+                const blockingIds = blockingIdsMap.get(task.id) ?? [];
+                const childIds = childIdsMap.get(task.id) ?? [];
+                // Check if all blockers are done
+                const allDone = blockerIds.length === 0 ||
+                    blockerIds.every(id => blockerStatusMap.get(id) === "done");
                 if (allDone) {
                     ready.push({
                         ...task,
@@ -44,14 +61,20 @@ export const ReadyServiceLive = Layer.effect(ReadyService, Effect.gen(function*
         isReady: (id) => Effect.gen(function* () {
             const task = yield* taskRepo.findById(id);
             if (!task)
-                return false;
-            if (!["backlog", "ready", "planning"].includes(task.status))
-                return false;
+                return { _tag: "TaskNotFound", id };
+            if (!["backlog", "ready", "planning"].includes(task.status)) {
+                return { _tag: "WrongStatus", id, status: task.status };
+            }
             const blockerIds = yield* depRepo.getBlockerIds(id);
             if (blockerIds.length === 0)
-                return true;
+                return { _tag: "Ready" };
             const blockers = yield* taskRepo.findByIds(blockerIds);
-            return blockers.every(b => b.status === "done");
+            const pendingBlockerIds = blockers
+                .filter(b => b.status !== "done")
+                .map(b => b.id);
+            if (pendingBlockerIds.length === 0)
+                return { _tag: "Ready" };
+            return { _tag: "Blocked", id, pendingBlockerIds };
         }),
         getBlockers: (id) => Effect.gen(function* () {
             const blockerIds = yield* depRepo.getBlockerIds(id);

package/dist/services/ready-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"ready-service.js","sourceRoot":"","sources":["../../src/services/ready-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ready-service.js","sourceRoot":"","sources":["../../src/services/ready-service.ts"],"names":[],"mappings":"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"}

package/dist/services/retriever-service.d.ts

@@ -1,16 +1,15 @@
 import { Context, Effect, Layer } from "effect";
 import { LearningRepository } from "../repo/learning-repo.js";
 import { EmbeddingService } from "./embedding-service.js";
-import { QueryExpansionService } from "./query-expansion-service.js";
 import { RerankerService } from "./reranker-service.js";
-import { RetrievalError, DatabaseError } from "../errors.js";
+import { RetrievalError, DatabaseError, EmbeddingDimensionMismatchError } from "../errors.js";
 import type { LearningWithScore, RetrievalOptions } from "@jamesaphoenix/tx-types";
 declare const RetrieverService_base: Context.TagClass<RetrieverService, "RetrieverService", {
     /**
      * Search for learnings matching a query.
      * Returns scored results sorted by relevance (highest first).
      */
-    readonly search: (query: string, options?: RetrievalOptions) => Effect.Effect<readonly LearningWithScore[], RetrievalError | DatabaseError>;
+    readonly search: (query: string, options?: RetrievalOptions) => Effect.Effect<readonly LearningWithScore[], RetrievalError | DatabaseError | EmbeddingDimensionMismatchError>;
     /** Check if retrieval functionality is available */
     readonly isAvailable: () => Effect.Effect<boolean>;
 }>;
@@ -30,20 +29,21 @@ export declare class RetrieverService extends RetrieverService_base {
 export declare const RetrieverServiceNoop: Layer.Layer<RetrieverService, never, never>;
 /**
  * Live implementation with BM25 + vector + RRF pipeline.
- * Uses the default hybrid search with:
- * - Query expansion via LLM
+ * Simplified pipeline:
  * - BM25 full-text search
  * - Vector similarity (when embeddings available)
  * - RRF fusion
- * - Optional LLM re-ranking
+ * - Optional LLM re-ranking (local model)
+ * - Optional MMR diversification
  * - Recency/outcome/frequency boosts
  */
-export declare const RetrieverServiceLive: Layer.Layer<RetrieverService, DatabaseError, LearningRepository | EmbeddingService | QueryExpansionService | RerankerService>;
+export declare const RetrieverServiceLive: Layer.Layer<RetrieverService, DatabaseError, LearningRepository | EmbeddingService | RerankerService>;
 /**
  * Auto-detecting layer that always uses Live since BM25 is always available.
- * The Live implementation gracefully degrades vector search when embeddings
- * are unavailable, so Auto just delegates to Live.
+ * The Live implementation gracefully degrades:
+ * - Vector search skips when EmbeddingService unavailable
+ * - Reranking skips when RerankerService unavailable
  */
-export declare const RetrieverServiceAuto: Layer.Layer<RetrieverService, DatabaseError, LearningRepository | EmbeddingService | QueryExpansionService | RerankerService>;
+export declare const RetrieverServiceAuto: Layer.Layer<RetrieverService, DatabaseError, LearningRepository | EmbeddingService | RerankerService>;
 export {};
 //# sourceMappingURL=retriever-service.d.ts.map

package/dist/services/retriever-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retriever-service.d.ts","sourceRoot":"","sources":["../../src/services/retriever-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAU,MAAM,QAAQ,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAmB,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAGvD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,KAAK,EAAY,iBAAiB,EAAc,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;;IA+BpG;;;OAGG;qBACc,CACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,KACvB,MAAM,CAAC,MAAM,CAAC,SAAS,iBAAiB,EAAE,EAAE,cAAc,GAAG,aAAa,CAAC;IAChF,oDAAoD;0BAC9B,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;;AAnBtD;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,qBAcnC;CAAG;AAwNN;;;GAGG;AACH,eAAO,MAAM,oBAAoB,6CAMhC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,+HAmQhC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,+HAAuB,CAAA"}
+{"version":3,"file":"retriever-service.d.ts","sourceRoot":"","sources":["../../src/services/retriever-service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAU,MAAM,QAAQ,CAAA;AACvD,OAAO,EAAE,kBAAkB,EAAmB,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAA;AAC7F,OAAO,KAAK,EAAY,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;;IAiCxF;;;OAGG;qBACc,CACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,KACvB,MAAM,CAAC,MAAM,CAAC,SAAS,iBAAiB,EAAE,EAAE,cAAc,GAAG,aAAa,GAAG,+BAA+B,CAAC;IAClH,oDAAoD;0BAC9B,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;;AAnBtD;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,qBAcnC;CAAG;AA0NN;;;GAGG;AACH,eAAO,MAAM,oBAAoB,6CAMhC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,uGA4HhC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,uGAKhC,CAAA"}