@carlonicora/nestjs-neo4jsonapi 1.64.0 → 1.65.0

package/dist/agents/graph/services/graph.search.service.d.ts

@@ -0,0 +1,69 @@
+import { EmbedderService } from "../../../core/llm/services/embedder.service";
+import { Neo4jService } from "../../../core/neo4j/services/neo4j.service";
+import { CatalogEntity } from "../interfaces/graph.catalog.interface";
+import { GraphIndexManager } from "./graph.index.manager";
+import { GraphCatalogService } from "./graph.catalog.service";
+export declare const GRAPH_EXACT_MAX_RESULTS = 10;
+export declare const GRAPH_FUZZY_MAX_RESULTS = 10;
+export declare const GRAPH_SEMANTIC_MAX_RESULTS = 5;
+export declare const GRAPH_RESOLVE_MAX_RESULTS = 10;
+export declare const GRAPH_SEMANTIC_MIN_SCORE = 0.6;
+export type MatchMode = "exact" | "fuzzy" | "semantic" | "none";
+export interface RunSearchParams {
+    entity: CatalogEntity;
+    text: string;
+    companyId: string;
+    limit: number;
+}
+export interface RankedCandidate {
+    type: string;
+    id: string;
+    summary: string;
+    score: number;
+}
+export interface ResolveEntityParams {
+    text: string;
+    companyId: string;
+    userModuleIds: string[];
+}
+export interface ResolveEntityResult {
+    matchMode: MatchMode;
+    items: RankedCandidate[];
+    /**
+     * When the merged candidate list satisfies a deterministic disambiguation
+     * rule (literal-summary match, or score-margin dominance), surface a short
+     * actionable hint here. The graph node prompt instructs the LLM to follow
+     * this when present, since LLMs apply rules in the tool result more
+     * reliably than rules they have to re-derive from the system prompt.
+     */
+    recommendation?: string;
+}
+/**
+ * Decide whether the merged candidate list satisfies a deterministic
+ * disambiguation rule worth surfacing to the LLM. Returns the recommendation
+ * text or `undefined` when the candidates are genuinely ambiguous.
+ *
+ * Two rules, in priority order:
+ *   1. Literal-summary match: items[0].summary equals the user's literal
+ *      phrase (case-insensitive). Holds even with a smaller margin because
+ *      the name match is unambiguous on its own.
+ *   2. Score-margin dominance: items[0] beats items[1] by ≥ 0.15 on
+ *      exact/fuzzy tiers, ≥ 0.08 on semantic.
+ */
+export declare function buildResolveRecommendation(items: RankedCandidate[], userText: string, matchMode: MatchMode): string | undefined;
+export declare class GraphSearchService {
+    private readonly neo4j;
+    private readonly embedder;
+    private readonly indexNames;
+    private readonly catalog;
+    private readonly logger;
+    private existingIndexesPromise;
+    constructor(neo4j: Neo4jService, embedder: EmbedderService, indexNames: GraphIndexManager, catalog: GraphCatalogService);
+    private getExistingIndexes;
+    resolveEntity(params: ResolveEntityParams): Promise<ResolveEntityResult>;
+    private runTierForEntitySafe;
+    private projectSummary;
+    private tierFulltext;
+    private tierSemantic;
+}
+//# sourceMappingURL=graph.search.service.d.ts.map

package/dist/agents/graph/services/graph.search.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.search.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/services/graph.search.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAC5C,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAK5C,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,eAAe,EAAE,EACxB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,GACnB,MAAM,GAAG,SAAS,CAepB;AASD,qBACa,kBAAkB;IAY3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAd1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAQ9D,OAAO,CAAC,sBAAsB,CAAqC;gBAGhD,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,eAAe,EACzB,UAAU,EAAE,iBAAiB,EAC7B,OAAO,EAAE,mBAAmB;IAG/C,OAAO,CAAC,kBAAkB;IAmBpB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;YA2BhE,oBAAoB;IAqDlC,OAAO,CAAC,cAAc;YAiBR,YAAY;YAiCZ,YAAY;CAoC3B"}

