🧪 feat: Add Scoped Bun RAG v2 PoC

[lia-by-librechat]

Scope

Isolated Bun 1.4.2/Hono RAG v2 PoC. No RAG v1, LibreChat UI, or extraction-service changes. No LangChain.

• Tenant/namespace/resource grants in short-lived asymmetric service JWTs, with server-stamped actor and source provenance. LibreChat remains the users/groups/roles/ACL authority.
• Immutable ClickHouse chunks, complete versioned document rows, staged generations and one publication pointer. Failed replacements preserve the prior searchable generation. Acknowledged batch inserts, retry tokens, durable idempotency receipts, and restart-safe version floors.
• Scoped semantic and BM25/RRF retrieval, exact search by default and explicit capability-checked quantized-code shortlist/rescore, batched original-file metadata, and ordered page/UTF-16 source positions.
• Pluggable embedding interface, OpenAI-compatible adapter, bounded batching/admission and query single-flight. Deterministic embeddings require explicit test opt-in.
• Optional versioned Unix-socket extraction adapter. Original files remain in application storage; results carry revision/hash references, not download credentials.

caller → signed namespace grants → Hono → bounded ingest/search → ClickHouse

Run / constraints

bun install --frozen-lockfile --ignore-scripts; bun run migrate; bun run start in v2.

The Compose recipe takes RAG_V2_JWKS_JSON, RAG_V2_CLICKHOUSE_PASSWORD, and RAG_V2_EMBEDDING_API_KEY. It runs one coordinator. API mode is read-only and is the default; coordinator mode requires explicit single-writer acknowledgment. Distributed writer fencing, physical reclamation/erasure, dynamic ACL resolution, and the LibreChat token issuer/viewer integration are outside this initial PoC. Public verification keys load at startup; rotate through overlapping keys and rolling restart.

The synthetic benchmark compares Loom-shaped SQL over identical data, not a running Loom deployment. Production performance parity and cross-replica qualification remain gates, not claims.

Verification

Focused Bun tests, TypeScript no-emit check, build, formatting, and disposable ClickHouse 26.8 integration tests. The shipped non-root, read-only image also passes real HTTP auth, ingestion, search, context, deletion and stale-edit checks. Ingestion admits at most 10,000 chunks; context fails explicitly instead of truncating. Provider prefixes are byte-budgeted without changing source text. The real query plan retains the quantized shortlist/rescore with the publication filter. bun run test:container qualifies both plain and coded storage. RAG_V2_RUN_BENCH=true bun run test:container also runs the synthetic benchmark.

[lia-by-librechat]

Head: c3ce95f. Isolated Bun/Hono PoC with signed tenant/namespace/resource grants, server-stamped provenance, safe ClickHouse generation publication, pluggable embeddings/extraction, and original-file revision references. Exact retrieval is the default; quantized shortlist search is explicit opt-in. RAG v1 and LibreChat are unchanged.

[lia-by-librechat]

Verified c3ce95f: 28 focused tests, both real ClickHouse 26.8 storage modes, TypeScript, build, formatting, and the non-root deployment image passed. Synthetic warm-cache test: 10,000 vectors, 1,536 dimensions, database limited to 2 CPUs. Candidate-query p50: Loom-shaped SQL 32.19 ms, publication-filter SQL 33.44 ms. Authenticated HTTP p50: exact 45.97 ms, quantized 39.01 ms. Recall@10 against exact: exact 1.0, quantized 0.6 on this noisy synthetic corpus. Exact is the default; approximate search is explicit opt-in. This is not a running-Loom comparison, mixed-load benchmark, or Cloud cross-replica qualification.

[lia-by-librechat]

Head: 5830459. Fixed the three P2 findings from independent review of c3ce95f: conditional writes require a live publication; ingestion and context share a 10,000-chunk ceiling with explicit completeness checks; provider input budgets include Unicode-safe title/section prefixes without changing stored source text. Focused tests, no-emit typecheck, build and formatting passed. Real ClickHouse qualification is running for this head.

[lia-by-librechat]

Verified 5830459: 34 focused tests, strict no-emit typecheck, build, formatting, and both real ClickHouse 26.8 layouts passed. Real storage qualification also ingested and returned exactly 10,000 ordered chunks. First-round ledger: R1-1 stale conditional resurrection, R1-2 context truncation, and R1-3 metadata input overflow were all P2 and fixed in this head. Independent review of this head is running.

[lia-by-librechat]

Head: 90c7fee. The three P2 review fixes remain included. Local deployed-image qualification found an owner-only package manifest unreadable by the non-root Bun user; the runtime copy now explicitly sets read permissions. CI now builds and runs the actual read-only, capability-free image, tests authenticated HTTP ingestion/search/context/delete and stale-edit rejection, and removes its test containers and anonymous volumes. Static checks, focused tests, real storage qualification, and the corrected runtime smoke passed locally. Review of the prior head was stopped; this head needs a fresh independent review.

[lia-by-librechat]

Delivery head: 90c7fee. Independent source review completed with no new findings. Ledger: three P2 lifecycle/context/embedding-budget findings fixed in 5830459; the locally observed non-root runtime packaging defect fixed in this head. No rejected or retained findings. Both CI checks are green. Local verification: 34 focused tests, plain/coded ClickHouse integration, full 10,000-chunk context, strict no-emit typecheck, build, formatting, and the shipped non-root read-only HTTP runtime passed. The reviewer did not run dependency-based tests; local checks and CI supply that runtime coverage. Production Loom parity, Cloud cross-replica tests, live embedding/extraction providers, and LibreChat issuer/viewer integration remain unqualified or outside this slice.