fix(assistant): типизирани AI/Vectorize биндинги — без 'as unknown as' на route границата

[nedda76]

Closes #316

Какво

Двойните assertions (env.AI as unknown as EmbeddingRunner, env.VECTORIZE as unknown as VectorIndex) в routes/assistant.chat.tsx изчезват:

• VECTORIZE се присвоява директно: VectorRecord.metadata е стеснен до стойностите, които Vectorize приема (VectorMetadataValue), а неизползваемият метадата filter член отпадна от интерфейса. Присвояването е компилационното доказателство — дрейф между rag.ts и worker-configuration.d.ts чупи tsc, не продукцията. Негативен контрол: връщането на стария filter?: Record<string, unknown> член дава TS2322 точно на присвояването.
• AI не може да удовлетвори EmbeddingRunner структурно (Ai.run() е generic per-model и връща output UNION), затова минава през единствения санкциониран мост — embeddingRunnerFor() в новия bindings.ts, който вика реалния @cf/baai/bge-m3 overload, също проверен от компилатора.

Кастовете към AgentEnv остават: BGGPT_API_KEY е secret и не присъства в генерирания Env — отделен въпрос.

От ревюто (второ комитче)

• EmbeddingRunner.run взима model: typeof EMBED_MODEL (литерала) и адаптерът го препраща — втори, различен модел би бил компилационна грешка, не тихо embed-ване с грешния модел.
• Адаптерът е изнесен в bindings.ts и unit тестван (вкл. не-embedding форми на отговора).
• При неочаквана форма адаптерът хвърля именувана грешка (само ключовете, без payload) вместо да връща [], което се четеше като „провайдърът не embed-на нищо".
• README provisioning gate-ът вика indexSchemaCorpus през embeddingRunnerFor — голият env.AI там вече не typecheck-ва.

Стак

Стъпва върху #319 (→ #223). За ревю са последните 2 комита (eb05524, 78d36fb). Ред на мърдж: #223 → #319 → този PR.

Проверено

tsc -b чист (вкл. негативния контрол по-горе), 185/185 теста на assistant пакета, Prettier чист.

[ydimitrof]

Обобщение на ревюто

Фаза 0 — Security-Critical Scan: CLEAN. Няма хардкоднати тайни (BGGPT_API_KEY се подава през wrangler secret put, никога не се комитва). Няма нови URL-и извън whitelist. Няма backdoor/обфускация/code injection. Промяната в osv-scanner.toml е suppression, но е добре обоснована (sharp е транзитивна, само-dev зависимост през miniflare, не влиза в деплойнатия Worker; има ignoreUntil и ясно условие за премахване). Нови зависимости не се добавят. → Продължавам към същинското ревю.

Оценка по измерения

Сигурност (агентско ниво) — отлично. Ядрото на PR-а всъщност повишава сигурността:

• Премахва as unknown as на граница route↔RAG (#316) — типов контракт, който tsc проверява, вместо сляп каст.
• sql-guard.ts разширява denylist-а с string-building агрегати (group_concat/string_agg/json_group_array/json_group_object) — реален клас memory-amplification (OOM на изолата преди capRows). Правилно уловен и string_agg синонимът за модерен SQLite на D1.
• emit-report-schema.ts: горни граници за масиви (MAX_BLOCKS/ITEMS/COLUMNS) + short-circuit преди сканиране на oversize структура; align whitelist (left|right) спира out-of-enum стойност да достигне рендерер, който я интерполира в атрибут.
• report-schema.ts: експлицитно изграждане на колоните (без spread) спира пренасяне на непроверени model-supplied ключове към рендерера — добра defense-in-depth.
• Диагностиките са „keys-only" (не логват съдържанието на ембеднатия вход) — правилно за да не изтича потребителски текст.

Архитектура — отлично. bindings.ts е единственият модул, който знае и двете страни на границата; структурните типове в rag.ts остават deploy-независими и unit-тестируеми. Разделянето hardTraps() (безусловно) vs. RAG-извлечени chunk-ове поправя реален дефект: RAG-ход, който е бил по-слабо ограничен от no-RAG fallback-а (пропускал е SUM(amount)). renderTraps() премахва дублирането между describeSchema() и hard-traps пътя.

Производителност — без регресии. Native namespace вместо metadata filter (не изисква provisioned metadata index, изключва stale кохорти преди topK). Relevance floor (MIN_SCHEMA_SCORE) предотвратява инжектиране на off-topic chunk-ове вместо пълния речник. Версионираните namespace-и позволяват rollback на Worker-а без счупване на RAG.

Тестове — много силни. Добавени/разширени тестове покриват: adapter forward + два error-shape случая, versioned namespace/ids, relevance floor (вкл. scoreless-match defensive пътища), cap short-circuit, align whitelist, exactly-once рендиране на trap-овете през реалния write→read seam, суфиксното matching на магнитуди, новите SQL агрегати. Тестовете са смислени (не тривиални), проверяват границите и regression пътищата.

Документация — отлично. README е обстойно обновен: ре-индексиране, „WHEN TO BUMP" правило, разграничение схема-корпус (append-only) vs. entity-корпус (data-derived, нужен reconciliation/delete път).

CLAUDE.md съответствие

Няма частична имплементация, TODO-симплификации, дублиран или мъртъв код. Именуването е консистентно. Разделянето на отговорности е чисто. Няма resource leaks.

Незначителни наблюдения (не блокиращи — виж inline)

1. sql-guard.ts: denylist-ът fail-closed отхвърля и стрингови литерали, съдържащи имената на функциите (напр. WHERE name = 'group_concat(x)'). Това е предсъществуващо поведение (printf/format), безопасната посока е, и коментарът вече насочва към positive allowlist като трайно решение.
2. report-schema.ts: суфиксният подход не покрива съкращенията млрд./млн. без придружаваща валутна дума или 5-цифрено число — потенциален (маргинален) false-negative.

Препоръка: Няма блокиращи проблеми. Кодът е за мърдж след потвърждаване на пълния тестов пакет и coverage в CI (не можах да ги изпълня в тази среда) и предварителното осигуряване на Cloudflare ресурсите (Vectorize sigma-assistant 1024/cosine, R2 sigma-reports, BGGPT_API_KEY, ре-индекс на схема-корпуса) преди deploy, както е описано в README.

[ydimitrof]

Ревю на PR: типизирани AI/Vectorize биндинги (без as unknown as)

Обобщение

Много силен, добре обоснован PR. Основната цел — премахване на as unknown as на границата на route-а (assistant.chat.tsx) и въвеждане на един-единствен санкциониран мост (bindings.ts → embeddingRunnerFor) — е постигната чисто и е покрита с прицелни тестове. Съпътстващите промени (versioned native namespaces в Vectorize, relevance floor при retrieval, capове на масивите в emit_report, разширяване на SQL denylist-а и prose-number gate-а) са последователни, добре документирани и всяка носи регресионен тест. Разделението на отговорностите е спазено: bindings.ts е единственият модул, който познава двете страни на типовете.

Фаза 0 — Security-critical scan: CLEAN

• Hardcoded secrets: няма. BGGPT_API_KEY минава през wrangler secret put, никога не се комитва; документацията изрично го подчертава.
• URL промени: няма нови външни URL-и. Единствените нови идентификатори са модел-литерал (@cf/baai/bge-m3) и имена на Cloudflare ресурси (sigma-assistant, sigma-reports).
• Malicious patterns: няма backdoor/обфускация/eval.
• Зависимости: osv-scanner.toml добавя ignore само за sharp (транзитивна, dev-only през miniflare) с ясна обосновка и ignoreUntil. Приемливо.
• Логове: адаптерът съзнателно логва само ключове (KEYS ONLY), за да не изтича потребителски текст — добра практика.

Силни страни

• Типова безопасност на route границата: env.VECTORIZE се присвоява без каст (compile-time доказателство за структурна съвместимост), а env.AI минава през embeddingRunnerFor, който извиква реалния per-model overload. Точно това, което issue #316 иска.
• Sanitizing на emit_report: експлицитното изграждане на колоните (без spread) спира пренасянето на непознати model-подадени полета към renderer-а — реално подобрение на сигурността срещу injection в атрибути/стил, подсилено от isAlign whitelist-а.
• SQL guard: добавянето на string-building агрегатите (group_concat/string_agg/json_group_*) затваря реален memory-amplification вектор; коментарът честно признава, че denylist-ът е catch-up игра и allowlist е трайният фикс.
• Prose-number gate: преминаването от явен списък към суфиксите -илион/-илиард затваря реда нагоре (квинтилион/секстилион) — добро решение, съзнателно приема over-flagging в правилната посока.
• RAG namespaces + relevance floor: native namespace вместо metadata filter (който изисква непровизиран metadata index) и floor-ът срещу off-topic topK са коректни; fallback-ът към пълния статичен речник е безопасният изход.

Забележки (ниска тежест)

Виж inline коментарите. Няма блокиращи проблеми.

Проверимост

Тестовете и typecheck-ът не са изпълнени в тази среда (няма достъп до repo build/CI). Финалната препоръка е при условие за зелен CI: pnpm --filter web typecheck → 0 и целият тестов пакет минава, съгласно README.

Съответствие с CLAUDE.md

• NO PARTIAL IMPLEMENTATION / TODO: спазено — недовършените части (entity indexer, eop_fetch само брой) са ясно документирани като „Какво остава", не са скрити TODO-та.
• NO CODE DUPLICATION: renderTraps() е извлечен и споделен между describeSchema и hardTraps, точно за да не дрейфа.
• COMPREHENSIVE / NO CHEATER TESTS: тестовете са смислени (проверяват форма на namespace, floor поведение, cap short-circuit, exactly-once на trap-овете през реалния write→read seam).
• CONSISTENT NAMING / SEPARATION OF CONCERNS: спазено.

Препоръка

APPROVE (при зелен CI). Качество: ~9.4/10.

[ydimitrof]

Ревю на PR: типизирани AI/Vectorize биндинги (без as unknown as)

Фаза 0 — Сигурност (сканиране): ЧИСТО (с една бележка)

• Няма hardcoded тайни. BGGPT_API_KEY се подава през wrangler secret put и изрично не се комитва — коректно.
• Няма нови/променени URL адреси, няма backdoor/обфускация/code-injection модели.
• Промяна по зависимости — само подтискане в osv-scanner.toml: добавени са игнори за sharp 0.34.5 (libvips CVE-та). Обосновката е валидна (транзитивна, само-dev зависимост през miniflare, не влиза в деплойнатия Worker, няма in-range upstream фикс) и има ignoreUntil дата за ре-визия. Приемливо, но флагвам за проследяване — това остава подтисната уязвимост до 2026-10-22.

Обща оценка

Много силен, добре обоснован PR. Основната цел — премахване на as unknown as на границата на route-а — е постигната чисто:

• env.VECTORIZE вече се присвоява структурно към VectorIndex (compile-time доказателство), а env.AI минава през единствения санкциониран мост embeddingRunnerFor(), който форва̀рдва EMBED_MODEL литерала през реалния @cf/baai/bge-m3 overload.
• Адаптерът в bindings.ts не губи диагностиката, която сляп каст губеше (именувана грешка по форма, keys-only — без изтичане на потребителски текст в логовете). Отлично.

Тестове (силна страна)

• Новите bindings.test.ts пинват поведението на адаптера (форуард, невалидна форма, липсващи ключове, празен data масив за непразен вход).
• rag.test.ts покрива версионирания native namespace (schema-v2/entity-v1), релевантния праг, scoreless match-овете и отсъствието на metadata filter.
• Композиционният тест в system-prompt.test.ts минава през реалния write→read seam (indexSchemaCorpus → retrieveSchemaContext → buildSystemPrompt) и гарантира, че всеки trap се рендира точно веднъж — това хваща регресията с двойния рендер.
• sql-guard.test.ts покрива quoted-identifier bypass и string-building агрегатите.

Архитектура / CLAUDE.md

• renderTraps() премахва дублирането между describeSchema() и hardTraps() — DRY спазено.
• Разделянето на контрактите (VectorIndex е assignable от VectorizeIndex; EmbeddingRunner — не) е ясно документирано.
• hardTraps() инжектира императивните капани безусловно — RAG вече само добавя релевантни таблици/заявки, така че RAG-ход никога не е по-слабо ограничен от fallback-а. Коректна поправка на реален дефект.

Точки за внимание (не блокиращи)

1. Ред на деплой (операционен риск, документиран): PR добавя изисквания за bindings — Vectorize индекс sigma-assistant (1024/cosine), R2 sigma-reports, secret BGGPT_API_KEY. Ако деплой стане преди тяхното създаване, wrangler deploy пада и блокира CD на целия екип. Документирано подробно в README; уверете се, че CD-то го прилага преди мърдж.
2. Namespace миграция: заявките сега сочат schema-v2/entity-v1. Среда без ре-индекс връща 0 чънка и пада към пълния статичен речник — безопасно, но без RAG grounding, докато indexSchemaCorpus не се пусне отново. Проследете ре-индекса като част от deploy runbook-а.
3. Малка бележка по semanticSearch (вж. inline).

Заключение

Няма блокиращи проблеми по код или сигурност. Не давам автоматичен APPROVE, защото agent loop-ът и route-ът остават runtime-непроверени (няма BGGPT_API_KEY/облачни bindings в средата — признато в README), а деплой-редът е външно условие. Verdict: COMMENT — след потвърден ре-индекс и осигурени bindings PR-ът е готов за мърдж.

[ydimitrof]

Обобщение

Много добре изпипан PR. Основната цел — премахване на as unknown as на границата route→lib и въвеждане на типизирани биндинги (issue #316) — е постигната чисто: VectorIndex е структурно съвместим с VectorizeIndex (присвояването в assistant.chat.tsx е compile-time доказателството), а Ai минава през единствения санкциониран мост embeddingRunnerFor. Тестовото покритие е образцово (адаптер, relevance floor, cap-ове, quoted-identifier bypass).

Прегледах и за враждебен код: няма exfiltration, нови мрежови повиквания, обфускирани payload-и или промени по auth/workflow файлове. osv-scanner.toml игнорите за sharp са обосновани (transitive, dev-only чрез miniflare, извън деплойнатия Worker) и с ignoreUntil дата. Няма prompt-injection в дифа.

Отбелязвам няколко забележки, всичките незадължителни — нищо блокиращо.

Забележки (незадължителни)

1. rag.ts — асиметрия между retrieveSchemaContext и semanticSearch за scoreless match. retrieveSchemaContext използва (m.score ?? 0) >= minScore, докато semanticSearch съзнателно ползва Number.isFinite(m.score) && m.score >= minScore, точно за да не пропусне безскоров match при minScore = 0. minScore е публичен параметър по подразбиране MIN_SCHEMA_SCORE; ако бъдещ викащ подаде 0 (както прави entity-тестът), схема-пътят ще пропусне безскоров запис през пода 0 (0 >= 0), а entity-пътят — не. За консистентност и да не се появи този клас грешка по-късно, изравнете schema-филтъра към Number.isFinite(m.score) && m.score >= minScore.

2. sql-guard.ts — denylist срещу нови алиаси е догонваща игра (както сами отбелязвате в коментара). Класът покрива quoted-identifier bypass-а и aggregate string-builder-ите добре, но позитивен allowlist на функции остава по-устойчивото решение; добре е, че е проследен отделно. Няма нужда от промяна тук.

3. bindings.ts — предположението „embed() никога не вика адаптера с празен вход" е коректно за текущите три викащи (retrieveSchemaContext/semanticSearch/indexSchemaCorpus подават непразни масиви), но е негласен контракт. Ако някой добави нов път, който подаде празни texts, съобщението „празен data масив за непразен вход" ще подведе. Струва си кратък guard или коментар в самия embed.

Одобрявам — промените са коректни, добре тествани и подобряват сигурността на retrieval границата.

[nedda76]

Благодаря за прегледа — по трите незадължителни бележки:

1. Асиметрията ?? 0 / Number.isFinite в rag.ts — изравнена още в fix(assistant): semantic_search през native Vectorize namespace вместо metadata филтър #319 (4bb6004, в основата на този клон): схема пътят е Number.isFinite(m.score) && m.score >= minScore, с тест за minScore = 0 (истинска нула остава hit, scoreless отпада).
2. Денилистът като догонваща игра — съгласна. Междувременно в fix(assistant): integrity, grounding & guard fixes from the PR #79 review #223 денилистът стана една дефиниция, приложена и на AST ниво върху резолвнатото име на извикването, така че лексикален трик не може да го заобиколи (детайли в коментара там). Allowlist-ът (run_sql: durable memory-amplification защита (allowlist на функции + cell-size cap преди capRows) #227) остава трайното решение.
3. Негласният контракт „embed() никога не вика адаптера с празен вход" — записан на самото място, което го гарантира (89ea450): ранното връщане при texts.length === 0 в embed() вече носи коментар, че то Е контрактът на адаптера за ВСЕКИ извикващ (не само днешните три) и не бива да се мести под run(). Тестът в rag.test.ts вече заковаваше, че моделът не се вика за [] — guard имаше, липсваше изричното назоваване.

Клонът е пребазиран върху обновените #223/#319.

[nedda76]

Пребазирано върху текущия main (8529c12); собствената делта на PR-а е непроменена.

[lyubomir-bozhinov]

Прегледах собствената делта на #320 (4 комита над #319, при HEAD 55c0b1f4) — типизирани AI/Vectorize биндинги (#316).

Чисто (потвърдено):

• Типовете отговарят на runtime shape-а — няма as unknown as лъжа. Vectorize четенията (.matches, m.score, m.metadata) са валидни (VectorizeMatch.score е required); AI адаптерът (bindings.ts:26-35) гардва реалната bge-m3 форма: if ('data' in out && Array.isArray(out.data) && out.data.length > 0) иначе throw с диагностична форма („празен data масив за непразен вход") — типът НЕ обещава фалшиво data (optional е в runtime union-а). Останалите env as unknown as са само за BGGPT_API_KEY (secret извън generated Env), извън обхвата на #316.
• Empty-data throw-ът е коректен И хванат навсякъде: embed() early-return [] при празен вход; реален provider empty-batch → throw, хванат в retrieveSchemaContext try/catch (assistant.chat.tsx:119-122 → fallback към статичния речник) и в semanticSearch try/catch (tools.ts) → friendly message. Няма нов crash surface.
• #319 гаранциите — непокътнати след type-рефактора: и двата query-та с hardcoded namespace (SCHEMA_NS/ENTITY_NS, rag.ts:142/176/234), floor-ът Number.isFinite(m.score) && m.score >= minScore симетричен (:187/241).
• Тестовете (bindings.test.ts) са поведенчески: passthrough, keys-only named error, „празен data масив" rejection — мапнати към реални bge-m3 union членове.

Merge-ред: стек #223→#319→#320. Нямам блокери по собствената делта.