package/dist/agents/graph/services/graph.search.service.js

@@ -0,0 +1,230 @@
+"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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var GraphSearchService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphSearchService = exports.GRAPH_SEMANTIC_MIN_SCORE = exports.GRAPH_RESOLVE_MAX_RESULTS = exports.GRAPH_SEMANTIC_MAX_RESULTS = exports.GRAPH_FUZZY_MAX_RESULTS = exports.GRAPH_EXACT_MAX_RESULTS = void 0;
+exports.buildResolveRecommendation = buildResolveRecommendation;
+const common_1 = require("@nestjs/common");
+const embedder_service_1 = require("../../../core/llm/services/embedder.service");
+const neo4j_service_1 = require("../../../core/neo4j/services/neo4j.service");
+const graph_index_manager_1 = require("./graph.index.manager");
+const graph_catalog_service_1 = require("./graph.catalog.service");
+exports.GRAPH_EXACT_MAX_RESULTS = 10;
+exports.GRAPH_FUZZY_MAX_RESULTS = 10;
+exports.GRAPH_SEMANTIC_MAX_RESULTS = 5;
+exports.GRAPH_RESOLVE_MAX_RESULTS = 10;
+exports.GRAPH_SEMANTIC_MIN_SCORE = 0.6;
+const GRAPH_VECTOR_OVERFETCH = 50;
+const LUCENE_RESERVED_RE = /[+\-&|!(){}[\]^"~*?:\\/]/g;
+/**
+ * Decide whether the merged candidate list satisfies a deterministic
+ * disambiguation rule worth surfacing to the LLM. Returns the recommendation
+ * text or `undefined` when the candidates are genuinely ambiguous.
+ *
+ * Two rules, in priority order:
+ *   1. Literal-summary match: items[0].summary equals the user's literal
+ *      phrase (case-insensitive). Holds even with a smaller margin because
+ *      the name match is unambiguous on its own.
+ *   2. Score-margin dominance: items[0] beats items[1] by ≥ 0.15 on
+ *      exact/fuzzy tiers, ≥ 0.08 on semantic.
+ */
+function buildResolveRecommendation(items, userText, matchMode) {
+    if (items.length === 0)
+        return undefined;
+    const top = items[0];
+    const next = items[1];
+    const margin = next ? top.score - next.score : Number.POSITIVE_INFINITY;
+    const literalMatch = top.summary.trim().toLowerCase() === userText.trim().toLowerCase();
+    const dominantMargin = margin >= (matchMode === "semantic" ? 0.08 : 0.15);
+    if (literalMatch && (items.length === 1 || dominantMargin)) {
+        return `Use items[0] (id=${top.id}, type=${top.type}): its summary equals the user's literal phrase and dominates by score margin. Do not ask the user to disambiguate.`;
+    }
+    if (dominantMargin) {
+        return `Use items[0] (id=${top.id}, type=${top.type}): it dominates the next candidate by the documented score margin (${margin.toFixed(2)}).`;
+    }
+    return undefined;
+}
+let GraphSearchService = GraphSearchService_1 = class GraphSearchService {
+    constructor(neo4j, embedder, indexNames, catalog) {
+        this.neo4j = neo4j;
+        this.embedder = embedder;
+        this.indexNames = indexNames;
+        this.catalog = catalog;
+        this.logger = new common_1.Logger(GraphSearchService_1.name);
+        // Cached at first use, holds the names of fulltext + vector indexes that
+        // actually exist in Neo4j. Pre-checking this set lets us skip the
+        // `db.index.fulltext.queryNodes` call entirely for indexes the bootstrap
+        // didn't create (silencing the ERROR + WARN spam at source). Stored as a
+        // promise to deduplicate concurrent first-time lookups (resolveEntity fans
+        // out tier queries via Promise.all).
+        this.existingIndexesPromise = null;
+    }
+    getExistingIndexes() {
+        if (this.existingIndexesPromise)
+            return this.existingIndexesPromise;
+        this.existingIndexesPromise = (async () => {
+            try {
+                const result = await this.neo4j.read(`SHOW INDEXES YIELD name, type WHERE type IN ["FULLTEXT", "VECTOR"] RETURN name`);
+                return new Set((result.records ?? []).map((r) => r.get("name")));
+            }
+            catch {
+                // If SHOW INDEXES itself fails (older Neo4j, permissions, mocked tests
+                // that don't expect it), return an empty set. Downstream gating uses
+                // `size > 0 && !has(name)` so an empty set means "do not gate" — the
+                // tier query proceeds and any error is handled by runTierForEntitySafe.
+                return new Set();
+            }
+        })();
+        return this.existingIndexesPromise;
+    }
+    async resolveEntity(params) {
+        const entities = this.catalog.getAllChatEnabledEntities().filter((e) => params.userModuleIds.includes(e.moduleId));
+        if (!entities.length) {
+            return { matchMode: "none", items: [] };
+        }
+        const tiers = [
+            ["substring", "exact"],
+            ["fuzzy", "fuzzy"],
+            ["semantic", "semantic"],
+        ];
+        for (const [tier, label] of tiers) {
+            const buckets = await Promise.all(entities.map((e) => this.runTierForEntitySafe(e, params, tier)));
+            const merged = buckets.flat();
+            if (merged.length) {
+                merged.sort((a, b) => b.score - a.score);
+                const items = merged.slice(0, exports.GRAPH_RESOLVE_MAX_RESULTS);
+                const recommendation = buildResolveRecommendation(items, params.text, label);
+                return recommendation ? { matchMode: label, items, recommendation } : { matchMode: label, items };
+            }
+        }
+        return { matchMode: "none", items: [] };
+    }
+    async runTierForEntitySafe(entity, params, tier) {
+        try {
+            const runParams = {
+                entity,
+                text: params.text,
+                companyId: params.companyId,
+                limit: tier === "semantic"
+                    ? exports.GRAPH_SEMANTIC_MAX_RESULTS
+                    : tier === "fuzzy"
+                        ? exports.GRAPH_FUZZY_MAX_RESULTS
+                        : exports.GRAPH_EXACT_MAX_RESULTS,
+            };
+            const inner = tier === "semantic" ? await this.tierSemantic(runParams) : await this.tierFulltext(runParams, tier);
+            // Per-tier diagnostic so a future dump can distinguish "fulltext index
+            // missing" from "lucene parse failure" from "genuine zero hits". Today
+            // these were silently merged into a single matchMode=none response.
+            const indexName = tier === "semantic"
+                ? this.indexNames.vectorIndexName(entity.labelName)
+                : this.indexNames.fulltextIndexName(entity.labelName);
+            const existing = await this.getExistingIndexes();
+            const indexExists = existing.size === 0 || existing.has(indexName);
+            this.logger.debug(`resolve_entity tier=${tier} type=${entity.type} indexExists=${indexExists} items=${inner.items.length}`);
+            return inner.items.map((i) => ({
+                type: entity.type,
+                id: i.id,
+                summary: this.projectSummary(entity, i.properties, i.id),
+                score: i.score,
+            }));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // Missing fulltext / vector index for an entity type the manager bootstrap
+            // didn't create one for: silently skip this tier for this type. The whole
+            // Neo4j stack trace was being printed at ERROR level for every resolve_entity
+            // call — pure noise. Real failures (other Neo4j errors, network, etc.) still
+            // log at WARN as before.
+            if (/There is no such fulltext schema index|There is no such vector schema index/i.test(message)) {
+                return [];
+            }
+            this.logger.warn(`resolveEntity: tier=${tier} type=${entity.type} threw: ${message}`);
+            return [];
+        }
+    }
+    projectSummary(entity, properties, id) {
+        if (entity.summary) {
+            try {
+                return entity.summary(properties);
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        const name = properties.name;
+        if (typeof name === "string" && name.length)
+            return name;
+        return id;
+    }
+    async tierFulltext(params, mode) {
+        const indexName = this.indexNames.fulltextIndexName(params.entity.labelName);
+        const existing = await this.getExistingIndexes();
+        if (existing.size > 0 && !existing.has(indexName)) {
+            return { matchMode: mode === "substring" ? "exact" : "fuzzy", items: [] };
+        }
+        const escaped = params.text.replace(LUCENE_RESERVED_RE, "\\$&").toLowerCase();
+        const term = mode === "substring" ? `*${escaped}*` : `${escaped}~`;
+        const max = mode === "substring" ? exports.GRAPH_EXACT_MAX_RESULTS : exports.GRAPH_FUZZY_MAX_RESULTS;
+        const result = await this.neo4j.read(`
+      CALL db.index.fulltext.queryNodes($indexName, $term)
+      YIELD node, score
+      WHERE (node)-[:BELONGS_TO]->(:Company { id: $companyId })
+      RETURN node.id AS id, properties(node) AS properties, score
+      ORDER BY score DESC
+      LIMIT toInteger($limit)
+      `, { indexName, term, companyId: params.companyId, limit: Math.min(params.limit, max) });
+        const items = result.records.map((r) => ({
+            id: r.get("id"),
+            score: r.get("score"),
+            properties: r.get("properties") ?? {},
+        }));
+        return { matchMode: mode === "substring" ? "exact" : "fuzzy", items };
+    }
+    async tierSemantic(params) {
+        const indexName = this.indexNames.vectorIndexName(params.entity.labelName);
+        const existing = await this.getExistingIndexes();
+        if (existing.size > 0 && !existing.has(indexName)) {
+            return { matchMode: "semantic", items: [] };
+        }
+        const queryEmbedding = await this.embedder.vectoriseText({ text: params.text });
+        const result = await this.neo4j.read(`
+      CALL db.index.vector.queryNodes($indexName, toInteger($overFetch), $queryEmbedding)
+      YIELD node, score
+      WHERE (node)-[:BELONGS_TO]->(:Company { id: $companyId })
+        AND score >= $minScore
+      RETURN node.id AS id, properties(node) AS properties, score
+      ORDER BY score DESC
+      LIMIT toInteger($limit)
+      `, {
+            indexName,
+            overFetch: GRAPH_VECTOR_OVERFETCH,
+            queryEmbedding,
+            companyId: params.companyId,
+            minScore: exports.GRAPH_SEMANTIC_MIN_SCORE,
+            limit: Math.min(params.limit, exports.GRAPH_SEMANTIC_MAX_RESULTS),
+        });
+        const items = result.records.map((r) => ({
+            id: r.get("id"),
+            score: r.get("score"),
+            properties: r.get("properties") ?? {},
+        }));
+        return { matchMode: items.length ? "semantic" : "none", items };
+    }
+};
+exports.GraphSearchService = GraphSearchService;
+exports.GraphSearchService = GraphSearchService = GraphSearchService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [neo4j_service_1.Neo4jService,
+        embedder_service_1.EmbedderService,
+        graph_index_manager_1.GraphIndexManager,
+        graph_catalog_service_1.GraphCatalogService])
+], GraphSearchService);
+//# sourceMappingURL=graph.search.service.js.map

