@carlonicora/nestjs-neo4jsonapi 8.11.0 → 8.12.0

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

@@ -12,30 +12,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommunityRepository = exports.COMMUNITY_EXACT_SCAN_MAX_SCOPED_NODES = void 0;
 const common_1 = require("@nestjs/common");
 const crypto_1 = require("crypto");
+const nestjs_cls_1 = require("nestjs-cls");
 const registry_1 = require("../../../common/registries/registry");
 const agent_scope_filter_1 = require("../../../common/repositories/agent-scope.filter");
-const core_1 = require("../../../core");
+const embedder_service_1 = require("../../../core/llm/services/embedder.service");
+const model_service_1 = require("../../../core/llm/services/model.service");
+const abstract_repository_1 = require("../../../core/neo4j/abstracts/abstract.repository");
 const neo4j_service_1 = require("../../../core/neo4j/services/neo4j.service");
 const security_service_1 = require("../../../core/security/services/security.service");
-const community_model_1 = require("../entities/community.model");
+const company_meta_1 = require("../../company/entities/company.meta");
+const key_concept_meta_1 = require("../../keyconcept/entities/key.concept.meta");
+const key_concept_model_1 = require("../../keyconcept/entities/key.concept.model");
+const community_entity_1 = require("../entities/community.entity");
+const community_meta_1 = require("../entities/community.meta");
+const community_layer_service_1 = require("../services/community-layer.service");
 /**
  * Up to this many company/scope communities, `findByVector` ranks them by
  * exact cosine (no recall cliff). Above it, it falls back to the vector-index
  * over-fetch, which ranks globally and filters afterwards.
  */
 exports.COMMUNITY_EXACT_SCAN_MAX_SCOPED_NODES = 5000;
