@indexnetwork/protocol 4.14.2-rc.356.1 → 4.16.0-rc.358.1

package/dist/shared/hyde/hyde.frame.js

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+export const HYDE_HARD_CONSTRAINT_TYPES = [
+    'location',
+    'time',
+    'numeric',
+    'credential',
+    'organization',
+    'exclusivity',
+    'other',
+];
+export const HYDE_NAMED_ENTITY_TYPES = [
+    'person',
+    'organization',
+    'product',
+    'location',
+    'event',
+    'other',
+];
+const roleSchema = z.object({
+    role: z.string().min(1),
+    evidence: z.string().min(1).describe('Exact evidence span copied from sourceText'),
+});
+const hardConstraintSchema = z.object({
+    type: z.enum(HYDE_HARD_CONSTRAINT_TYPES),
+    value: z.string().min(1),
+    evidence: z.string().min(1).describe('Exact evidence span copied from sourceText'),
+});
+const namedEntitySchema = z.object({
+    type: z.enum(HYDE_NAMED_ENTITY_TYPES),
+    name: z.string().min(1),
+    evidence: z.string().min(1).describe('Exact evidence span copied from sourceText'),
+});
+const vocabularySchema = z.object({
+    term: z.string().min(1),
+    evidence: z.string().min(1).describe('Exact evidence span copied from sourceText'),
+});
+/** Structured-output schema for source-grounded frames. */
+export const HydeSourceFrameSchema = z.object({
+    sourceRoles: z.array(roleSchema),
+    counterpartRoles: z.array(roleSchema),
+    hardConstraints: z.array(hardConstraintSchema),
+    namedEntities: z.array(namedEntitySchema),
+    domainVocabulary: z.array(vocabularySchema),
+});
+function escapeRegularExpression(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Case-insensitive literal matching bounded by Unicode letters and numbers. */
+function containsAlphanumericSpanCaseInsensitive(container, value) {
+    const needle = value.trim();
+    if (!needle)
+        return false;
+    return new RegExp(`(?<![\\p{L}\\p{M}\\p{N}])${escapeRegularExpression(needle)}(?![\\p{L}\\p{M}\\p{N}])`, 'iu').test(container);
+}
+function hasExactEvidence(sourceText, evidence) {
+    return containsAlphanumericSpanCaseInsensitive(sourceText, evidence);
+}
+const GENERIC_ROLE_TOKENS = new Set([
+    'advisor', 'analyst', 'attendee', 'borrower', 'builder', 'buyer', 'candidate',
+    'capitalist', 'ceo', 'cfo', 'client', 'cmo', 'cofounder', 'collaborator',
+    'consultant', 'coo', 'creator', 'cto', 'customer', 'designer', 'developer',
+    'director', 'employer', 'engineer', 'entrepreneur', 'executive', 'expert',
+    'founder', 'funder', 'hire', 'hiring', 'investor', 'leader', 'lender',
+    'manager', 'mentor', 'operator', 'organizer', 'owner', 'partner', 'practitioner',
+    'professional', 'provider', 'recruiter', 'researcher', 'scientist', 'seller',
+    'speaker', 'specialist', 'sponsor', 'strategist', 'supplier', 'technologist',
+    'vendor', 'vp',
+]);
+const GENERIC_ROLE_MODIFIERS = new Set([
+    'business', 'co', 'commercial', 'community', 'creative', 'early', 'experienced',
+    'growth', 'independent', 'industry', 'junior', 'lead', 'local', 'nonprofit',
+    'operations', 'product', 'professional', 'public', 'senior', 'stage',
+    'startup', 'technical', 'venture',
+]);
+function roleTokens(role) {
+    return role.toLowerCase().match(/[\p{L}\p{M}\d]+/gu) ?? [];
+}
+function hasUnsupportedSourceRoleMaterial(role, evidence) {
+    const substantiveTokens = roleTokens(role).filter((token) => !GENERIC_ROLE_MODIFIERS.has(token));
+    return substantiveTokens.length === 0
+        || substantiveTokens.some((token) => !containsAlphanumericSpanCaseInsensitive(evidence, token));
+}
+function hasUnsupportedCounterpartRoleMaterial(role, evidence) {
+    return roleTokens(role).some((token) => !GENERIC_ROLE_TOKENS.has(token)
+        && !GENERIC_ROLE_MODIFIERS.has(token)
+        && !containsAlphanumericSpanCaseInsensitive(evidence, token));
+}
+/**
+ * Remove frame elements that cross the source-evidence boundary. Structured
+ * payloads must occur inside their evidence span. Source roles require grounded
+ * substantive tokens; counterpart roles may add generic inferred role language.
+ */
+export function sanitizeHydeSourceFrame(sourceText, frame) {
+    const grounded = (items) => items.filter((item) => hasExactEvidence(sourceText, item.evidence));
+    return {
+        sourceRoles: grounded(frame.sourceRoles)
+            .filter((item) => !hasUnsupportedSourceRoleMaterial(item.role, item.evidence)),
+        counterpartRoles: grounded(frame.counterpartRoles)
+            .filter((item) => !hasUnsupportedCounterpartRoleMaterial(item.role, item.evidence)),
+        hardConstraints: grounded(frame.hardConstraints)
+            .filter((item) => containsAlphanumericSpanCaseInsensitive(item.evidence, item.value)),
+        namedEntities: grounded(frame.namedEntities)
+            .filter((item) => containsAlphanumericSpanCaseInsensitive(item.evidence, item.name)),
+        domainVocabulary: grounded(frame.domainVocabulary)
+            .filter((item) => containsAlphanumericSpanCaseInsensitive(item.evidence, item.term)),
+    };
+}
+//# sourceMappingURL=hyde.frame.js.map

package/dist/shared/hyde/hyde.frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hyde.frame.js","sourceRoot":"/","sources":["shared/hyde/hyde.frame.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\n/** Source-grounded role supported by an exact span from the source text. */\nexport interface HydeFrameRole {\n  role: string;\n  evidence: string;\n}\n\nexport const HYDE_HARD_CONSTRAINT_TYPES = [\n  'location',\n  'time',\n  'numeric',\n  'credential',\n  'organization',\n  'exclusivity',\n  'other',\n] as const;\n\nexport type HydeHardConstraintType = (typeof HYDE_HARD_CONSTRAINT_TYPES)[number];\n\n/** Explicit hard constraint supported by an exact span from the source text. */\nexport interface HydeFrameHardConstraint {\n  type: HydeHardConstraintType;\n  value: string;\n  evidence: string;\n}\n\nexport const HYDE_NAMED_ENTITY_TYPES = [\n  'person',\n  'organization',\n  'product',\n  'location',\n  'event',\n  'other',\n] as const;\n\nexport type HydeNamedEntityType = (typeof HYDE_NAMED_ENTITY_TYPES)[number];\n\n/** Named entity supported by an exact span from the source text. */\nexport interface HydeFrameNamedEntity {\n  type: HydeNamedEntityType;\n  name: string;\n  evidence: string;\n}\n\n/** Domain term supported by an exact span from the source text. */\nexport interface HydeFrameVocabulary {\n  term: string;\n  evidence: string;\n}\n\n/**\n * Source-grounded controls for frame-constrained HyDE generation.\n * Counterpart roles may be reciprocal/complementary inferences, but their\n * evidence must still be an exact span from the source text.\n */\nexport interface HydeSourceFrame {\n  sourceRoles: HydeFrameRole[];\n  counterpartRoles: HydeFrameRole[];\n  hardConstraints: HydeFrameHardConstraint[];\n  namedEntities: HydeFrameNamedEntity[];\n  domainVocabulary: HydeFrameVocabulary[];\n}\n\nconst roleSchema = z.object({\n  role: z.string().min(1),\n  evidence: z.string().min(1).describe('Exact evidence span copied from sourceText'),\n});\n\nconst hardConstraintSchema = z.object({\n  type: z.enum(HYDE_HARD_CONSTRAINT_TYPES),\n  value: z.string().min(1),\n  evidence: z.string().min(1).describe('Exact evidence span copied from sourceText'),\n});\n\nconst namedEntitySchema = z.object({\n  type: z.enum(HYDE_NAMED_ENTITY_TYPES),\n  name: z.string().min(1),\n  evidence: z.string().min(1).describe('Exact evidence span copied from sourceText'),\n});\n\nconst vocabularySchema = z.object({\n  term: z.string().min(1),\n  evidence: z.string().min(1).describe('Exact evidence span copied from sourceText'),\n});\n\n/** Structured-output schema for source-grounded frames. */\nexport const HydeSourceFrameSchema = z.object({\n  sourceRoles: z.array(roleSchema),\n  counterpartRoles: z.array(roleSchema),\n  hardConstraints: z.array(hardConstraintSchema),\n  namedEntities: z.array(namedEntitySchema),\n  domainVocabulary: z.array(vocabularySchema),\n});\n\nfunction escapeRegularExpression(value: string): string {\n  return value.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/** Case-insensitive literal matching bounded by Unicode letters and numbers. */\nfunction containsAlphanumericSpanCaseInsensitive(container: string, value: string): boolean {\n  const needle = value.trim();\n  if (!needle) return false;\n  return new RegExp(\n    `(?<![\\\\p{L}\\\\p{M}\\\\p{N}])${escapeRegularExpression(needle)}(?![\\\\p{L}\\\\p{M}\\\\p{N}])`,\n    'iu',\n  ).test(container);\n}\n\nfunction hasExactEvidence(sourceText: string, evidence: string): boolean {\n  return containsAlphanumericSpanCaseInsensitive(sourceText, evidence);\n}\n\nconst GENERIC_ROLE_TOKENS = new Set([\n  'advisor', 'analyst', 'attendee', 'borrower', 'builder', 'buyer', 'candidate',\n  'capitalist', 'ceo', 'cfo', 'client', 'cmo', 'cofounder', 'collaborator',\n  'consultant', 'coo', 'creator', 'cto', 'customer', 'designer', 'developer',\n  'director', 'employer', 'engineer', 'entrepreneur', 'executive', 'expert',\n  'founder', 'funder', 'hire', 'hiring', 'investor', 'leader', 'lender',\n  'manager', 'mentor', 'operator', 'organizer', 'owner', 'partner', 'practitioner',\n  'professional', 'provider', 'recruiter', 'researcher', 'scientist', 'seller',\n  'speaker', 'specialist', 'sponsor', 'strategist', 'supplier', 'technologist',\n  'vendor', 'vp',\n]);\n\nconst GENERIC_ROLE_MODIFIERS = new Set([\n  'business', 'co', 'commercial', 'community', 'creative', 'early', 'experienced',\n  'growth', 'independent', 'industry', 'junior', 'lead', 'local', 'nonprofit',\n  'operations', 'product', 'professional', 'public', 'senior', 'stage',\n  'startup', 'technical', 'venture',\n]);\n\nfunction roleTokens(role: string): string[] {\n  return role.toLowerCase().match(/[\\p{L}\\p{M}\\d]+/gu) ?? [];\n}\n\nfunction hasUnsupportedSourceRoleMaterial(role: string, evidence: string): boolean {\n  const substantiveTokens = roleTokens(role).filter((token) => !GENERIC_ROLE_MODIFIERS.has(token));\n  return substantiveTokens.length === 0\n    || substantiveTokens.some((token) => !containsAlphanumericSpanCaseInsensitive(evidence, token));\n}\n\nfunction hasUnsupportedCounterpartRoleMaterial(role: string, evidence: string): boolean {\n  return roleTokens(role).some((token) =>\n    !GENERIC_ROLE_TOKENS.has(token)\n    && !GENERIC_ROLE_MODIFIERS.has(token)\n    && !containsAlphanumericSpanCaseInsensitive(evidence, token));\n}\n\n/**\n * Remove frame elements that cross the source-evidence boundary. Structured\n * payloads must occur inside their evidence span. Source roles require grounded\n * substantive tokens; counterpart roles may add generic inferred role language.\n */\nexport function sanitizeHydeSourceFrame(sourceText: string, frame: HydeSourceFrame): HydeSourceFrame {\n  const grounded = <T extends { evidence: string }>(items: T[]): T[] =>\n    items.filter((item) => hasExactEvidence(sourceText, item.evidence));\n  return {\n    sourceRoles: grounded(frame.sourceRoles)\n      .filter((item) => !hasUnsupportedSourceRoleMaterial(item.role, item.evidence)),\n    counterpartRoles: grounded(frame.counterpartRoles)\n      .filter((item) => !hasUnsupportedCounterpartRoleMaterial(item.role, item.evidence)),\n    hardConstraints: grounded(frame.hardConstraints)\n      .filter((item) => containsAlphanumericSpanCaseInsensitive(item.evidence, item.value)),\n    namedEntities: grounded(frame.namedEntities)\n      .filter((item) => containsAlphanumericSpanCaseInsensitive(item.evidence, item.name)),\n    domainVocabulary: grounded(frame.domainVocabulary)\n      .filter((item) => containsAlphanumericSpanCaseInsensitive(item.evidence, item.term)),\n  };\n}\n"]}

package/dist/shared/hyde/hyde.generator.d.ts

@@ -1,3 +1,9 @@
+/**
+ * HyDE Generator Agent: pure LLM agent for generating hypothetical documents
+ * in the target corpus voice. Uses free-text lens labels instead of enum strategies.
+ */
+import type { BaseLanguageModelInput } from '@langchain/core/language_models/base';
+import type { HydeSourceFrame } from './hyde.frame.js';
 import type { HydeTargetCorpus } from './lens.inferrer.js';
 export interface HydeGeneratorOutput {
     text: string;
@@ -9,19 +15,25 @@ export interface HydeGenerateInput {
     lens: string;
     /** Which corpus voice to generate in. */
     corpus: HydeTargetCorpus;
+    /** Sanitized source-grounded frame. Absence preserves the exact legacy prompt. */
+    sourceFrame?: HydeSourceFrame;
 }
-/**
- * Generates hypothetical documents in a target corpus voice for semantic search.
- * Uses free-text lens labels (from LensInferrer) instead of enum strategies.
- */
+/** Minimal structured model contract used for deterministic injection in tests. */
+export interface HydeGeneratorStructuredModel {
+    invoke(input: BaseLanguageModelInput, config?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+/** Build the frame-v1 generation prompt from sanitized source evidence. */
+export declare function buildFrameHydePrompt(input: HydeGenerateInput & {
+    sourceFrame: HydeSourceFrame;
+}): string;
+/** Generates hypothetical documents in a target corpus voice for semantic search. */
 export declare class HydeGenerator {
-    private model;
-    /**
-     * Generate a hypothetical document for the given source text and lens.
-     *
-     * @param input - Source text, lens label, and target corpus
-     * @returns Generated hypothetical document text
-     */
+    private model?;
+    constructor(model?: HydeGeneratorStructuredModel);
+    private getModel;
+    /** Generate a hypothetical document for the given source text and lens. */
     generate(input: HydeGenerateInput): Promise<HydeGeneratorOutput>;
 }
 //# sourceMappingURL=hyde.generator.d.ts.map

package/dist/shared/hyde/hyde.generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hyde.generator.d.ts","sourceRoot":"/","sources":["shared/hyde/hyde.generator.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAwB3D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAEV;IAEH;;;;;OAKG;IAEG,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAoBvE"}
+{"version":3,"file":"hyde.generator.d.ts","sourceRoot":"/","sources":["shared/hyde/hyde.generator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAQnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAoB3D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EAAE,gBAAgB,CAAC;IACzB,kFAAkF;IAClF,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,mFAAmF;AACnF,MAAM,WAAW,4BAA4B;IAC3C,MAAM,CAAC,KAAK,EAAE,sBAAsB,EAAE,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5F;AAMD,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG;IAAE,WAAW,EAAE,eAAe,CAAA;CAAE,GAAG,MAAM,CA0BxG;AAED,qFAAqF;AACrF,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAC,CAA+B;gBAEjC,KAAK,CAAC,EAAE,4BAA4B;IAQhD,OAAO,CAAC,QAAQ;IAOhB,2EAA2E;IAErE,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAuBvE"}

package/dist/shared/hyde/hyde.generator.js

@@ -7,17 +7,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-/**
- * HyDE Generator Agent: pure LLM agent for generating hypothetical documents
- * in the target corpus voice. Uses free-text lens labels instead of enum strategies.
- */
 import { HumanMessage, SystemMessage } from '@langchain/core/messages';
 import { z } from 'zod';
-import { HYDE_CORPUS_PROMPTS } from './hyde.strategies.js';
-import { Timed } from "../observability/performance.js";
-import { protocolLogger } from '../observability/protocol.logger.js';
 import { createStructuredModel } from "../agent/model.config.js";
 import { invokeWithAbortSignal } from "../agent/model-signal.js";
+import { protocolLogger } from '../observability/protocol.logger.js';
+import { Timed } from "../observability/performance.js";
+import { HYDE_CORPUS_PROMPTS } from './hyde.strategies.js';
 const logger = protocolLogger("HydeGenerator");
 const SYSTEM_PROMPT = `You are a Hypothetical Document Generator for semantic search.
 
@@ -33,35 +29,68 @@ const responseFormat = z.object({
         .string()
         .describe('The hypothetical document text in the target voice, suitable for embedding and retrieval'),
 });
-/**
- * Generates hypothetical documents in a target corpus voice for semantic search.
- * Uses free-text lens labels (from LensInferrer) instead of enum strategies.
- */
+function renderList(items) {
+    return items.length > 0 ? items.join('; ') : '(none)';
+}
+/** Build the frame-v1 generation prompt from sanitized source evidence. */
+export function buildFrameHydePrompt(input) {
+    const { sourceText, corpus, sourceFrame } = input;
+    const corpusInstruction = {
+        profiles: 'Write a first-person professional biography in the target profile voice.',
+        intents: 'Write a first-person goal or aspiration in the target intent voice.',
+        premises: 'Write a first-person stable identity, values, or worldview statement in the target premise voice.',
+    }[corpus];
+    return `${corpusInstruction}
+
+Source text: "${sourceText}"
+
+Sanitized source frame:
+- Source roles: ${renderList(sourceFrame.sourceRoles.map((item) => `${item.role} [evidence: "${item.evidence}"]`))}
+- Counterpart/complementary roles: ${renderList(sourceFrame.counterpartRoles.map((item) => `${item.role} [evidence: "${item.evidence}"]`))}
+- Explicit hard constraints: ${renderList(sourceFrame.hardConstraints.map((item) => `${item.type}: ${item.value} [evidence: "${item.evidence}"]`))}
+- Named entities: ${renderList(sourceFrame.namedEntities.map((item) => `${item.type}: ${item.name} [evidence: "${item.evidence}"]`))}
+- Domain vocabulary: ${renderList(sourceFrame.domainVocabulary.map((item) => `${item.term} [evidence: "${item.evidence}"]`))}
+
+Generation constraints:
+- You MAY elaborate generic roles and generic domain language.
+- You MAY use reciprocal/complementary inversion and write in the target voice.
+- You MUST NOT introduce any new proper noun or named entity.
+- You MUST NOT introduce any new hard location, time, numeric, credential, organization, or exclusivity constraint.
+- Preserve explicit source-frame constraints when they apply to the reciprocal target.
+- Output only a few sentences or one short paragraph.`;
+}
+/** Generates hypothetical documents in a target corpus voice for semantic search. */
 export class HydeGenerator {
-    constructor() {
-        this.model = createStructuredModel("hydeGenerator", responseFormat, {
+    constructor(model) {
+        // Preserve the legacy production model construction path; injected models
+        // keep prompt tests provider-free.
+        this.model = model ?? createStructuredModel("hydeGenerator", responseFormat, {
             name: "hyde_generator",
         });
     }
-    /**
-     * Generate a hypothetical document for the given source text and lens.
-     *
-     * @param input - Source text, lens label, and target corpus
-     * @returns Generated hypothetical document text
-     */
+    getModel() {
+        this.model ?? (this.model = createStructuredModel("hydeGenerator", responseFormat, {
+            name: "hyde_generator",
+        }));
+        return this.model;
+    }
+    /** Generate a hypothetical document for the given source text and lens. */
     async generate(input) {
-        const promptText = HYDE_CORPUS_PROMPTS[input.corpus](input.sourceText, input.lens);
+        const promptText = input.sourceFrame
+            ? buildFrameHydePrompt(input)
+            : HYDE_CORPUS_PROMPTS[input.corpus](input.sourceText, input.lens);
         const messages = [
             new SystemMessage(SYSTEM_PROMPT),
             new HumanMessage(promptText),
         ];
-        const result = await invokeWithAbortSignal(this.model, messages);
+        const result = await invokeWithAbortSignal(this.getModel(), messages);
         const parsed = responseFormat.parse(result);
         const text = parsed.hypotheticalDocument ?? '';
         logger.verbose('Generated HyDE document', {
             lens: input.lens,
             corpus: input.corpus,
             textLength: text.length,
+            frameConstrained: !!input.sourceFrame,
         });
         return { text };
     }

package/dist/shared/hyde/hyde.generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"hyde.generator.js","sourceRoot":"/","sources":["shared/hyde/hyde.generator.ts"],"names":[],"mappings":";;;;;;;;;AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,MAAM,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;AAE/C,MAAM,aAAa,GAAG;;;;;;;;yDAQmC,CAAC;AAE1D,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,oBAAoB,EAAE,CAAC;SACpB,MAAM,EAAE;SACR,QAAQ,CAAC,0FAA0F,CAAC;CACxG,CAAC,CAAC;AAeH;;;GAGG;AACH,MAAM,OAAO,aAAa;IAA1B;QACU,UAAK,GAAG,qBAAqB,CAAC,eAAe,EAAE,cAAc,EAAE;YACrE,IAAI,EAAE,gBAAgB;SACvB,CAAC,CAAC;IA6BL,CAAC;IA3BC;;;;;OAKG;IAEG,AAAN,KAAK,CAAC,QAAQ,CAAC,KAAwB;QACrC,MAAM,UAAU,GAAG,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAEnF,MAAM,QAAQ,GAAG;YACf,IAAI,aAAa,CAAC,aAAa,CAAC;YAChC,IAAI,YAAY,CAAC,UAAU,CAAC;SAC7B,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,oBAAoB,IAAI,EAAE,CAAC;QAE/C,MAAM,CAAC,OAAO,CAAC,yBAAyB,EAAE;YACxC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,UAAU,EAAE,IAAI,CAAC,MAAM;SACxB,CAAC,CAAC;QAEH,OAAO,EAAE,IAAI,EAAE,CAAC;IAClB,CAAC;CACF;AApBO;IADL,KAAK,EAAE;;;;6CAoBP","sourcesContent":["/**\n * HyDE Generator Agent: pure LLM agent for generating hypothetical documents\n * in the target corpus voice. Uses free-text lens labels instead of enum strategies.\n */\nimport { HumanMessage, SystemMessage } from '@langchain/core/messages';\nimport { z } from 'zod';\nimport { HYDE_CORPUS_PROMPTS } from './hyde.strategies.js';\nimport type { HydeTargetCorpus } from './lens.inferrer.js';\nimport { Timed } from \"../observability/performance.js\";\nimport { protocolLogger } from '../observability/protocol.logger.js';\nimport { createStructuredModel } from \"../agent/model.config.js\";\nimport { invokeWithAbortSignal } from \"../agent/model-signal.js\";\n\nconst logger = protocolLogger(\"HydeGenerator\");\n\nconst SYSTEM_PROMPT = `You are a Hypothetical Document Generator for semantic search.\n\nYour task: Given a source statement (e.g. an intent or goal), write a short hypothetical document in the voice of the TARGET side—the kind of person or statement that would be an ideal match for that source.\n\nRules:\n- Write in first person as the target.\n- Be concrete and specific so the text is good for vector similarity search.\n- Output only the hypothetical document text, no meta-commentary.\n- Keep length to a few sentences or one short paragraph.`;\n\nconst responseFormat = z.object({\n  hypotheticalDocument: z\n    .string()\n    .describe('The hypothetical document text in the target voice, suitable for embedding and retrieval'),\n});\n\nexport interface HydeGeneratorOutput {\n  text: string;\n}\n\nexport interface HydeGenerateInput {\n  /** Original intent or query text. */\n  sourceText: string;\n  /** Free-text lens label from LensInferrer (e.g. \"crypto infra VC\"). */\n  lens: string;\n  /** Which corpus voice to generate in. */\n  corpus: HydeTargetCorpus;\n}\n\n/**\n * Generates hypothetical documents in a target corpus voice for semantic search.\n * Uses free-text lens labels (from LensInferrer) instead of enum strategies.\n */\nexport class HydeGenerator {\n  private model = createStructuredModel(\"hydeGenerator\", responseFormat, {\n    name: \"hyde_generator\",\n  });\n\n  /**\n   * Generate a hypothetical document for the given source text and lens.\n   *\n   * @param input - Source text, lens label, and target corpus\n   * @returns Generated hypothetical document text\n   */\n  @Timed()\n  async generate(input: HydeGenerateInput): Promise<HydeGeneratorOutput> {\n    const promptText = HYDE_CORPUS_PROMPTS[input.corpus](input.sourceText, input.lens);\n\n    const messages = [\n      new SystemMessage(SYSTEM_PROMPT),\n      new HumanMessage(promptText),\n    ];\n\n    const result = await invokeWithAbortSignal(this.model, messages);\n    const parsed = responseFormat.parse(result);\n    const text = parsed.hypotheticalDocument ?? '';\n\n    logger.verbose('Generated HyDE document', {\n      lens: input.lens,\n      corpus: input.corpus,\n      textLength: text.length,\n    });\n\n    return { text };\n  }\n}\n"]}
+{"version":3,"file":"hyde.generator.js","sourceRoot":"/","sources":["shared/hyde/hyde.generator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * HyDE Generator Agent: pure LLM agent for generating hypothetical documents\n * in the target corpus voice. Uses free-text lens labels instead of enum strategies.\n */\nimport type { BaseLanguageModelInput } from '@langchain/core/language_models/base';\nimport { HumanMessage, SystemMessage } from '@langchain/core/messages';\nimport { z } from 'zod';\n\nimport { createStructuredModel } from \"../agent/model.config.js\";\nimport { invokeWithAbortSignal } from \"../agent/model-signal.js\";\nimport { protocolLogger } from '../observability/protocol.logger.js';\nimport { Timed } from \"../observability/performance.js\";\nimport type { HydeSourceFrame } from './hyde.frame.js';\nimport { HYDE_CORPUS_PROMPTS } from './hyde.strategies.js';\nimport type { HydeTargetCorpus } from './lens.inferrer.js';\n\nconst logger = protocolLogger(\"HydeGenerator\");\n\nconst SYSTEM_PROMPT = `You are a Hypothetical Document Generator for semantic search.\n\nYour task: Given a source statement (e.g. an intent or goal), write a short hypothetical document in the voice of the TARGET side—the kind of person or statement that would be an ideal match for that source.\n\nRules:\n- Write in first person as the target.\n- Be concrete and specific so the text is good for vector similarity search.\n- Output only the hypothetical document text, no meta-commentary.\n- Keep length to a few sentences or one short paragraph.`;\n\nconst responseFormat = z.object({\n  hypotheticalDocument: z\n    .string()\n    .describe('The hypothetical document text in the target voice, suitable for embedding and retrieval'),\n});\n\nexport interface HydeGeneratorOutput {\n  text: string;\n}\n\nexport interface HydeGenerateInput {\n  /** Original intent or query text. */\n  sourceText: string;\n  /** Free-text lens label from LensInferrer (e.g. \"crypto infra VC\"). */\n  lens: string;\n  /** Which corpus voice to generate in. */\n  corpus: HydeTargetCorpus;\n  /** Sanitized source-grounded frame. Absence preserves the exact legacy prompt. */\n  sourceFrame?: HydeSourceFrame;\n}\n\n/** Minimal structured model contract used for deterministic injection in tests. */\nexport interface HydeGeneratorStructuredModel {\n  invoke(input: BaseLanguageModelInput, config?: { signal?: AbortSignal }): Promise<unknown>;\n}\n\nfunction renderList(items: string[]): string {\n  return items.length > 0 ? items.join('; ') : '(none)';\n}\n\n/** Build the frame-v1 generation prompt from sanitized source evidence. */\nexport function buildFrameHydePrompt(input: HydeGenerateInput & { sourceFrame: HydeSourceFrame }): string {\n  const { sourceText, corpus, sourceFrame } = input;\n  const corpusInstruction = {\n    profiles: 'Write a first-person professional biography in the target profile voice.',\n    intents: 'Write a first-person goal or aspiration in the target intent voice.',\n    premises: 'Write a first-person stable identity, values, or worldview statement in the target premise voice.',\n  }[corpus];\n\n  return `${corpusInstruction}\n\nSource text: \"${sourceText}\"\n\nSanitized source frame:\n- Source roles: ${renderList(sourceFrame.sourceRoles.map((item) => `${item.role} [evidence: \"${item.evidence}\"]`))}\n- Counterpart/complementary roles: ${renderList(sourceFrame.counterpartRoles.map((item) => `${item.role} [evidence: \"${item.evidence}\"]`))}\n- Explicit hard constraints: ${renderList(sourceFrame.hardConstraints.map((item) => `${item.type}: ${item.value} [evidence: \"${item.evidence}\"]`))}\n- Named entities: ${renderList(sourceFrame.namedEntities.map((item) => `${item.type}: ${item.name} [evidence: \"${item.evidence}\"]`))}\n- Domain vocabulary: ${renderList(sourceFrame.domainVocabulary.map((item) => `${item.term} [evidence: \"${item.evidence}\"]`))}\n\nGeneration constraints:\n- You MAY elaborate generic roles and generic domain language.\n- You MAY use reciprocal/complementary inversion and write in the target voice.\n- You MUST NOT introduce any new proper noun or named entity.\n- You MUST NOT introduce any new hard location, time, numeric, credential, organization, or exclusivity constraint.\n- Preserve explicit source-frame constraints when they apply to the reciprocal target.\n- Output only a few sentences or one short paragraph.`;\n}\n\n/** Generates hypothetical documents in a target corpus voice for semantic search. */\nexport class HydeGenerator {\n  private model?: HydeGeneratorStructuredModel;\n\n  constructor(model?: HydeGeneratorStructuredModel) {\n    // Preserve the legacy production model construction path; injected models\n    // keep prompt tests provider-free.\n    this.model = model ?? createStructuredModel(\"hydeGenerator\", responseFormat, {\n      name: \"hyde_generator\",\n    });\n  }\n\n  private getModel(): HydeGeneratorStructuredModel {\n    this.model ??= createStructuredModel(\"hydeGenerator\", responseFormat, {\n      name: \"hyde_generator\",\n    });\n    return this.model;\n  }\n\n  /** Generate a hypothetical document for the given source text and lens. */\n  @Timed()\n  async generate(input: HydeGenerateInput): Promise<HydeGeneratorOutput> {\n    const promptText = input.sourceFrame\n      ? buildFrameHydePrompt(input as HydeGenerateInput & { sourceFrame: HydeSourceFrame })\n      : HYDE_CORPUS_PROMPTS[input.corpus](input.sourceText, input.lens);\n\n    const messages = [\n      new SystemMessage(SYSTEM_PROMPT),\n      new HumanMessage(promptText),\n    ];\n\n    const result = await invokeWithAbortSignal(this.getModel(), messages);\n    const parsed = responseFormat.parse(result);\n    const text = parsed.hypotheticalDocument ?? '';\n\n    logger.verbose('Generated HyDE document', {\n      lens: input.lens,\n      corpus: input.corpus,\n      textLength: text.length,\n      frameConstrained: !!input.sourceFrame,\n    });\n\n    return { text };\n  }\n}\n"]}

package/dist/shared/hyde/hyde.graph.d.ts

@@ -1,27 +1,39 @@
-/**
- * HyDE Graph: cache-aware hypothetical document generation with lens inference.
- *
- * Flow: infer_lenses → check_cache → (generate_missing if needed) → embed → cache_results.
- * Constructor injects Database, Embedder, Cache, LensInferrer, HydeGenerator.
- */
-import { type HydeDocumentState } from './hyde.state.js';
-import { LensInferrer } from './lens.inferrer.js';
-import { HydeGenerator } from './hyde.generator.js';
+import type { DebugMetaAgent } from '../../chat/chat-streaming.types.js';
+import type { HydeCache } from '../interfaces/cache.interface.js';
 import type { HydeGraphDatabase } from '../interfaces/database.interface.js';
 import type { EmbeddingGenerator } from '../interfaces/embedder.interface.js';
-import type { HydeCache } from '../interfaces/cache.interface.js';
-import type { DebugMetaAgent } from '../../chat/chat-streaming.types.js';
-/**
- * Factory for the HyDE generation graph.
- * Injects Database, Embedder, Cache, LensInferrer, and HydeGenerator.
- */
+import { type HydeGenerationMode } from './hyde.env.js';
+import { type HydeSourceFrame } from './hyde.frame.js';
+import type { HydeGenerateInput, HydeGeneratorOutput } from './hyde.generator.js';
+import { type HydeDocumentState } from './hyde.state.js';
+import type { LensInferenceInput, LensInferenceOutput } from './lens.inferrer.js';
+import { type HydeValidationInput, type HydeValidationOutput } from './hyde.validator.js';
+/** Narrow lens inferrer contract accepted by the graph. */
+export interface HydeLensInferrerLike {
+    infer(input: LensInferenceInput): Promise<LensInferenceOutput>;
+}
+/** Narrow document generator contract accepted by the graph. */
+export interface HydeGeneratorLike {
+    generate(input: HydeGenerateInput): Promise<HydeGeneratorOutput>;
+}
+/** Narrow batch validator contract accepted by the graph. */
+export interface HydeValidatorLike {
+    validate(input: HydeValidationInput): Promise<HydeValidationOutput>;
+}
+export interface HydeGraphOptions {
+    /** Test override. Production derives the mode from HYDE_FRAME_CONSTRAINTS_ENABLED. */
+    mode?: HydeGenerationMode;
+    validator?: HydeValidatorLike;
+}
+/** Factory for the HyDE generation graph. Existing five-argument calls remain valid. */
 export declare class HydeGraphFactory {
     private database;
     private embedder;
     private cache;
     private inferrer;
     private generator;
-    constructor(database: HydeGraphDatabase, embedder: EmbeddingGenerator, cache: HydeCache, inferrer: LensInferrer, generator: HydeGenerator);
+    private options;
+    constructor(database: HydeGraphDatabase, embedder: EmbeddingGenerator, cache: HydeCache, inferrer: HydeLensInferrerLike, generator: HydeGeneratorLike, options?: HydeGraphOptions);
     createGraph(): import("@langchain/langgraph").CompiledStateGraph<{
         sourceType: "intent" | "context" | "query";
         sourceId: import("../interfaces/database.interface.js").Id<"users"> | import("../interfaces/database.interface.js").Id<"intents"> | undefined;
@@ -30,6 +42,10 @@ export declare class HydeGraphFactory {
         maxLenses: number;
         forceRegenerate: boolean;
         lenses: import("./lens.inferrer.js").Lens[];
+        sourceFrame: HydeSourceFrame | undefined;
+        frameFingerprint: string | undefined;
+        sourceTextHash: string | undefined;
+        generatedAt: string | undefined;
         hydeDocuments: Record<string, HydeDocumentState>;
         hydeEmbeddings: Record<string, number[]>;
         error: string | undefined;
@@ -42,6 +58,10 @@ export declare class HydeGraphFactory {
         maxLenses?: number | import("@langchain/langgraph").OverwriteValue<number> | undefined;
         forceRegenerate?: boolean | import("@langchain/langgraph").OverwriteValue<boolean> | undefined;
         lenses?: import("./lens.inferrer.js").Lens[] | import("@langchain/langgraph").OverwriteValue<import("./lens.inferrer.js").Lens[]> | undefined;
+        sourceFrame?: HydeSourceFrame | import("@langchain/langgraph").OverwriteValue<HydeSourceFrame | undefined> | undefined;
+        frameFingerprint?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
+        sourceTextHash?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
+        generatedAt?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
         hydeDocuments?: Record<string, HydeDocumentState> | import("@langchain/langgraph").OverwriteValue<Record<string, HydeDocumentState>> | undefined;
         hydeEmbeddings?: Record<string, number[]> | import("@langchain/langgraph").OverwriteValue<Record<string, number[]>> | undefined;
         error?: string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined;
@@ -62,6 +82,10 @@ export declare class HydeGraphFactory {
         maxLenses: import("@langchain/langgraph").BaseChannel<number, number | import("@langchain/langgraph").OverwriteValue<number>, unknown>;
         forceRegenerate: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
         lenses: import("@langchain/langgraph").BaseChannel<import("./lens.inferrer.js").Lens[], import("./lens.inferrer.js").Lens[] | import("@langchain/langgraph").OverwriteValue<import("./lens.inferrer.js").Lens[]>, unknown>;
+        sourceFrame: import("@langchain/langgraph").BaseChannel<HydeSourceFrame | undefined, HydeSourceFrame | import("@langchain/langgraph").OverwriteValue<HydeSourceFrame | undefined> | undefined, unknown>;
+        frameFingerprint: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        sourceTextHash: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        generatedAt: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
         hydeDocuments: import("@langchain/langgraph").BaseChannel<Record<string, HydeDocumentState>, Record<string, HydeDocumentState> | import("@langchain/langgraph").OverwriteValue<Record<string, HydeDocumentState>>, unknown>;
         hydeEmbeddings: import("@langchain/langgraph").BaseChannel<Record<string, number[]>, Record<string, number[]> | import("@langchain/langgraph").OverwriteValue<Record<string, number[]>>, unknown>;
         error: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
@@ -82,17 +106,34 @@ export declare class HydeGraphFactory {
         maxLenses: import("@langchain/langgraph").BaseChannel<number, number | import("@langchain/langgraph").OverwriteValue<number>, unknown>;
         forceRegenerate: import("@langchain/langgraph").BaseChannel<boolean, boolean | import("@langchain/langgraph").OverwriteValue<boolean>, unknown>;
         lenses: import("@langchain/langgraph").BaseChannel<import("./lens.inferrer.js").Lens[], import("./lens.inferrer.js").Lens[] | import("@langchain/langgraph").OverwriteValue<import("./lens.inferrer.js").Lens[]>, unknown>;
+        sourceFrame: import("@langchain/langgraph").BaseChannel<HydeSourceFrame | undefined, HydeSourceFrame | import("@langchain/langgraph").OverwriteValue<HydeSourceFrame | undefined> | undefined, unknown>;
+        frameFingerprint: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        sourceTextHash: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
+        generatedAt: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
         hydeDocuments: import("@langchain/langgraph").BaseChannel<Record<string, HydeDocumentState>, Record<string, HydeDocumentState> | import("@langchain/langgraph").OverwriteValue<Record<string, HydeDocumentState>>, unknown>;
         hydeEmbeddings: import("@langchain/langgraph").BaseChannel<Record<string, number[]>, Record<string, number[]> | import("@langchain/langgraph").OverwriteValue<Record<string, number[]>>, unknown>;
         error: import("@langchain/langgraph").BaseChannel<string | undefined, string | import("@langchain/langgraph").OverwriteValue<string | undefined> | undefined, unknown>;
         agentTimings: import("@langchain/langgraph").BaseChannel<DebugMetaAgent[], DebugMetaAgent[] | import("@langchain/langgraph").OverwriteValue<DebugMetaAgent[]>, unknown>;
     }, import("@langchain/langgraph").StateDefinition, {
         infer_lenses: {
+            lenses: import("./lens.inferrer.js").Lens[];
+            sourceFrame: HydeSourceFrame;
+            frameFingerprint: string;
+            sourceTextHash: string;
+            generatedAt: string;
+            agentTimings: DebugMetaAgent[];
+        } | {
             lenses: import("./lens.inferrer.js").Lens[];
             agentTimings: DebugMetaAgent[];
+            sourceFrame?: undefined;
+            frameFingerprint?: undefined;
+            sourceTextHash?: undefined;
+            generatedAt?: undefined;
         };
         check_cache: {
-            hydeDocuments: Record<string, HydeDocumentState>;
+            hydeDocuments: {
+                [k: string]: HydeDocumentState;
+            };
         };
         generate_missing: {
             hydeDocuments: {

package/dist/shared/hyde/hyde.graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hyde.graph.d.ts","sourceRoot":"/","sources":["shared/hyde/hyde.graph.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAKlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAyBzE;;;GAGG;AACH,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;gBAJT,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,aAAa;IAGlC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqOZ"}
+{"version":3,"file":"hyde.graph.d.ts","sourceRoot":"/","sources":["shared/hyde/hyde.graph.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAK9E,OAAO,EAAwD,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC9G,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAElF,OAAO,EAAiB,KAAK,mBAAmB,EAAE,KAAK,oBAAoB,EAA8B,MAAM,qBAAqB,CAAC;AAUrI,2DAA2D;AAC3D,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChE;AAED,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAClE;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAsID,wFAAwF;AACxF,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,OAAO;gBALP,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE,gBAAqB;IAGxC,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiZZ"}