package/dist/agents/graph/services/graph.search.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.search.service.js","sourceRoot":"","sources":["../../../../src/agents/graph/services/graph.search.service.ts"],"names":[],"mappings":"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"}

package/dist/agents/graph/services/humanize-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"humanize-tool.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/services/humanize-tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAuBjF"}

package/dist/agents/graph/services/humanize-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"humanize-tool.js","sourceRoot":"","sources":["../../../../src/agents/graph/services/humanize-tool.ts"],"names":[],"mappings":";;AAOA,oCAuBC;AA9BD;;;;;;GAMG;AACH,SAAgB,YAAY,CAAC,IAAY,EAAE,KAA8B;IACvE,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,gBAAgB,CAAC,CAAC,CAAC;YACtB,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,OAAO,cAAc,IAAI,GAAG,CAAC;QAC/B,CAAC;QACD,KAAK,iBAAiB;YACpB,OAAO,cAAc,IAAI,SAAS,CAAC;QACrC,KAAK,iBAAiB;YACpB,OAAO,aAAa,IAAI,EAAE,CAAC;QAC7B,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,MAAM,EAAE,GAAG,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,OAAO,WAAW,IAAI,MAAM,EAAE,EAAE,CAAC;QACnC,CAAC;QACD,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,IAAI,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,MAAM,GAAG,GAAG,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,OAAO,cAAc,IAAI,MAAM,GAAG,EAAE,CAAC;QACvC,CAAC;QACD;YACE,OAAO,WAAW,IAAI,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC"}

