@carlonicora/nestjs-neo4jsonapi 2.14.11 → 2.15.0

package/dist/eval/retrieval/token-accounting.check.js

@@ -0,0 +1,75 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var TokenAccountingChecker_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenAccountingChecker = void 0;
+const common_1 = require("@nestjs/common");
+/** Tokens may legitimately differ by rounding; anything larger is a defect. */
+const TOLERANCE_TOKENS = 2;
+/**
+ * Cross-checks a turn's reported token aggregate against the sum of the calls
+ * actually observed for it.
+ *
+ * Spec §6.5. The `2C + A` reducer bug inflated every archived chat figure and
+ * went unnoticed for a full measurement cycle; this check is what makes the
+ * same class of bug loud instead of silent. Provider-reported per-call figures
+ * are the source of truth.
+ */
+let TokenAccountingChecker = TokenAccountingChecker_1 = class TokenAccountingChecker {
+    constructor() {
+        this.logger = new common_1.Logger(TokenAccountingChecker_1.name);
+        this.observedInput = 0;
+        this.observedOutput = 0;
+    }
+    /** Record one provider call's reported usage for the question in flight. */
+    observe(params) {
+        this.observedInput += params.input;
+        this.observedOutput += params.output;
+    }
+    /**
+     * Clears the accumulator WITHOUT producing a verdict.
+     *
+     * For the question that never completed a turn: it has nothing to compare, but
+     * it may still have deposited observations before it threw. Leaving them in
+     * place attributes them to the NEXT question — which either invents a mismatch
+     * that is not there or, worse, masks one that is. `check()` resets as a side
+     * effect of comparing; this is the same reset for the path that cannot compare.
+     */
+    reset() {
+        this.observedInput = 0;
+        this.observedOutput = 0;
+    }
+    /** Compare and RESET, so the next question starts clean. */
+    check(params) {
+        const result = {
+            ledgerInput: params.ledger.input,
+            observedInput: this.observedInput,
+            ledgerOutput: params.ledger.output,
+            observedOutput: this.observedOutput,
+            agrees: Math.abs(params.ledger.input - this.observedInput) <= TOLERANCE_TOKENS &&
+                Math.abs(params.ledger.output - this.observedOutput) <= TOLERANCE_TOKENS,
+            // The comparison ran. Only this method may set it — every other producer
+            // of a `TokenAccountingCheck` is describing a check that did NOT happen.
+            checked: true,
+        };
+        if (!result.agrees) {
+            this.logger.error(`token accounting MISMATCH on ${params.questionId}: reported ` +
+                `${result.ledgerInput}/${result.ledgerOutput} but observed ` +
+                `${result.observedInput}/${result.observedOutput}. The baseline is not trustworthy ` +
+                `until this is explained.`);
+        }
+        this.observedInput = 0;
+        this.observedOutput = 0;
+        return result;
+    }
+};
+exports.TokenAccountingChecker = TokenAccountingChecker;
+exports.TokenAccountingChecker = TokenAccountingChecker = TokenAccountingChecker_1 = __decorate([
+    (0, common_1.Injectable)()
+], TokenAccountingChecker);
+//# sourceMappingURL=token-accounting.check.js.map

package/dist/eval/retrieval/token-accounting.check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-accounting.check.js","sourceRoot":"","sources":["../../../src/eval/retrieval/token-accounting.check.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAoD;AAGpD,+EAA+E;AAC/E,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;;;;;;GAQG;AAEI,IAAM,sBAAsB,8BAA5B,MAAM,sBAAsB;IAA5B;QACY,WAAM,GAAG,IAAI,eAAM,CAAC,wBAAsB,CAAC,IAAI,CAAC,CAAC;QAC1D,kBAAa,GAAG,CAAC,CAAC;QAClB,mBAAc,GAAG,CAAC,CAAC;IAkD7B,CAAC;IAhDC,4EAA4E;IAC5E,OAAO,CAAC,MAAyC;QAC/C,IAAI,CAAC,aAAa,IAAI,MAAM,CAAC,KAAK,CAAC;QACnC,IAAI,CAAC,cAAc,IAAI,MAAM,CAAC,MAAM,CAAC;IACvC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK;QACH,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,MAAyE;QAC7E,MAAM,MAAM,GAAyB;YACnC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK;YAChC,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM;YAClC,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,MAAM,EACJ,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,gBAAgB;gBACtE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,gBAAgB;YAC1E,yEAAyE;YACzE,yEAAyE;YACzE,OAAO,EAAE,IAAI;SACd,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,gCAAgC,MAAM,CAAC,UAAU,aAAa;gBAC5D,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,YAAY,gBAAgB;gBAC5D,GAAG,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,cAAc,oCAAoC;gBACpF,0BAA0B,CAC7B,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QACxB,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAA;AArDY,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,mBAAU,GAAE;GACA,sBAAsB,CAqDlC"}

