Data Layer (Symbols)

function searchSymbols(query: string, category?: string, page = 1, limit = 20): SearchResult;
function getSymbolById(id: string): Symbol | undefined;          // id = "Library:Name"
function getLibraryByName(name: string): LibraryDetail | undefined;
function getAllLibraries(category?: string): Library[];
function getStats(): { totalSymbols: number; totalLibraries: number; totalContributors: number };
function getCategoryStats(): { id: string; count: number }[];

// catalog
searchSymbols(query, { category?, page?, limit? }): Promise<SearchResult>;
searchSymbolsSemantic(query, limit?): Promise<{ results, total, source } | null>;
fetchSymbolById(id): Promise<Symbol | null>;
fetchLibraries({ category?, page?, limit? }): Promise<{ libraries, total }>;
fetchLibrary(name): Promise<LibraryDetail | null>;
downloadLibrary(name): Promise<Blob>;
// generation / persistence (auth)
generateSymbol(description, { datasheet_url?, additional_instructions? }): Promise<{ data: GenerateSymbolResult; status }>;
saveGeneratedComponent(payload: SaveComponentPayload): Promise<SaveResult>;
// contribution (auth)
validateSymbol(file): Promise<ValidationResult>;
submitContribution(data: ContributionData): Promise<SubmissionResponse>;
// user
fetchUserProfile(): Promise<UserProfile | null>;

interface SearchResult { symbols: Symbol[]; total: number; page: number; limit: number; totalPages: number; }
interface Library { id: string; name: string; description: string; category: string;
  symbolCount: number; lastUpdated: string; contributor: string; source?: string; }
interface LibraryDetail extends Library { symbols: Symbol[]; }