package/dist/agents/graph/services/materialise-bridge.d.ts

@@ -0,0 +1,36 @@
+import { CatalogEntity } from "../interfaces/graph.catalog.interface";
+import { GraphCatalogService } from "./graph.catalog.service";
+import { EntityServiceRegistry } from "../../../common/registries/entity.service.registry";
+import { UserContext } from "../tools/tool.factory";
+/** Hard cap per cardinality-many materialised relationship. */
+export declare const MATERIALISE_LIMIT = 50;
+export interface BridgeRecordIn {
+    id: string;
+    /** Already type-converted target-node fields, as returned by buildToolFieldsOutput. */
+    fields: Record<string, unknown>;
+}
+export interface BridgeRecordOut {
+    id: string;
+    type: string;
+    summary: string;
+    fields: Record<string, unknown>;
+    __materialised: string[];
+    __truncated?: Record<string, {
+        returned: number;
+        hasMore: true;
+    }>;
+    [key: string]: unknown;
+}
+export interface MaterialiseBridgeDeps {
+    catalog: GraphCatalogService;
+    registry: EntityServiceRegistry;
+}
+export declare function materialiseBridge(params: {
+    bridge: CatalogEntity;
+    record: BridgeRecordIn;
+    ctx: UserContext;
+    deps: MaterialiseBridgeDeps;
+    /** Counter used by the responder to populate trace.materialisedBridges. Optional. */
+    onMaterialised?: (relName: string, count: number) => void;
+}): Promise<BridgeRecordOut>;
+//# sourceMappingURL=materialise-bridge.d.ts.map