package/dist/foundations/atomicfact/repositories/atomicfact.repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomicfact.repository.d.ts","sourceRoot":"","sources":["../../../../src/foundations/atomicfact/repositories/atomicfact.repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,iDAAiD,CAAC;AAC1F,OAAO,EAAmB,qBAAqB,EAAE,MAAM,uDAAuD,CAAC;AAC/G,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,8CAA8C,CAAC;AAG1E,qBACa,oBAAqB,YAAW,YAAY;IAErD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU;IACF,OAAO,CAAC,QAAQ,CAAC,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAJV,KAAK,EAAE,YAAY,EACnB,eAAe,EAAE,eAAe,EAChC,UAAU,EAAE,UAAU,EACG,aAAa,EAAE,qBAAqB,EAC7D,UAAU,EAAE,uBAAuB;IAGhD,YAAY;IAMZ,4BAA4B,CAAC,MAAM,EAAE;QACzC,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,UAAU,EAAE,UAAU,CAAC;KACxB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAkCnB,wBAAwB,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAgB5E,kBAAkB,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAezE,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9C,gBAAgB,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAmB1G"}
+{"version":3,"file":"atomicfact.repository.d.ts","sourceRoot":"","sources":["../../../../src/foundations/atomicfact/repositories/atomicfact.repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,iDAAiD,CAAC;AAC1F,OAAO,EAAmB,qBAAqB,EAAE,MAAM,uDAAuD,CAAC;AAC/G,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kDAAkD,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,8CAA8C,CAAC;AAI1E,qBACa,oBAAqB,YAAW,YAAY;IAErD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU;IACF,OAAO,CAAC,QAAQ,CAAC,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAJV,KAAK,EAAE,YAAY,EACnB,eAAe,EAAE,eAAe,EAChC,UAAU,EAAE,UAAU,EACG,aAAa,EAAE,qBAAqB,EAC7D,UAAU,EAAE,uBAAuB;IAGhD,YAAY;IAMZ,4BAA4B,CAAC,MAAM,EAAE;QACzC,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,YAAY,EAAE,MAAM,EAAE,CAAC;QACvB,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,UAAU,EAAE,UAAU,CAAC;KACxB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAwCnB,wBAAwB,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAgB5E,kBAAkB,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAezE,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9C,gBAAgB,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAmB1G"}

package/dist/foundations/atomicfact/repositories/atomicfact.repository.js

@@ -20,6 +20,7 @@ const ai_source_query_provider_1 = require("../../../common/repositories/ai-sour
 const neo4j_service_1 = require("../../../core/neo4j/services/neo4j.service");
 const security_service_1 = require("../../../core/security/services/security.service");
 const atomic_fact_model_1 = require("../../atomicfact/entities/atomic.fact.model");
+const retrieval_constants_1 = require("../../chunk/repositories/retrieval.constants");
 let AtomicFactRepository = class AtomicFactRepository {
     constructor(neo4j, securityService, clsService, aiSourceQuery, agentScope) {
         this.neo4j = neo4j;
@@ -51,9 +52,14 @@ let AtomicFactRepository = class AtomicFactRepository {
             keyConcepts: params.keyConcepts,
             skipChunkIds: params.skipChunkIds,
             skipAtomicFactIds: params.skipAtomicFactIds,
+            maxAtomicFacts: retrieval_constants_1.MAX_ATOMIC_FACTS,
             ...scope.params,
             ...scopeFilter.params,
         };
+        // Deliberate: the facts are NOT ordered before the cut. Atomic facts carry no
+        // embedding (spec §2.4), so there is no relevance signal to order by — this is
+        // a spend bound, not a ranking. Giving facts embeddings is out of scope and has
+        // its own spec.
         query.query += `
       ${scope.cypher}
       ${scopeFilter.cypher}
@@ -62,6 +68,7 @@ let AtomicFactRepository = class AtomicFactRepository {
       ${params.skipChunkIds.length > 0 ? `AND NOT atomicfact_chunk.id IN $skipChunkIds` : ""}
       ${params.skipAtomicFactIds.length > 0 ? `AND NOT atomicfact.id IN $skipAtomicFactIds` : ""}
       RETURN atomicfact, atomicfact_chunk
+      LIMIT toInteger($maxAtomicFacts)
   `;
         return this.neo4j.readMany(query);
     }

package/dist/foundations/atomicfact/repositories/atomicfact.repository.js.map

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

package/dist/foundations/chunk/repositories/chunk.repository.d.ts

@@ -39,13 +39,70 @@ export declare class ChunkRepository implements OnModuleInit {
      * lives with the caller (the contextualiser knows which content the run is
      * bound to), which is why it is passed down rather than derived here. Absent,
      * `EmbedderService.persistUsage` records nothing.
+     *
+     * Each returned chunk carries `score`: the cosine similarity of that chunk against
+     * the question embedding. Both retrieval halves have to reach the notebook on ONE
+     * scale — the answer node orders entries best-score-first and fills a character
+     * budget, so an unscored half sorts last however good it is. The RRF score is NOT
+     * usable for that: it is rank-derived (the top hit scores ≈1/61 whether it is a
+     * perfect match or noise) and is not comparable with a cosine from the graph half.
      */
     findPotentialChunks(params: {
         question: string;
         dataLimits: DataLimits;
         attribution?: EmbedderAttribution;
-    }): Promise<Chunk[]>;
+        /**
+         * Precomputed question embedding. When supplied the repository does NOT
+         * embed again — the same question is otherwise embedded twice per turn,
+         * once here and once in findPotentialKeyConcepts. Optional so existing
+         * callers are unaffected.
+         */
+        queryEmbedding?: number[];
+    }): Promise<Array<Chunk & {
+        score?: number;
+    }>>;
+    /**
+     * Exact cosine over the scoped set. No recall cliff by construction: every
+     * in-scope chunk is scored, so a small tenant can never be crowded out of a
+     * global top-K by a large one.
+     */
+    private vectorIdsByExactScan;
+    /**
+     * Index-backed fallback for scoped sets too large to scan exactly. Still
+     * post-filters, so it still has a cliff — the over-fetch is what pushes that
+     * cliff out of reach, and it is deliberately far above the previous 1,000.
+     */
+    private vectorIdsByIndex;
+    /**
+     * Lexical branch, scoped the same way. Previously filtered against the
+     * client-side id list; now joined in the database like the vector branch.
+     */
+    private lexicalIdsInScope;
+    /**
+     * INPUT ORDER IS PART OF THE CONTRACT here too: `WHERE chunk.id IN $ids` yields rows
+     * in store order, and the fused RRF order is what the caller means by "best first".
+     *
+     * `queryEmbedding` attaches the cosine score of each chunk against the question, on
+     * the same scale `findChunksByIds` puts on the graph half. No floor and no count cap
+     * are applied — the notebook's character budget decides what reaches the answer.
+     */
     private findChunksByIdsOrdered;
+    /**
+     * Attaches `vector.similarity.cosine(chunk.embedding, $queryEmbedding)` to already
+     * hydrated chunks, by id, in JS.
+     *
+     * Why a separate read rather than one extra column on the hydration query: the
+     * hydration goes through `readMany`, which maps every row with the descriptor's
+     * generated mapper, and that mapper only ever reads the descriptor's own fields,
+     * computed fields and virtual fields (`define-entity.ts`). A projected column such
+     * as `score` is therefore silently DROPPED before the caller ever sees it. Reading
+     * the id/score pairs on their own and merging them here keeps entity mapping on
+     * `readMany` — this repository never hand-maps raw Neo4j records.
+     *
+     * SCOPE: this read scores only ids that the caller's own scope-gated query already
+     * returned, so it cannot widen the scope by construction.
+     */
+    private attachCosineScores;
     findParentName(params: {
         id: string;
         nodeType: string;
@@ -67,6 +124,35 @@ export declare class ChunkRepository implements OnModuleInit {
         chunkId: string;
         dataLimits?: DataLimits;
     }): Promise<Chunk>;
+    /**
+     * Hydrates many chunks in ONE query, with the same scope gate `findChunkById`
+     * applies to one. The caller previously looped with an `await` inside,
+     * costing one round trip per queued chunk. Returns only the chunks that
+     * exist and are in scope; the caller must not assume a 1:1 mapping with
+     * `chunkIds`.
+     *
+     * ORDER IS PART OF THE CONTRACT. `WHERE chunk.id IN $chunkIds` returns rows in
+     * whatever order the store yields them, but the loop this replaced hydrated in
+     * queue order, and that order reaches the contextualiser's per-chunk fan-out and
+     * the notebook entries it writes. Returning them shuffled changes what the answer
+     * node cites. The input order is therefore restored here, exactly as
+     * `findChunksByIdsOrdered` does for the retrieval path.
+     *
+     * `queryEmbedding` is OPTIONAL and, when given, attaches `score`: the cosine
+     * similarity of the chunk against the question. These chunks arrive from a fact
+     * join with no score of their own, which is precisely why an LLM used to have to
+     * judge them; cosine puts this half on the SAME scale as the document half, so the
+     * answer node can order both together. When it is absent the scoring clause is not
+     * in the Cypher at all. No floor is applied at any point: the notebook's character
+     * budget, not a threshold, decides what reaches the answer.
+     */
+    findChunksByIds(params: {
+        chunkIds: string[];
+        dataLimits?: DataLimits;
+        queryEmbedding?: number[];
+    }): Promise<Array<Chunk & {
+        score?: number;
+    }>>;
     /**
      * Pipeline hydration of a content node's chunks — deliberately WITHOUT `embedding`.
      *

package/dist/foundations/chunk/repositories/chunk.repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.repository.d.ts","sourceRoot":"","sources":["../../../../src/foundations/chunk/repositories/chunk.repository.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chunk.repository.d.ts","sourceRoot":"","sources":["../../../../src/foundations/chunk/repositories/chunk.repository.ts"],"names":[],"mappings":"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"}

package/dist/foundations/chunk/repositories/chunk.repository.js

@@ -27,6 +27,7 @@ const neo4j_service_1 = require("../../../core/neo4j/services/neo4j.service");
 const security_service_1 = require("../../../core/security/services/security.service");
 const chunk_entity_1 = require("../../chunk/entities/chunk.entity");
 const chunk_meta_1 = require("../entities/chunk.meta");
+const retrieval_constants_1 = require("./retrieval.constants");
 const reciprocal_rank_fusion_1 = require("../services/reciprocal-rank-fusion");
 let ChunkRepository = ChunkRepository_1 = class ChunkRepository {
     constructor(neo4j, modelService, embedderService, clsService, securityService, aiSourceQuery, agentScope) {
@@ -101,67 +102,163 @@ let ChunkRepository = ChunkRepository_1 = class ChunkRepository {
      * lives with the caller (the contextualiser knows which content the run is
      * bound to), which is why it is passed down rather than derived here. Absent,
      * `EmbedderService.persistUsage` records nothing.
+     *
+     * Each returned chunk carries `score`: the cosine similarity of that chunk against
+     * the question embedding. Both retrieval halves have to reach the notebook on ONE
+     * scale — the answer node orders entries best-score-first and fills a character
+     * budget, so an unscored half sorts last however good it is. The RRF score is NOT
+     * usable for that: it is rank-derived (the top hit scores ≈1/61 whether it is a
+     * perfect match or noise) and is not comparable with a cosine from the graph half.
      */
     async findPotentialChunks(params) {
-        const queryEmbedding = await this.embedderService.vectoriseText({
-            text: params.question,
-            attribution: params.attribution,
-        });
+        // The question is embedded ONCE per turn. When the caller already has the
+        // vector (chunk_vector computes it and shares it through the graph state),
+        // do not pay for a second identical embedding.
+        const queryEmbedding = params.queryEmbedding ??
+            (await this.embedderService.vectoriseText({
+                text: params.question,
+                attribution: params.attribution,
+            }));
         // Lucene special-character escape so user questions can't break the fulltext query.
+        //
+        // NOT `buildFulltextTerm`: that helper tokenises and AND-joins a
+        // contains-wildcard per token, which is right for a search BOX (a few
+        // words) and wrong for a natural-language question. A 28-token question
+        // becomes 28 AND-ed clauses that no chunk can satisfy — measured against
+        // the eval corpus, the identical question went from 1,786 fulltext hits to
+        // 0, silently collapsing hybrid retrieval to its vector branch alone.
         const term = params.question.replace(/([+\-!(){}\[\]^"~*?:\\\/]|&&|\|\|)/g, "\\$1");
-        // The access-scoped id-set both retrieval branches are filtered to.
         const scope = this.aiSourceQuery.build({
             dataLimits: params.dataLimits,
             currentUserId: this.clsService.get("userId"),
             securityService: this.securityService,
             returnsData: true,
         });
-        // Both the vector and the lexical branch below are filtered to this id-set,
-        // so confining it to the run's scope root confines the whole hybrid search.
         const scopeFilter = this.agentScope.build({ alias: "data", dataLimits: params.dataLimits });
-        const scopeQuery = this.neo4j.initQuery();
-        scopeQuery.queryParams = { ...scopeQuery.queryParams, ...scope.params, ...scopeFilter.params };
-        scopeQuery.query += `
-        ${scope.cypher}
-        ${scopeFilter.cypher}
-        MATCH (chunk:Chunk)<-[:HAS_CHUNK]-(data)
-        RETURN COLLECT(DISTINCT chunk.id) AS chunkIds
-      `;
-        const scopeResult = await this.neo4j.read(scopeQuery.query, scopeQuery.queryParams);
-        const chunkIds = scopeResult.records[0]?.get("chunkIds") ?? [];
-        if (chunkIds.length === 0)
+        // How large is the scoped set? One cheap count decides which shape to use.
+        // Scope-first exact cosine has no recall cliff but reads every in-scope
+        // embedding; the index is cheaper at volume but can only post-filter a
+        // GLOBAL top-K, which is the cliff this task exists to remove.
+        const countQuery = this.neo4j.initQuery();
+        countQuery.queryParams = { ...countQuery.queryParams, ...scope.params, ...scopeFilter.params };
+        countQuery.query += `
+      ${scope.cypher}
+      ${scopeFilter.cypher}
+      MATCH (chunk:Chunk)<-[:HAS_CHUNK]-(data)
+      RETURN count(DISTINCT chunk) AS scopedCount
+    `;
+        const countResult = await this.neo4j.read(countQuery.query, countQuery.queryParams);
+        const scopedCount = Number(countResult.records[0]?.get("scopedCount") ?? 0);
+        if (scopedCount === 0)
             return [];
-        const vectorResult = await this.neo4j.read(`
-        CALL db.index.vector.queryNodes('chunks', 1000, $queryEmbedding)
-        YIELD node AS candidateChunk, score
-        WHERE candidateChunk.id IN $chunkIds
-        RETURN candidateChunk.id AS id
-        ORDER BY score DESC
-        LIMIT 50
-      `, { queryEmbedding, chunkIds });
-        const vectorIds = vectorResult.records.map((record) => record.get("id"));
-        let lexicalIds = [];
-        if (term.trim()) {
-            const lexicalResult = await this.neo4j.read(`
-          CALL db.index.fulltext.queryNodes('chunk_content_search', $term)
-          YIELD node, score
-          WHERE node.id IN $chunkIds
-          RETURN node.id AS id
-          ORDER BY score DESC
-          LIMIT 50
-        `, { term, chunkIds });
-            lexicalIds = lexicalResult.records.map((record) => record.get("id"));
-        }
+        const vectorIds = scopedCount <= retrieval_constants_1.EXACT_SCAN_MAX_SCOPED_CHUNKS
+            ? await this.vectorIdsByExactScan({ scope, scopeFilter, queryEmbedding })
+            : await this.vectorIdsByIndex({ scope, scopeFilter, queryEmbedding });
+        const lexicalIds = term.trim() ? await this.lexicalIdsInScope({ scope, scopeFilter, term }) : [];
         const fusedIds = (0, reciprocal_rank_fusion_1.reciprocalRankFusion)([vectorIds, lexicalIds]).slice(0, 20);
-        return this.findChunksByIdsOrdered(fusedIds);
+        return this.findChunksByIdsOrdered({ ids: fusedIds, queryEmbedding });
     }
-    async findChunksByIdsOrdered(ids) {
-        if (ids.length === 0)
+    /**
+     * Exact cosine over the scoped set. No recall cliff by construction: every
+     * in-scope chunk is scored, so a small tenant can never be crowded out of a
+     * global top-K by a large one.
+     */
+    async vectorIdsByExactScan(params) {
+        const query = this.neo4j.initQuery();
+        query.queryParams = {
+            ...query.queryParams,
+            ...params.scope.params,
+            ...params.scopeFilter.params,
+            queryEmbedding: params.queryEmbedding,
+        };
+        query.query += `
+      ${params.scope.cypher}
+      ${params.scopeFilter.cypher}
+      MATCH (chunk:Chunk)<-[:HAS_CHUNK]-(data)
+      WHERE chunk.embedding IS NOT NULL
+      WITH DISTINCT chunk
+      WITH chunk, vector.similarity.cosine(chunk.embedding, $queryEmbedding) AS score
+      WHERE score IS NOT NULL
+      RETURN chunk.id AS id
+      ORDER BY score DESC
+      LIMIT 50
+    `;
+        const result = await this.neo4j.read(query.query, query.queryParams);
+        return result.records.map((record) => record.get("id"));
+    }
+    /**
+     * Index-backed fallback for scoped sets too large to scan exactly. Still
+     * post-filters, so it still has a cliff — the over-fetch is what pushes that
+     * cliff out of reach, and it is deliberately far above the previous 1,000.
+     */
+    async vectorIdsByIndex(params) {
+        const query = this.neo4j.initQuery();
+        query.queryParams = {
+            ...query.queryParams,
+            ...params.scope.params,
+            ...params.scopeFilter.params,
+            queryEmbedding: params.queryEmbedding,
+            overFetch: retrieval_constants_1.CHUNK_VECTOR_OVERFETCH,
+        };
+        query.query += `
+      ${params.scope.cypher}
+      ${params.scopeFilter.cypher}
+      MATCH (chunk:Chunk)<-[:HAS_CHUNK]-(data)
+      WITH collect(DISTINCT chunk.id) AS scopedChunkIds
+      CALL db.index.vector.queryNodes('chunks', toInteger($overFetch), $queryEmbedding)
+      YIELD node AS candidateChunk, score
+      WITH scopedChunkIds, candidateChunk, score
+      WHERE candidateChunk.id IN scopedChunkIds
+      RETURN candidateChunk.id AS id
+      ORDER BY score DESC
+      LIMIT 50
+    `;
+        const result = await this.neo4j.read(query.query, query.queryParams);
+        return result.records.map((record) => record.get("id"));
+    }
+    /**
+     * Lexical branch, scoped the same way. Previously filtered against the
+     * client-side id list; now joined in the database like the vector branch.
+     */
+    async lexicalIdsInScope(params) {
+        const query = this.neo4j.initQuery();
+        query.queryParams = {
+            ...query.queryParams,
+            ...params.scope.params,
+            ...params.scopeFilter.params,
+            term: params.term,
+        };
+        query.query += `
+      ${params.scope.cypher}
+      ${params.scopeFilter.cypher}
+      MATCH (chunk:Chunk)<-[:HAS_CHUNK]-(data)
+      WITH collect(DISTINCT chunk.id) AS scopedChunkIds
+      CALL db.index.fulltext.queryNodes('chunk_content_search', $term)
+      YIELD node, score
+      WITH scopedChunkIds, node, score
+      WHERE node.id IN scopedChunkIds
+      RETURN node.id AS id
+      ORDER BY score DESC
+      LIMIT 50
+    `;
+        const result = await this.neo4j.read(query.query, query.queryParams);
+        return result.records.map((record) => record.get("id"));
+    }
+    /**
+     * INPUT ORDER IS PART OF THE CONTRACT here too: `WHERE chunk.id IN $ids` yields rows
+     * in store order, and the fused RRF order is what the caller means by "best first".
+     *
+     * `queryEmbedding` attaches the cosine score of each chunk against the question, on
+     * the same scale `findChunksByIds` puts on the graph half. No floor and no count cap
+     * are applied — the notebook's character budget decides what reaches the answer.
+     */
+    async findChunksByIdsOrdered(params) {
+        if (params.ids.length === 0)
             return [];
         const query = this.neo4j.initQuery({ serialiser: chunk_entity_1.ChunkDescriptor.model });
         query.queryParams = {
             ...query.queryParams,
-            ids,
+            ids: params.ids,
         };
         query.query += `
       MATCH (chunk:Chunk)
@@ -169,8 +266,50 @@ let ChunkRepository = ChunkRepository_1 = class ChunkRepository {
       RETURN chunk
     `;
         const chunks = await this.neo4j.readMany(query);
-        const byId = new Map(chunks.map((chunk) => [chunk.id, chunk]));
-        return ids.map((id) => byId.get(id)).filter((chunk) => chunk !== undefined);
+        const scored = await this.attachCosineScores({ chunks, queryEmbedding: params.queryEmbedding });
+        const byId = new Map(scored.map((chunk) => [chunk.id, chunk]));
+        return params.ids
+            .map((id) => byId.get(id))
+            .filter((chunk) => chunk !== undefined);
+    }
+    /**
+     * Attaches `vector.similarity.cosine(chunk.embedding, $queryEmbedding)` to already
+     * hydrated chunks, by id, in JS.
+     *
+     * Why a separate read rather than one extra column on the hydration query: the
+     * hydration goes through `readMany`, which maps every row with the descriptor's
+     * generated mapper, and that mapper only ever reads the descriptor's own fields,
+     * computed fields and virtual fields (`define-entity.ts`). A projected column such
+     * as `score` is therefore silently DROPPED before the caller ever sees it. Reading
+     * the id/score pairs on their own and merging them here keeps entity mapping on
+     * `readMany` — this repository never hand-maps raw Neo4j records.
+     *
+     * SCOPE: this read scores only ids that the caller's own scope-gated query already
+     * returned, so it cannot widen the scope by construction.
+     */
+    async attachCosineScores(params) {
+        if (!params.queryEmbedding || params.chunks.length === 0)
+            return params.chunks;
+        const query = this.neo4j.initQuery();
+        query.queryParams = {
+            ...query.queryParams,
+            ids: params.chunks.map((chunk) => chunk.id),
+            queryEmbedding: params.queryEmbedding,
+        };
+        query.query += `
+      MATCH (chunk:Chunk)
+      WHERE chunk.id IN $ids AND chunk.embedding IS NOT NULL
+      RETURN chunk.id AS id, vector.similarity.cosine(chunk.embedding, $queryEmbedding) AS score
+    `;
+        const result = await this.neo4j.read(query.query, query.queryParams);
+        const scoreById = new Map();
+        for (const record of result.records) {
+            const id = record.get("id");
+            const score = record.get("score");
+            if (typeof id === "string" && typeof score === "number")
+                scoreById.set(id, score);
+        }
+        return params.chunks.map((chunk) => ({ ...chunk, score: scoreById.get(chunk.id) }));
     }
     async findParentName(params) {
         const query = this.neo4j.initQuery();
@@ -229,6 +368,51 @@ let ChunkRepository = ChunkRepository_1 = class ChunkRepository {
     `;
         return this.neo4j.readOne(query);
     }
+    /**
+     * Hydrates many chunks in ONE query, with the same scope gate `findChunkById`
+     * applies to one. The caller previously looped with an `await` inside,
+     * costing one round trip per queued chunk. Returns only the chunks that
+     * exist and are in scope; the caller must not assume a 1:1 mapping with
+     * `chunkIds`.
+     *
+     * ORDER IS PART OF THE CONTRACT. `WHERE chunk.id IN $chunkIds` returns rows in
+     * whatever order the store yields them, but the loop this replaced hydrated in
+     * queue order, and that order reaches the contextualiser's per-chunk fan-out and
+     * the notebook entries it writes. Returning them shuffled changes what the answer
+     * node cites. The input order is therefore restored here, exactly as
+     * `findChunksByIdsOrdered` does for the retrieval path.
+     *
+     * `queryEmbedding` is OPTIONAL and, when given, attaches `score`: the cosine
+     * similarity of the chunk against the question. These chunks arrive from a fact
+     * join with no score of their own, which is precisely why an LLM used to have to
+     * judge them; cosine puts this half on the SAME scale as the document half, so the
+     * answer node can order both together. When it is absent the scoring clause is not
+     * in the Cypher at all. No floor is applied at any point: the notebook's character
+     * budget, not a threshold, decides what reaches the answer.
+     */
+    async findChunksByIds(params) {
+        if (params.chunkIds.length === 0)
+            return [];
+        const query = this.neo4j.initQuery({ serialiser: chunk_entity_1.ChunkDescriptor.model });
+        const scopePredicate = this.agentScope.predicate({ alias: "data", dataLimits: params.dataLimits });
+        query.queryParams = {
+            ...query.queryParams,
+            chunkIds: params.chunkIds,
+            ...(scopePredicate?.params ?? {}),
+        };
+        query.query += `
+      MATCH (chunk:Chunk)
+      WHERE chunk.id IN $chunkIds
+      ${scopePredicate ? `AND EXISTS { MATCH (chunk)<-[:HAS_CHUNK]-(data) WHERE ${scopePredicate.cypher} }` : ""}
+      RETURN chunk
+    `;
+        const chunks = await this.neo4j.readMany(query);
+        const scored = await this.attachCosineScores({ chunks, queryEmbedding: params.queryEmbedding });
+        const byId = new Map(scored.map((chunk) => [chunk.id, chunk]));
+        return params.chunkIds
+            .map((id) => byId.get(id))
+            .filter((chunk) => chunk !== undefined);
+    }
     /**
      * Pipeline hydration of a content node's chunks — deliberately WITHOUT `embedding`.
      *
@@ -564,16 +748,21 @@ let ChunkRepository = ChunkRepository_1 = class ChunkRepository {
         if (params.chunkIds.length === 0)
             return [];
         const query = this.neo4j.initQuery();
-        query.queryParams = { ...query.queryParams, chunkIds: params.chunkIds, window: params.window };
+        query.queryParams = { ...query.queryParams, chunkIds: params.chunkIds };
+        // Neo4j will not take a parameter as a variable-length bound, so the window
+        // is clamped to a small integer and interpolated. It is never user input —
+        // the only caller passes the NEIGHBOR_WINDOW constant — and Number() plus
+        // the clamp make injection impossible.
+        const window = Math.max(1, Math.min(5, Math.trunc(Number(params.window) || 1)));
         query.query = `
       UNWIND $chunkIds AS cid
       MATCH (c:Chunk {id: cid})
-      OPTIONAL MATCH pBefore = (b:Chunk)-[:NEXT*1..]->(c)
+      OPTIONAL MATCH pBefore = (b:Chunk)-[:NEXT*1..${window}]->(c)
       WITH cid, c, b, length(pBefore) AS beforeDist ORDER BY beforeDist ASC
-      WITH cid, c, [x IN collect(b) WHERE x IS NOT NULL][0..$window] AS befores
-      OPTIONAL MATCH pAfter = (c)-[:NEXT*1..]->(a:Chunk)
+      WITH cid, c, [x IN collect(b) WHERE x IS NOT NULL][0..${window}] AS befores
+      OPTIONAL MATCH pAfter = (c)-[:NEXT*1..${window}]->(a:Chunk)
       WITH cid, befores, a, length(pAfter) AS afterDist ORDER BY afterDist ASC
-      WITH cid, befores, [x IN collect(a) WHERE x IS NOT NULL][0..$window] AS afters
+      WITH cid, befores, [x IN collect(a) WHERE x IS NOT NULL][0..${window}] AS afters
       RETURN cid AS chunkId, [x IN befores | x.content] AS before, [x IN afters | x.content] AS after
     `;
         const result = await this.neo4j.read(query.query, query.queryParams);