-let CommunityRepository = class CommunityRepository {
-    constructor(neo4j, embedderService, modelService, securityService, agentScope) {
-        this.neo4j = neo4j;
+const toNumber = (value) => value?.toNumber?.() ?? (value === null || value === undefined ? 0 : Number(value));
+/**
+ * Topic groups of key concepts, one set per company or per layer root (`CommunityLayerService`).
+ *
+ * Every match on a Community starts from `buildDefaultMatch()`, so the company predicate is the
+ * framework's. With no company in CLS that predicate matches every company: only
+ * `findAllStaleCommunities` (the cron) relies on it; every write throws instead.
+ */
+let CommunityRepository = class CommunityRepository extends abstract_repository_1.AbstractRepository {
+    constructor(neo4j, securityService, clsService, embedderService, modelService, agentScope, layer) {
+        super(neo4j, securityService, clsService);
         this.embedderService = embedderService;
         this.modelService = modelService;
-        this.securityService = securityService;
         this.agentScope = agentScope;
+        this.layer = layer;
+        this.descriptor = community_entity_1.CommunityDescriptor;
     }
     async onModuleInit() {
-        await this.neo4j.writeOne({
-            query: `CREATE CONSTRAINT community_id IF NOT EXISTS FOR (community:Community) REQUIRE community.id IS UNIQUE`,
-        });
+        await super.onModuleInit();
         const dimensions = this.modelService.getEmbedderDimensions();
         await this.neo4j.writeOne({
             query: `
@@ -49,30 +64,36 @@ let CommunityRepository = class CommunityRepository {
           `,
         });
     }
+    /** A query on the Community serialiser, refused when no company is in context (writes). */
+    writeQuery(method) {
+        const query = this.neo4j.initQuery({ serialiser: community_entity_1.CommunityDescriptor.model });
+        if (!query.queryParams.companyId)
+            throw new Error(`CommunityRepository.${method}: no company in context`);
+        return query;
+    }
+    readQuery() {
+        return this.neo4j.initQuery({ serialiser: community_entity_1.CommunityDescriptor.model });
+    }
     /**
-     * Create a new community node with BELONGS_TO company relationship
-     * Uses companyId from CLS (current request context)
-     */
-    /**
-     * `scopeRoot` ties the community to the scope root its members were detected
-     * within. Communities are built per scope root precisely so a scoped run can
-     * be answered from communities that contain nothing from a sibling root;
-     * without the edge, `findByVector` has no way to tell them apart and the
-     * whole partition is decorative.
+     * `scopeRoot` ties the group to the layer root its members were detected within. Its `label`
+     * is ignored: the label comes from the layer. A `scopeRoot` with no layer configured throws.
      */
     async createCommunity(params) {
-        const query = this.neo4j.initQuery({ serialiser: community_model_1.CommunityModel });
-        const id = (0, crypto_1.randomUUID)();
+        const query = this.writeQuery("createCommunity");
+        const layer = await this.layer.ready();
+        if (params.scopeRoot && !layer)
+            throw new Error("CommunityRepository.createCommunity: scopeRoot passed but no community layer is configured");
+        if (params.scopeRoot && layer)
+            await this.neo4j.validateRelatedNodes({ nodes: [{ id: params.scopeRoot.id, label: layer.labelName }] });
         query.queryParams = {
             ...query.queryParams,
-            id,
+            id: (0, crypto_1.randomUUID)(),
             name: params.name,
             level: params.level,
             memberCount: params.memberCount,
             rating: params.rating ?? 0,
             scopeRootId: params.scopeRoot?.id ?? null,
         };
-        // Guarded: initQuery() binds this variable only when the id is in CLS; an unbound CREATE target creates an orphan node.
         query.query += `
       CREATE (community:Community {
         id: $id,
@@ -85,242 +106,213 @@ let CommunityRepository = class CommunityRepository {
         createdAt: datetime(),
         updatedAt: datetime()
       })
-      ${query.queryParams.companyId ? `CREATE (community)-[:BELONGS_TO]->(company)` : ``}
-      ${params.scopeRoot
+      CREATE (community)-[:BELONGS_TO]->(company)
+      ${params.scopeRoot && layer
             ? `WITH community
-      MATCH (scopeRoot:${params.scopeRoot.label} { id: $scopeRootId })
+      MATCH (scopeRoot:${layer.labelName} { id: $scopeRootId })
       CREATE (community)-[:SCOPED_TO]->(scopeRoot)`
             : ``}
       RETURN community
     `;
         return this.neo4j.writeOne(query);
     }
-    /**
-     * Update community members (HAS_MEMBER relationships to KeyConcepts)
-     */
+    /** Replaces the group's HAS_MEMBER edges. */
     async updateCommunityMembers(params) {
-        // First, remove existing HAS_MEMBER relationships
-        const removeQuery = this.neo4j.initQuery();
-        removeQuery.queryParams = { ...removeQuery.queryParams, communityId: params.communityId };
+        const removeQuery = this.writeQuery("updateCommunityMembers");
+        removeQuery.queryParams = { ...removeQuery.queryParams, searchValue: params.communityId };
         removeQuery.query += `
-      MATCH (community:Community {id: $communityId})-[r:HAS_MEMBER]->()
+      ${this.buildDefaultMatch({ searchField: "id" })}
+      MATCH (community)-[r:HAS_MEMBER]->()
       DELETE r
     `;
+        if (params.keyConceptIds.length > 0)
+            await this.neo4j.validateRelatedNodes({
+                nodes: params.keyConceptIds.map((id) => ({ id, label: key_concept_meta_1.keyConceptMeta.labelName })),
+            });
         await this.neo4j.writeOne(removeQuery);
-        // Then, create new HAS_MEMBER relationships
-        if (params.keyConceptIds.length > 0) {
-            const addQuery = this.neo4j.initQuery();
-            addQuery.queryParams = {
-                ...addQuery.queryParams,
-                communityId: params.communityId,
-                keyConceptIds: params.keyConceptIds,
-            };
-            addQuery.query += `
-        MATCH (community:Community {id: $communityId})
-        MATCH (keyconcept:KeyConcept) WHERE keyconcept.id IN $keyConceptIds
-        MERGE (community)-[:HAS_MEMBER]->(keyconcept)
-      `;
-            await this.neo4j.writeOne(addQuery);
-            // Update memberCount
-            const updateCountQuery = this.neo4j.initQuery();
-            updateCountQuery.queryParams = {
-                ...updateCountQuery.queryParams,
-                communityId: params.communityId,
-                memberCount: params.keyConceptIds.length,
-            };
-            updateCountQuery.query += `
-        MATCH (community:Community {id: $communityId})
-        SET community.memberCount = $memberCount
-      `;
-            await this.neo4j.writeOne(updateCountQuery);
-        }
+        if (params.keyConceptIds.length === 0)
+            return;
+        const addQuery = this.writeQuery("updateCommunityMembers");
+        addQuery.queryParams = {
+            ...addQuery.queryParams,
+            searchValue: params.communityId,
+            keyConceptIds: params.keyConceptIds,
+            memberCount: params.keyConceptIds.length,
+        };
+        addQuery.query += `
+      ${this.buildDefaultMatch({ searchField: "id" })}
+      SET community.memberCount = $memberCount
+      WITH community
+      MATCH (keyconcept:KeyConcept) WHERE keyconcept.id IN $keyConceptIds
+      MERGE (community)-[:HAS_MEMBER]->(keyconcept)
+    `;
+        await this.neo4j.writeOne(addQuery);
     }
-    /**
-     * Set PARENT_OF relationship between communities (hierarchy)
-     */
+    /** PARENT_OF between two groups of the same company. */
     async setParentCommunity(params) {
-        const query = this.neo4j.initQuery();
+        const query = this.writeQuery("setParentCommunity");
+        await this.neo4j.validateRelatedNodes({
+            nodes: [{ id: params.parentCommunityId, label: community_meta_1.communityMeta.labelName }],
+        });
         query.queryParams = {
             ...query.queryParams,
-            childCommunityId: params.childCommunityId,
+            searchValue: params.childCommunityId,
             parentCommunityId: params.parentCommunityId,
         };
         query.query += `
+      ${this.buildDefaultMatch({ searchField: "id" })}
       MATCH (parent:Community {id: $parentCommunityId})
-      MATCH (child:Community {id: $childCommunityId})
-      MERGE (parent)-[:PARENT_OF]->(child)
+      WHERE EXISTS { MATCH (parent)-[:BELONGS_TO]-(company) }
+      MERGE (parent)-[:PARENT_OF]->(community)
     `;
         await this.neo4j.writeOne(query);
     }
-    /**
-     * Mark communities as stale (needs reprocessing)
-     */
+    /** Marks groups as stale (needs reprocessing). */
     async markAsStale(communityIds) {
         if (communityIds.length === 0)
             return;
-        const query = this.neo4j.initQuery();
-        query.queryParams = {
-            ...query.queryParams,
-            communityIds,
-        };
+        const query = this.writeQuery("markAsStale");
+        query.queryParams = { ...query.queryParams, communityIds };
         query.query += `
-      MATCH (community:Community) WHERE community.id IN $communityIds
+      ${this.buildDefaultMatch()}
+      WHERE community.id IN $communityIds
       SET community.isStale = true, community.staleSince = datetime(), community.updatedAt = datetime()
     `;
         await this.neo4j.writeOne(query);
     }
     /**
-     * Mark a community as deferred for lack of credits — the summariser cron
-     * skips it (via `findAllStaleCommunities`'s WHERE clause) until approval
-     * clears the flag (spec §2: a fresh top-up must not be silently eaten).
+     * Defers a group for lack of credits: the summariser cron skips it (`findAllStaleCommunities`)
+     * until approval clears the flag (spec §2: a fresh top-up must not be silently eaten).
      */
     async markPendingCredits(communityId) {
-        const query = this.neo4j.initQuery();
-        query.queryParams = { ...query.queryParams, communityId };
+        const query = this.writeQuery("markPendingCredits");
+        query.queryParams = { ...query.queryParams, searchValue: communityId };
         query.query += `
-      MATCH (community:Community { id: $communityId })-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch({ searchField: "id" })}
       SET community.pendingCredits = true, community.updatedAt = datetime()
     `;
         await this.neo4j.writeOne(query);
     }
-    /**
-     * Approval: clear the flag for the current company (from CLS); returns the
-     * cleared community ids so the caller can re-enqueue them.
-     */
+    /** Approval: clears the flag for the current company; returns the cleared ids so the caller can re-enqueue them. */
     async clearPendingCredits() {
-        // Read the ids first, then clear the flag. A single `SET ... RETURN` cannot
-        // go through `neo4j.read()` (Neo4j rejects writes in a read transaction:
-        // "Writing in read access mode not allowed"), and the public write helpers
-        // only return rows when given a serialiser — which this projection has no
-        // use for.
-        const readQuery = this.neo4j.initQuery();
+        const readQuery = this.writeQuery("clearPendingCredits");
         readQuery.query += `
-      MATCH (community:Community { pendingCredits: true })-[:BELONGS_TO]->(company)
-      RETURN community.id AS communityId
+      ${this.buildDefaultMatch()}
+      WHERE community.pendingCredits = true
+      RETURN community
     `;
-        const result = await this.neo4j.read(readQuery.query, readQuery.queryParams);
-        const communityIds = result.records.map((record) => record.get("communityId"));
+        const pending = await this.neo4j.readMany(readQuery);
+        const communityIds = pending.map((community) => community.id);
         if (communityIds.length === 0)
             return [];
-        const writeQuery = this.neo4j.initQuery();
+        const writeQuery = this.writeQuery("clearPendingCredits");
         writeQuery.queryParams = { ...writeQuery.queryParams, communityIds };
         writeQuery.query += `
-      MATCH (community:Community)-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch()}
       WHERE community.id IN $communityIds
       SET community.pendingCredits = false, community.updatedAt = datetime()
     `;
         await this.neo4j.writeOne(writeQuery);
         return communityIds;
     }
-    /**
-     * Backlog count for the current company (from CLS) — mirrors countStaleCommunities.
-     */
+    /** Backlog count for the current company (mirrors countStaleCommunities). */
     async countPendingCredits() {
-        const query = this.neo4j.initQuery();
+        const query = this.readQuery();
         query.query += `
-      MATCH (community:Community { pendingCredits: true })-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch()}
+      WHERE community.pendingCredits = true
       RETURN COUNT(community) AS count
     `;
-        const result = await this.neo4j.read(query.query, query.queryParams);
-        const count = result.records[0]?.get("count");
-        return count?.toNumber?.() ?? count ?? 0;
+        const result = await this.neo4j.read(query.query, query.queryParams); // nja-lint-ignore: scalar read, no node to map (Carlo, 2026-10-28, WYR-10 spec D4)
+        return toNumber(result.records[0]?.get("count"));
     }
-    /**
-     * Count stale communities for the current company (from CLS)
-     */
+    /** Stale groups of the current company. */
     async countStaleCommunities() {
-        const query = this.neo4j.initQuery();
+        const query = this.readQuery();
         query.query += `
-      MATCH (community:Community {isStale: true})-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch()}
+      WHERE community.isStale = true
       RETURN COUNT(community) AS count
     `;
-        const result = await this.neo4j.read(query.query, query.queryParams);
-        const count = result.records[0]?.get("count");
-        return count?.toNumber?.() ?? count ?? 0;
+        const result = await this.neo4j.read(query.query, query.queryParams); // nja-lint-ignore: scalar read, no node to map (Carlo, 2026-10-28, WYR-10 spec D4)
+        return toNumber(result.records[0]?.get("count"));
     }
     /**
-     * Find all stale communities with their company IDs (for cron job enqueuing)
-     * No CLS context needed - returns cross-company results
+     * Stale groups with their company ids, for the cron. Runs with no company in CLS, so the
+     * default match spans every company (spec D5: no admin repository).
      */
     async findAllStaleCommunities() {
-        const query = this.neo4j.initQuery();
+        const query = this.readQuery();
         query.query += `
-      MATCH (community:Community {isStale: true})-[:BELONGS_TO]->(company)
-      WHERE community.pendingCredits IS NULL OR community.pendingCredits = false
-      RETURN community.id AS communityId, company.id AS companyId
+      ${this.buildDefaultMatch()}
+      WHERE community.isStale = true
+        AND (community.pendingCredits IS NULL OR community.pendingCredits = false)
+      MATCH (community)-[:BELONGS_TO]->(${community_meta_1.communityMeta.nodeName}_${company_meta_1.companyMeta.nodeName}:${company_meta_1.companyMeta.labelName})
+      RETURN community, ${community_meta_1.communityMeta.nodeName}_${company_meta_1.companyMeta.nodeName}
       ORDER BY community.staleSince ASC
     `;
-        const result = await this.neo4j.read(query.query, query.queryParams);
-        return result.records.map((record) => ({
-            communityId: record.get("communityId"),
-            companyId: record.get("companyId"),
-        }));
+        const communities = await this.neo4j.readMany(query);
+        return communities.map((community) => ({ communityId: community.id, companyId: community.company?.id }));
     }
     /**
-     * The scope root a community was detected under (its `SCOPED_TO` target),
-     * for the current company (from CLS). `rootLabels` are the scope-root labels
-     * the caller knows (the graph catalog's roots); each is read as a typed node
-     * with its registered model's serialiser. `null` when the community has no
-     * scope root among them, or no company is in CLS. Both the community and the
-     * root must belong to the CLS company.
+     * The layer root a group was detected under (its SCOPED_TO target), for the current company.
+     * `null` on the company layer, with no company in CLS, or when the group has no root.
+     *
+     * @deprecated rootLabels — accepted and ignored: the layer comes from CommunityLayerService.
      */
     async findScopeRootForCommunity(params) {
-        for (const label of params.rootLabels) {
-            const model = registry_1.modelRegistry.getByLabelName(label);
-            if (!model)
-                continue;
-            const query = this.neo4j.initQuery({ serialiser: model });
-            if (!query.queryParams.companyId)
-                return null;
-            query.queryParams = { ...query.queryParams, communityId: params.communityId };
-            query.query += `
-        MATCH (community:Community { id: $communityId })-[:BELONGS_TO]->(company)
-        MATCH (community)-[:SCOPED_TO]->(${model.nodeName}:${model.labelName})-[:BELONGS_TO]->(company)
-        RETURN ${model.nodeName}
-      `;
-            const root = await this.neo4j.readOne(query);
-            if (root?.id)
-                return { id: root.id, type: model.type, label: model.labelName };
-        }
-        return null;
+        const layer = await this.layer.ready();
+        if (!layer)
+            return null;
+        const model = registry_1.modelRegistry.getByLabelName(layer.labelName);
+        if (!model)
+            return null;
+        const query = this.neo4j.initQuery({ serialiser: model });
+        if (!query.queryParams.companyId)
+            return null;
+        query.queryParams = { ...query.queryParams, searchValue: params.communityId };
+        query.query += `
+      ${this.buildDefaultMatch({ searchField: "id" })}
+      MATCH (community)-[:SCOPED_TO]->(${layer.nodeName}:${layer.labelName})
+      WHERE EXISTS { MATCH (${layer.nodeName})-[:BELONGS_TO]-(company) }
+      RETURN ${layer.nodeName}
+    `;
+        const root = await this.neo4j.readOne(query);
+        return root?.id ? { id: root.id, type: layer.type, label: layer.labelName } : null;
     }
     /**
-     * Delete every community detected under one scope root, for the current
-     * company (from CLS). Communities of other roots, and unpartitioned ones,
-     * are left alone. Does nothing when no company is in CLS.
+     * Deletes every group detected under one layer root, for the current company. A scope of
+     * another type than the layer (or no layer) does nothing; the label comes from the layer.
      */
     async deleteCommunitiesForScope(params) {
-        // The label goes into the query text, so it must be a registered model's.
-        const model = registry_1.modelRegistry.getByLabelName(params.scope.label);
-        if (!model)
-            return;
-        const query = this.neo4j.initQuery({ serialiser: community_model_1.CommunityModel });
+        const query = this.readQuery();
+        // No company in CLS: refuse with a no-op, never a delete across every company.
         if (!query.queryParams.companyId)
             return;
+        const layer = await this.layer.ready();
+        if (!layer || params.scope.type !== layer.type)
+            return;
         query.queryParams = { ...query.queryParams, scopeRootId: params.scope.id };
         query.query += `
-      MATCH (scopeRoot:${model.labelName} { id: $scopeRootId })-[:BELONGS_TO]->(company)
-      MATCH (community:Community)-[:SCOPED_TO]->(scopeRoot)
-      MATCH (community)-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch()}
+      WHERE EXISTS { MATCH (community)-[:SCOPED_TO]->(:${layer.labelName} { id: $scopeRootId }) }
       DETACH DELETE community
     `;
         await this.neo4j.writeOne(query);
     }
-    /**
-     * Update community summary, embedding, and mark as not stale
-     */
+    /** Writes the summary and embedding and clears the stale flag. */
     async updateSummary(params) {
-        const query = this.neo4j.initQuery();
+        const query = this.writeQuery("updateSummary");
         query.queryParams = {
             ...query.queryParams,
-            communityId: params.communityId,
+            searchValue: params.communityId,
             name: params.name,
             summary: params.summary,
             embedding: params.embedding,
             rating: params.rating,
         };
         query.query += `
-      MATCH (community:Community {id: $communityId})
+      ${this.buildDefaultMatch({ searchField: "id" })}
       SET community.name = $name,
           community.summary = $summary,
           community.embedding = $embedding,
@@ -333,54 +325,64 @@ let CommunityRepository = class CommunityRepository {
     `;
         await this.neo4j.writeOne(query);
     }
+    /** Clears the stale flag without summarising (credit backlog discard). */
+    async clearStaleness(params) {
+        if (params.communityIds.length === 0)
+            return;
+        const query = this.writeQuery("clearStaleness");
+        query.queryParams = { ...query.queryParams, communityIds: params.communityIds };
+        query.query += `
+      ${this.buildDefaultMatch()}
+      WHERE community.id IN $communityIds
+      SET community.isStale = false, community.staleSince = null, community.updatedAt = datetime()
+    `;
+        await this.neo4j.writeOne(query);
+    }
     /**
-     * Find communities by vector similarity search
-     * Filters by company from CLS context
-     */
-    /**
-     * FAIL CLOSED on scope. A community summarises many members at once, so a
-     * single unscoped hit hands the answer content from every scope root it drew
-     * on. In a scoped run only communities detected within that exact root are
-     * eligible; a community with no `SCOPED_TO` edge predates the partition and
-     * is therefore assumed to mix roots.
+     * Vector search over the current company's groups.
+     *
+     * FAIL CLOSED on scope. A group summarises many members at once, so in a scoped chat only
+     * groups detected within that exact root are eligible. A chat scoped to a type other than the
+     * layer (or any scoped chat on the company layer) gets nothing: its groups mix roots.
      */
     async findByVector(params) {
         const scope = this.agentScope.current();
-        let whereClause = "WHERE community.embedding IS NOT NULL AND community.isStale = false";
-        if (params.level !== undefined) {
-            whereClause += " AND community.level = $level";
-        }
-        if (scope) {
-            whereClause += ` AND EXISTS { MATCH (community)-[:SCOPED_TO]->(:${scope.label} { id: $agentScopeId }) }`;
-        }
+        const layer = await this.layer.ready();
+        if (scope && (!layer || scope.type !== layer.type))
+            return [];
+        const countQuery = this.readQuery();
+        if (!countQuery.queryParams.companyId)
+            return [];
+        const conditions = ["community.embedding IS NOT NULL", "community.isStale = false"];
+        if (params.level !== undefined)
+            conditions.push("community.level = $level");
+        if (scope && layer)
+            conditions.push(`EXISTS { MATCH (community)-[:SCOPED_TO]->(:${layer.labelName} { id: $agentScopeId }) }`);
         const filterParams = {
             embedding: params.embedding,
             topK: params.topK,
             level: params.level,
             ...(scope ? { agentScopeId: scope.id } : {}),
         };
-        // How large is the company's (and scope's) set? The vector index ranks
-        // ALL companies first and filters afterwards, so identical content in
-        // other companies can push this company's communities out of the
-        // candidates. Small sets are ranked by exact cosine; the index only above
-        // the threshold (mirrors ChunkRepository.findPotentialChunks).
-        const countQuery = this.neo4j.initQuery();
+        // The vector index ranks ALL companies first and filters afterwards, so identical content
+        // in other companies can push this company's groups out of the candidates. Small sets are
+        // ranked by exact cosine; the index only above the threshold (mirrors ChunkRepository).
         countQuery.queryParams = { ...countQuery.queryParams, ...filterParams };
         countQuery.query += `
-      MATCH (community:Community)-[:BELONGS_TO]->(company)
-      ${whereClause}
+      ${this.buildDefaultMatch()}
+      WHERE ${conditions.join(" AND ")}
       RETURN count(community) AS scopedCount
     `;
-        const countResult = await this.neo4j.read(countQuery.query, countQuery.queryParams);
-        const scopedCount = Number(countResult?.records?.[0]?.get("scopedCount") ?? 0);
+        const countResult = await this.neo4j.read(countQuery.query, countQuery.queryParams); // nja-lint-ignore: scalar read, no node to map (Carlo, 2026-10-28, WYR-10 spec D4)
+        const scopedCount = toNumber(countResult?.records?.[0]?.get("scopedCount"));
         if (scopedCount === 0)
             return [];
-        const query = this.neo4j.initQuery({ serialiser: community_model_1.CommunityModel });
+        const query = this.readQuery();
         query.queryParams = { ...query.queryParams, ...filterParams };
         if (scopedCount <= exports.COMMUNITY_EXACT_SCAN_MAX_SCOPED_NODES) {
             query.query += `
-      MATCH (community:Community)-[:BELONGS_TO]->(company)
-      ${whereClause}
+      ${this.buildDefaultMatch()}
+      WHERE ${conditions.join(" AND ")}
       WITH community, vector.similarity.cosine(community.embedding, $embedding) AS score
       RETURN community, score
       ORDER BY score DESC
@@ -388,68 +390,58 @@ let CommunityRepository = class CommunityRepository {
     `;
             return this.neo4j.readMany(query);
         }
+        // nja-lint-ignore: vector index CALL precedes the default match (Carlo, 2026-10-28, WYR-10 O3)
         query.query += `
       CALL db.index.vector.queryNodes('communities', $topK * 2, $embedding)
       YIELD node AS community, score
-      MATCH (community)-[:BELONGS_TO]->(company)
-      ${whereClause}
+      WHERE EXISTS { MATCH (community)-[:BELONGS_TO]-(company) } AND ${conditions.join(" AND ")}
       RETURN community, score
       ORDER BY score DESC
       LIMIT toInteger($topK)
     `;
         return this.neo4j.readMany(query);
     }
-    /**
-     * Find communities by hierarchy level
-     * Filters by company from CLS context
-     */
+    /** Groups of one hierarchy level, for the current company. */
     async findByLevel(params) {
-        const query = this.neo4j.initQuery({ serialiser: community_model_1.CommunityModel });
-        query.queryParams = {
-            ...query.queryParams,
-            level: params.level,
-        };
+        const query = this.readQuery();
+        query.queryParams = { ...query.queryParams, level: params.level };
         query.query += `
-      MATCH (community:Community)-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch()}
       WHERE community.level = $level
       RETURN community
       ORDER BY community.rating DESC
     `;
         return this.neo4j.readMany(query);
     }
-    /**
-     * Find member KeyConcepts for a community
-     */
+    /** Member key concepts of a group. */
     async findMemberKeyConcepts(communityId) {
-        const query = this.neo4j.initQuery();
-        query.queryParams = { ...query.queryParams, communityId };
+        const query = this.neo4j.initQuery({ serialiser: key_concept_model_1.KeyConceptModel });
+        query.queryParams = { ...query.queryParams, searchValue: communityId };
         query.query += `
-      MATCH (community:Community {id: $communityId})-[:HAS_MEMBER]->(keyconcept:KeyConcept)
-      RETURN keyconcept.id AS id, keyconcept.value AS value, keyconcept.description AS description
+      ${this.buildDefaultMatch({ searchField: "id" })}
+      MATCH (community)-[:HAS_MEMBER]->(keyconcept:KeyConcept)
+      RETURN keyconcept
     `;
-        // Use raw read() to avoid entity serialization - we just need properties
-        const result = await this.neo4j.read(query.query, query.queryParams);
-        return result.records.map((record) => ({
-            id: record.get("id"),
-            value: record.get("value"),
-            description: record.get("description") ?? undefined,
+        const keyConcepts = await this.neo4j.readMany(query);
+        return keyConcepts.map((keyConcept) => ({
+            id: keyConcept.id,
+            value: keyConcept.value,
+            description: keyConcept.description ?? undefined,
         }));
     }
-    /**
-     * Get KeyConceptRelationships between community members
-     */
+    /** KeyConceptRelationships between a group's members. */
     async findMemberRelationships(communityId) {
-        const query = this.neo4j.initQuery();
-        query.queryParams = { ...query.queryParams, communityId };
+        const query = this.readQuery();
+        query.queryParams = { ...query.queryParams, searchValue: communityId };
         query.query += `
-      MATCH (community:Community {id: $communityId})-[:HAS_MEMBER]->(kc1:KeyConcept)
+      ${this.buildDefaultMatch({ searchField: "id" })}
+      MATCH (community)-[:HAS_MEMBER]->(kc1:KeyConcept)
       MATCH (community)-[:HAS_MEMBER]->(kc2:KeyConcept)
       MATCH (kc1)<-[:RELATES_TO]-(rel:KeyConceptRelationship)-[:RELATES_TO]->(kc2)
       WHERE kc1.value < kc2.value
       RETURN kc1.value AS keyConcept1, kc2.value AS keyConcept2, rel.weight AS weight
     `;
-        // Use raw read() to avoid entity serialization - we just need properties
-        const result = await this.neo4j.read(query.query, query.queryParams);
+        const result = await this.neo4j.read(query.query, query.queryParams); // nja-lint-ignore: scalar read, no node to map (Carlo, 2026-10-28, WYR-10 spec D4)
         return result.records.map((record) => {
             const weight = record.get("weight");
             return {
@@ -459,153 +451,153 @@ let CommunityRepository = class CommunityRepository {
             };
         });
     }
-    /**
-     * Get parent community chain (hierarchy)
-     */
+    /** The group and its parent chain, top level first. */
     async getHierarchy(communityId) {
-        const query = this.neo4j.initQuery({ serialiser: community_model_1.CommunityModel });
-        query.queryParams = { ...query.queryParams, communityId };
+        const query = this.readQuery();
+        query.queryParams = { ...query.queryParams, searchValue: communityId };
         query.query += `
-      MATCH (child:Community {id: $communityId})
-      MATCH path = (parent:Community)-[:PARENT_OF*]->(child)
-      UNWIND nodes(path) AS community
-      RETURN DISTINCT community
+      ${this.buildDefaultMatch({ searchField: "id" })}
+      MATCH path = (parent:Community)-[:PARENT_OF*]->(community)
+      WHERE all(node IN nodes(path) WHERE EXISTS { MATCH (node)-[:BELONGS_TO]-(company) })
+      UNWIND nodes(path) AS member
+      RETURN DISTINCT member AS community
       ORDER BY community.level DESC
     `;
         return this.neo4j.readMany(query);
     }
-    /**
-     * Get child communities
-     */
+    /** Child groups of a group. */
     async getChildren(communityId) {
-        const query = this.neo4j.initQuery({ serialiser: community_model_1.CommunityModel });
-        query.queryParams = { ...query.queryParams, communityId };
+        const query = this.readQuery();
+        query.queryParams = { ...query.queryParams, searchValue: communityId };
         query.query += `
-      MATCH (parent:Community {id: $communityId})-[:PARENT_OF]->(child:Community)
+      ${this.buildDefaultMatch({ searchField: "id" })}
+      MATCH (community)-[:PARENT_OF]->(child:Community)
+      WHERE EXISTS { MATCH (child)-[:BELONGS_TO]-(company) }
       RETURN child AS community
-      ORDER BY child.rating DESC
+      ORDER BY community.rating DESC
     `;
         return this.neo4j.readMany(query);
     }
-    /**
-     * Delete a community and its relationships
-     */
+    /** Deletes one group of the current company. */
     async deleteCommunity(communityId) {
-        const query = this.neo4j.initQuery();
-        query.queryParams = { ...query.queryParams, communityId };
+        const query = this.writeQuery("deleteCommunity");
+        query.queryParams = { ...query.queryParams, searchValue: communityId };
         query.query += `
-      MATCH (community:Community {id: $communityId})
+      ${this.buildDefaultMatch({ searchField: "id" })}
       DETACH DELETE community
     `;
         await this.neo4j.writeOne(query);
     }
-    /**
-     * Delete all communities for the current company (from CLS)
-     */
+    /** Deletes every group of the current company. */
     async deleteAllCommunities() {
-        const query = this.neo4j.initQuery();
+        const query = this.writeQuery("deleteAllCommunities");
         query.query += `
-      MATCH (community:Community)-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch()}
       DETACH DELETE community
     `;
         await this.neo4j.writeOne(query);
     }
-    /**
-     * Find communities that contain a specific KeyConcept
-     */
+    /** Groups of the current company that contain a key concept. */
     async findCommunitiesByKeyConcept(keyConceptId) {
-        const query = this.neo4j.initQuery({ serialiser: community_model_1.CommunityModel });
+        const query = this.readQuery();
         query.queryParams = { ...query.queryParams, keyConceptId };
         query.query += `
-      MATCH (community:Community)-[:HAS_MEMBER]->(keyconcept:KeyConcept {id: $keyConceptId})
-      MATCH (community)-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch()}
+      MATCH (community)-[:HAS_MEMBER]->(:KeyConcept {id: $keyConceptId})
       RETURN community
       ORDER BY community.level ASC
     `;
         return this.neo4j.readMany(query);
     }
-    /**
-     * Count communities by level for the current company (from CLS)
-     */
+    /** Group counts per level for the current company. */
     async countByLevel() {
-        const query = this.neo4j.initQuery();
+        const query = this.readQuery();
         query.query += `
-      MATCH (community:Community)-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch()}
       RETURN community.level AS level, COUNT(community) AS count
       ORDER BY level ASC
     `;
-        // Use raw read() to avoid entity serialization - we just need counts
-        const result = await this.neo4j.read(query.query, query.queryParams);
-        return result.records.map((record) => {
-            const level = record.get("level");
-            const count = record.get("count");
-            return {
-                level: level?.toNumber?.() ?? level ?? 0,
-                count: count?.toNumber?.() ?? count ?? 0,
-            };
-        });
+        const result = await this.neo4j.read(query.query, query.queryParams); // nja-lint-ignore: scalar read, no node to map (Carlo, 2026-10-28, WYR-10 spec D4)
+        return result.records.map((record) => ({
+            level: toNumber(record.get("level")),
+            count: toNumber(record.get("count")),
+        }));
+    }
+    async findById(params) {
+        if (typeof params === "string")
+            return this.findCommunityById(params);
+        return super.findById(params);
     }
     /**
-     * Find community by ID with company scope from CLS
+     * Ids of the layer's root nodes the current company owns. `[]` on the company layer
+     * or with no company in CLS. The label comes from the layer, never from a caller.
      */
-    async findById(communityId) {
-        const query = this.neo4j.initQuery({ serialiser: community_model_1.CommunityModel });
-        query.queryParams = { ...query.queryParams, communityId };
+    async findLayerRootIds() {
+        const layer = await this.layer.ready();
+        if (!layer)
+            return [];
+        const model = registry_1.modelRegistry.getByLabelName(layer.labelName);
+        if (!model)
+            return [];
+        const query = this.neo4j.initQuery({ serialiser: model });
+        if (!query.queryParams.companyId)
+            return [];
+        query.query += `
+      MATCH (${layer.nodeName}:${layer.labelName})
+      WHERE EXISTS { MATCH (${layer.nodeName})-[:BELONGS_TO]-(company) }
+      RETURN ${layer.nodeName}
+    `;
+        const roots = await this.neo4j.readMany(query);
+        return roots.map((root) => root.id).filter((id) => typeof id === "string");
+    }
+    /** One group of the current company, or `null`. */
+    async findCommunityById(communityId) {
+        const query = this.readQuery();
+        query.queryParams = { ...query.queryParams, searchValue: communityId };
         query.query += `
-      MATCH (community:Community {id: $communityId})-[:BELONGS_TO]->(company)
+      ${this.buildDefaultMatch({ searchField: "id" })}
       RETURN community
     `;
         return this.neo4j.readOne(query);
     }
     /**
-     * Find communities that contain KeyConcepts related to a given KeyConcept
-     * Returns affinity scores based on relationship count and weight
-     */
-    /**
-     * `scopeRoot` keeps incremental assignment inside its partition.
+     * Groups holding key concepts related to a given one, with affinity totals.
      *
-     * KeyConcept nodes are globally de-duplicated by value, so a concept two
-     * scope roots happen to share relates to members of BOTH their communities.
-     * Without this filter the incremental path quietly re-mixes what detection
-     * partitioned, and the mixing compounds on every ingest.
+     * `scopeRoot` keeps incremental assignment inside its partition: key concepts are shared by
+     * value, so a concept two roots share relates to members of both their groups. Its `label` is
+     * ignored (the layer's is used); with no layer no scope filter applies.
      */
     async findCommunitiesByRelatedKeyConcepts(keyConceptId, scopeRoot) {
-        const query = this.neo4j.initQuery();
+        const layer = await this.layer.ready();
+        const scopeLabel = scopeRoot && layer ? layer.labelName : undefined;
+        const query = this.readQuery();
         query.queryParams = { ...query.queryParams, keyConceptId, scopeRootId: scopeRoot?.id ?? null };
         query.query += `
-      MATCH (kc:KeyConcept {id: $keyConceptId})
-      MATCH (kc)<-[:RELATES_TO]-(rel:KeyConceptRelationship)-[:RELATES_TO]->(relatedKc:KeyConcept)
-      MATCH (community:Community)-[:HAS_MEMBER]->(relatedKc)
-      MATCH (community)-[:BELONGS_TO]->(company)
-      ${scopeRoot ? `WHERE EXISTS { MATCH (community)-[:SCOPED_TO]->(:${scopeRoot.label} { id: $scopeRootId }) }` : ""}
-      WITH community, rel, relatedKc
-      RETURN community.id AS communityId,
-             community.memberCount AS memberCount,
-             count(DISTINCT relatedKc) AS relationshipCount,
-             sum(coalesce(rel.weight, 1.0)) AS totalWeight
+      ${this.buildDefaultMatch()}
+      ${scopeLabel ? `WHERE EXISTS { MATCH (community)-[:SCOPED_TO]->(:${scopeLabel} { id: $scopeRootId }) }` : ""}
+      MATCH (community)-[:HAS_MEMBER]->(relatedKc:KeyConcept)
+      MATCH (:KeyConcept {id: $keyConceptId})<-[:RELATES_TO]-(rel:KeyConceptRelationship)-[:RELATES_TO]->(relatedKc)
+      WITH community,
+           count(DISTINCT relatedKc) AS relationshipCount,
+           sum(coalesce(rel.weight, 1.0)) AS totalWeight
+      RETURN community, relationshipCount, totalWeight
       ORDER BY totalWeight DESC
     `;
-        const result = await this.neo4j.read(query.query, query.queryParams);
-        return result.records.map((record) => {
-            const relationshipCount = record.get("relationshipCount");
-            const totalWeight = record.get("totalWeight");
-            const memberCount = record.get("memberCount");
-            return {
-                communityId: record.get("communityId"),
-                memberCount: memberCount?.toNumber?.() ?? memberCount ?? 0,
-                relationshipCount: relationshipCount?.toNumber?.() ?? relationshipCount ?? 0,
-                totalWeight: totalWeight?.toNumber?.() ?? totalWeight ?? 0,
-            };
-        });
+        const communities = await this.neo4j.readMany(query);
+        return communities.map((community) => ({
+            communityId: community.id,
+            memberCount: community.memberCount ?? 0,
+            relationshipCount: community.relationshipCount ?? 0,
+            totalWeight: community.totalWeight ?? 0,
+        }));
     }
-    /**
-     * Add a single KeyConcept to an existing community
-     */
+    /** Adds one key concept to a group. */
     async addMemberToCommunity(communityId, keyConceptId) {
-        const query = this.neo4j.initQuery();
-        query.queryParams = { ...query.queryParams, communityId, keyConceptId };
+        const query = this.writeQuery("addMemberToCommunity");
+        await this.neo4j.validateRelatedNodes({ nodes: [{ id: keyConceptId, label: key_concept_meta_1.keyConceptMeta.labelName }] });
+        query.queryParams = { ...query.queryParams, searchValue: communityId, keyConceptId };
         query.query += `
-      MATCH (community:Community {id: $communityId})
+      ${this.buildDefaultMatch({ searchField: "id" })}
       MATCH (keyconcept:KeyConcept {id: $keyConceptId})
       MERGE (community)-[:HAS_MEMBER]->(keyconcept)
       SET community.memberCount = community.memberCount + 1,
@@ -614,27 +606,37 @@ let CommunityRepository = class CommunityRepository {
         await this.neo4j.writeOne(query);
     }
     /**
-     * Find KeyConcepts from a content that are not in any community
+     * Key concepts of one content that are in no group of THIS company. `label` must be a
+     * registered model's: an unknown label returns `[]` and never reaches the query text.
      */
     async findOrphanKeyConceptsForContent(contentId, label) {
-        const query = this.neo4j.initQuery();
+        const model = registry_1.modelRegistry.getByLabelName(label);
+        if (!model)
+            return [];
+        const query = this.neo4j.initQuery({ serialiser: key_concept_model_1.KeyConceptModel });
+        if (!query.queryParams.companyId)
+            return [];
         query.queryParams = { ...query.queryParams, contentId };
         query.query += `
-      MATCH (content:${label} {id: $contentId})-[:HAS_CHUNK]->()-[:HAS_ATOMIC_FACT]->()-[:HAS_KEY_CONCEPT]->(kc:KeyConcept)
-      WHERE NOT EXISTS { (kc)<-[:HAS_MEMBER]-(:Community) }
-      RETURN DISTINCT kc.id AS keyConceptId
+      MATCH (content:${model.labelName} {id: $contentId})
+      WHERE EXISTS { MATCH (content)-[:BELONGS_TO]-(company) }
+      MATCH (content)-[:HAS_CHUNK]->()-[:HAS_ATOMIC_FACT]->()-[:HAS_KEY_CONCEPT]->(keyconcept:KeyConcept)
+      WHERE NOT EXISTS { MATCH (keyconcept)<-[:HAS_MEMBER]-(community:Community) WHERE EXISTS { MATCH (community)-[:BELONGS_TO]-(company) } }
+      RETURN DISTINCT keyconcept
     `;
-        const result = await this.neo4j.read(query.query, query.queryParams);
-        return result.records.map((record) => record.get("keyConceptId"));
+        const keyConcepts = await this.neo4j.readMany(query);
+        return keyConcepts.map((keyConcept) => keyConcept.id);
     }
 };
 exports.CommunityRepository = CommunityRepository;
 exports.CommunityRepository = CommunityRepository = __decorate([
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [neo4j_service_1.Neo4jService,
-        core_1.EmbedderService,
-        core_1.ModelService,
         security_service_1.SecurityService,
-        agent_scope_filter_1.AgentScopeFilterService])
+        nestjs_cls_1.ClsService,
+        embedder_service_1.EmbedderService,
+        model_service_1.ModelService,
+        agent_scope_filter_1.AgentScopeFilterService,
+        community_layer_service_1.CommunityLayerService])
 ], CommunityRepository);
 //# sourceMappingURL=community.repository.js.map