package/dist/agents/graph/services/materialise-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialise-bridge.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/services/materialise-bridge.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oDAAoD,CAAC;AAC3F,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKpD,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,uFAAuF;IACvF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IAElE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,QAAQ,EAAE,qBAAqB,CAAC;CACjC;AAED,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,GAAG,EAAE,WAAW,CAAC;IACjB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,qFAAqF;IACrF,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D,GAAG,OAAO,CAAC,eAAe,CAAC,CAsE3B"}

package/dist/agents/graph/services/materialise-bridge.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MATERIALISE_LIMIT = void 0;
+exports.materialiseBridge = materialiseBridge;
+const common_1 = require("@nestjs/common");
+const field_formatting_1 = require("./field-formatting");
+const logger = new common_1.Logger("materialiseBridge");
+/** Hard cap per cardinality-many materialised relationship. */
+exports.MATERIALISE_LIMIT = 50;
+async function materialiseBridge(params) {
+    const { bridge, record, ctx, deps } = params;
+    if (!bridge.bridge) {
+        throw new Error(`materialiseBridge called on non-bridge entity "${bridge.type}".`);
+    }
+    const summary = bridge.summary ? bridge.summary({ id: record.id, ...record.fields }) : record.id;
+    const out = {
+        id: record.id,
+        type: bridge.type,
+        summary: String(summary),
+        fields: record.fields,
+        __materialised: [],
+    };
+    for (const relName of bridge.bridge.materialiseTo) {
+        const rel = bridge.relationships.find((r) => r.name === relName);
+        if (!rel) {
+            // Should be impossible — defineEntity / catalog buildCatalog enforce this — but
+            // be defensive at runtime so a stale catalog doesn't crash a tool call.
+            logger.warn(`materialiseBridge: relationship "${relName}" not found on ${bridge.type}; skipping.`);
+            continue;
+        }
+        // Module-gated drop: target type the user can't access disappears from the response.
+        const target = deps.catalog.getEntityDetail(rel.targetType, ctx.userModuleIds);
+        if (!target) {
+            logger.debug(`materialiseBridge: target type ${rel.targetType} not accessible to user; dropping ${bridge.type}.${relName}`);
+            continue;
+        }
+        const targetSvc = deps.registry.get(target.type);
+        if (!targetSvc) {
+            logger.warn(`materialiseBridge: no service registered for ${target.type}; dropping ${bridge.type}.${relName}`);
+            continue;
+        }
+        const targetDirection = rel.cypherDirection === "out" ? "in" : "out";
+        const records = await targetSvc.findRelatedRecordsByEdge({
+            cypherLabel: rel.cypherLabel,
+            cypherDirection: targetDirection,
+            relatedLabel: bridge.labelName,
+            relatedId: record.id,
+            limit: exports.MATERIALISE_LIMIT + 1, // overfetch by one to detect truncation cheaply
+        });
+        const truncated = records.length > exports.MATERIALISE_LIMIT;
+        const visible = records.slice(0, exports.MATERIALISE_LIMIT);
+        const summariser = target.summary ?? ((d) => String(d.name ?? d.id));
+        const materialised = visible.map((r) => ({
+            id: r.id,
+            type: target.type,
+            summary: String(summariser(r)),
+            fields: (0, field_formatting_1.buildToolFieldsOutput)(target.fields, r),
+        }));
+        out[relName] = rel.cardinality === "one" ? (materialised[0] ?? null) : materialised;
+        out.__materialised.push(relName);
+        if (truncated) {
+            out.__truncated = out.__truncated ?? {};
+            out.__truncated[relName] = { returned: exports.MATERIALISE_LIMIT, hasMore: true };
+        }
+        params.onMaterialised?.(relName, materialised.length);
+    }
+    return out;
+}
+//# sourceMappingURL=materialise-bridge.js.map

package/dist/agents/graph/services/materialise-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialise-bridge.js","sourceRoot":"","sources":["../../../../src/agents/graph/services/materialise-bridge.ts"],"names":[],"mappings":"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"}

package/dist/agents/graph/tools/describe-entity.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/tools/describe-entity.tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE1E,QAAA,MAAM,WAAW;;iBAEf,CAAC;AAEH,qBACa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,WAAW;IAEjD,KAAK,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,qBAAqB;IASpE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CA6BjH"}

package/dist/agents/{chatbot → graph}/tools/describe-entity.tool.js

@@ -51,6 +51,7 @@ let DescribeEntityTool = class DescribeEntityTool {
                     cardinality: r.cardinality,
                     description: r.description,
                 })),
+                ...(entity.bridge ? { bridge: { materialiseTo: [...entity.bridge.materialiseTo] } } : {}),
             };
         }, recorder);
     }

package/dist/agents/graph/tools/describe-entity.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-entity.tool.js","sourceRoot":"","sources":["../../../../src/agents/graph/tools/describe-entity.tool.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAC5C,iDAA8D;AAC9D,6BAAwB;AACxB,iDAA0E;AAE1E,MAAM,WAAW,GAAG,OAAC,CAAC,MAAM,CAAC;IAC3B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;CAClE,CAAC,CAAC;AAGI,IAAM,kBAAkB,GAAxB,MAAM,kBAAkB;IAC7B,YAA6B,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;IAAG,CAAC;IAErD,KAAK,CAAC,GAAgB,EAAE,QAA0B;QAChD,OAAO,IAAI,6BAAqB,CAAC;YAC/B,IAAI,EAAE,iBAAiB;YACvB,WAAW,EAAE,oEAAoE;YACjF,MAAM,EAAE,WAAW;YACnB,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;SAC/E,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAkC,EAAE,GAAgB,EAAE,QAA0B;QAC3F,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CACzB,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,EAClC,KAAK,IAAI,EAAE;YACT,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC3D,IAAI,OAAO,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;YACrC,OAAO;gBACL,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAChC,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,WAAW,EAAE,CAAC,CAAC,WAAW;oBAC1B,UAAU,EAAE,CAAC,CAAC,UAAU;oBACxB,QAAQ,EAAE,CAAC,CAAC,QAAQ;oBACpB,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACpC,CAAC,CAAC;gBACH,aAAa,EAAE,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC9C,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,UAAU,EAAE,CAAC,CAAC,UAAU;oBACxB,WAAW,EAAE,CAAC,CAAC,WAAW;oBAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;iBAC3B,CAAC,CAAC;gBACH,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC1F,CAAC;QACJ,CAAC,EACD,QAAQ,CACT,CAAC;IACJ,CAAC;CACF,CAAA;AAzCY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,mBAAU,GAAE;qCAE2B,0BAAW;GADtC,kBAAkB,CAyC9B"}

package/dist/agents/{chatbot → graph}/tools/read-entity.tool.d.ts

@@ -1,6 +1,8 @@
 import { DynamicStructuredTool } from "@langchain/core/tools";
 import { z } from "zod";
 import { ToolFactory, ToolCallRecord, UserContext } from "./tool.factory";
+import { GraphCatalogService } from "../services/graph.catalog.service";
+import { EntityServiceRegistry } from "../../../common/registries/entity.service.registry";
 declare const inputSchema: z.ZodObject<{
     type: z.ZodString;
     id: z.ZodString;
@@ -8,7 +10,9 @@ declare const inputSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare class ReadEntityTool {
     private readonly factory;
-    constructor(factory: ToolFactory);
+    private readonly catalog;
+    private readonly registry;
+    constructor(factory: ToolFactory, catalog: GraphCatalogService, registry: EntityServiceRegistry);
     build(ctx: UserContext, recorder: ToolCallRecord[]): DynamicStructuredTool;
     invoke(input: z.infer<typeof inputSchema>, ctx: UserContext, recorder: ToolCallRecord[]): Promise<unknown>;
 }

package/dist/agents/graph/tools/read-entity.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/tools/read-entity.tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oDAAoD,CAAC;AAE3F,QAAA,MAAM,WAAW;;;;iBAIf,CAAC;AAEH,qBACa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFR,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,qBAAqB;IAGlD,KAAK,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,qBAAqB;IASpE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CA+FjH"}

package/dist/agents/{chatbot → graph}/tools/read-entity.tool.js

@@ -15,14 +15,19 @@ const tools_1 = require("@langchain/core/tools");
 const zod_1 = require("zod");
 const tool_factory_1 = require("./tool.factory");
 const field_formatting_1 = require("../services/field-formatting");
+const materialise_bridge_1 = require("../services/materialise-bridge");
+const graph_catalog_service_1 = require("../services/graph.catalog.service");
+const entity_service_registry_1 = require("../../../common/registries/entity.service.registry");
 const inputSchema = zod_1.z.object({
     type: zod_1.z.string(),
     id: zod_1.z.string(),
     include: zod_1.z.array(zod_1.z.string()).optional().describe("Relationship names to pull one-hop related records."),
 });
 let ReadEntityTool = class ReadEntityTool {
-    constructor(factory) {
+    constructor(factory, catalog, registry) {
         this.factory = factory;
+        this.catalog = catalog;
+        this.registry = registry;
     }
     build(ctx, recorder) {
         return new tools_1.DynamicStructuredTool({
@@ -33,16 +38,18 @@ let ReadEntityTool = class ReadEntityTool {
         });
     }
     async invoke(input, ctx, recorder) {
-        return this.factory.capture({ tool: "read_entity", input }, async () => {
+        const localMaterialised = [];
+        const result = await this.factory.capture({ tool: "read_entity", input }, async () => {
             const described = recorder.some((c) => c.tool === "describe_entity" && c.input.type === input.type);
+            const entity = this.factory.resolveEntity(input.type, ctx);
+            if ("error" in entity)
+                return entity;
             if (!described) {
                 return {
-                    error: `You must call describe_entity({ type: "${input.type}" }) before reading a ${input.type} record. The describe call returns the exact field names and relationships available — needed to interpret the response and construct any include argument.`,
+                    error: `You must call describe_entity({ type: "${input.type}" }) before reading a ${input.type} record. The schema is included below — either call describe_entity({ type: "${input.type}" }) to record the contract and retry this read, or proceed using the listed fields and relationships. Never stop on this error.`,
+                    schema: { fields: entity.fields, relationships: entity.relationships },
                 };
             }
-            const entity = this.factory.resolveEntity(input.type, ctx);
-            if ("error" in entity)
-                return entity;
             const validRels = new Set(entity.relationships.map((r) => r.name));
             for (const name of input.include ?? []) {
                 if (!validRels.has(name)) {
@@ -85,18 +92,40 @@ let ReadEntityTool = class ReadEntityTool {
                     }));
                 }
             }
+            const baseFields = (0, field_formatting_1.buildToolFieldsOutput)(entity.fields, record);
+            // Bridge fanout: if this entity is a bridge, replace the bare payload with
+            // the materialised one. The existing `include` block (if any) stacks on top
+            // as a sibling `related` map — it carries summary refs, while the bridge
+            // fanout fills full records at the top level. They do not collide.
+            if (entity.bridge) {
+                const materialised = await (0, materialise_bridge_1.materialiseBridge)({
+                    bridge: entity,
+                    record: { id: record.id, fields: baseFields },
+                    ctx,
+                    deps: { catalog: this.catalog, registry: this.registry },
+                    onMaterialised: (relName, count) => localMaterialised.push({ relName, count }),
+                });
+                return input.include?.length ? { ...materialised, related } : materialised;
+            }
             return {
                 id: record.id,
                 type: entity.type,
-                fields: (0, field_formatting_1.buildToolFieldsOutput)(entity.fields, record),
+                fields: baseFields,
                 ...(input.include?.length ? { related } : {}),
             };
         }, recorder);
+        // Attach materialised summary to the recorder entry that capture() just pushed.
+        if (localMaterialised.length && recorder.length) {
+            recorder[recorder.length - 1].materialised = localMaterialised;
+        }
+        return result;
     }
 };
 exports.ReadEntityTool = ReadEntityTool;
 exports.ReadEntityTool = ReadEntityTool = __decorate([
     (0, common_1.Injectable)(),
-    __metadata("design:paramtypes", [tool_factory_1.ToolFactory])
+    __metadata("design:paramtypes", [tool_factory_1.ToolFactory,
+        graph_catalog_service_1.GraphCatalogService,
+        entity_service_registry_1.EntityServiceRegistry])
 ], ReadEntityTool);
 //# sourceMappingURL=read-entity.tool.js.map

package/dist/agents/graph/tools/read-entity.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-entity.tool.js","sourceRoot":"","sources":["../../../../src/agents/graph/tools/read-entity.tool.ts"],"names":[],"mappings":"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"}

package/dist/agents/{chatbot → graph}/tools/resolve-entity.tool.d.ts

@@ -1,14 +1,14 @@
 import { DynamicStructuredTool } from "@langchain/core/tools";
 import { z } from "zod";
 import { ToolFactory, ToolCallRecord, UserContext } from "./tool.factory";
-import { ChatbotSearchService } from "../services/chatbot.search.service";
+import { GraphSearchService } from "../services/graph.search.service";
 declare const inputSchema: z.ZodObject<{
     text: z.ZodString;
 }, z.core.$strip>;
 export declare class ResolveEntityTool {
     private readonly factory;
     private readonly search;
-    constructor(factory: ToolFactory, search: ChatbotSearchService);
+    constructor(factory: ToolFactory, search: GraphSearchService);
     build(ctx: UserContext, recorder: ToolCallRecord[]): DynamicStructuredTool;
     invoke(input: z.infer<typeof inputSchema>, ctx: UserContext, recorder: ToolCallRecord[]): Promise<unknown>;
 }

package/dist/agents/graph/tools/resolve-entity.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/tools/resolve-entity.tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAEtE,QAAA,MAAM,WAAW;;iBAEf,CAAC;AAEH,qBACa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,kBAAkB;IAG7C,KAAK,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,qBAAqB;IAUpE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAYjH"}