@carlonicora/nestjs-neo4jsonapi 2.14.4 → 2.14.5

package/dist/agents/graph/services/scope.guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope.guard.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/services/scope.guard.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;;;;;;;GASG;AACH,qBACa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAGnC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,YAAY;IAGtC,gBAAgB,CAAC,MAAM,EAAE;QACvB,MAAM,EAAE,aAAa,CAAC;QACtB,GAAG,EAAE,WAAW,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI;IAYxD,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnF,MAAM,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAAC,GAAG,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAiC9G,mEAAmE;IACnE,OAAO,CAAC,YAAY;CASrB"}
+{"version":3,"file":"scope.guard.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/services/scope.guard.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;;;;;;;GASG;AACH,qBACa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAGnC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,YAAY;IAGtC,gBAAgB,CAAC,MAAM,EAAE;QACvB,MAAM,EAAE,aAAa,CAAC;QACtB,GAAG,EAAE,WAAW,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI;IAYxD,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAKnF,MAAM,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAAC,GAAG,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAiC9G,mEAAmE;IACnE,OAAO,CAAC,YAAY;CAGrB"}

package/dist/agents/graph/services/scope.guard.js

@@ -14,6 +14,7 @@ exports.ScopeGuard = void 0;
 const common_1 = require("@nestjs/common");
 const neo4j_service_1 = require("../../../core/neo4j/services/neo4j.service");
 const graph_catalog_service_1 = require("./graph.catalog.service");
+const scope_pattern_1 = require("./scope.pattern");
 /**
  * Single place a scope predicate is built or applied. Every agent data-access
  * point routes through here so "which campaign is this run confined to" has
@@ -73,13 +74,7 @@ let ScopeGuard = ScopeGuard_1 = class ScopeGuard {
     }
     /** `(alias)-[:REL]->(:Label)…-[:REL]->(:Root { id: $scopeId })` */
     buildPattern(scope, alias) {
-        let pattern = `(${alias})`;
-        scope.path.forEach((hop, index) => {
-            const isLast = index === scope.path.length - 1;
-            const node = isLast ? `(:${hop.targetLabel} { id: $scopeId })` : `(:${hop.targetLabel})`;
-            pattern += hop.cypherDirection === "out" ? `-[:${hop.cypherLabel}]->${node}` : `<-[:${hop.cypherLabel}]-${node}`;
-        });
-        return pattern;
+        return (0, scope_pattern_1.buildScopePattern)({ scope, alias, paramName: "scopeId" });
     }
 };
 exports.ScopeGuard = ScopeGuard;

package/dist/agents/graph/services/scope.guard.js.map

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

package/dist/agents/graph/services/scope.pattern.d.ts

@@ -0,0 +1,23 @@
+import { CatalogScope } from "../interfaces/graph.catalog.interface";
+/**
+ * `(alias)-[:REL]->(:Label)…-[:REL]->(:Root { id: $<paramName> })`
+ *
+ * The single place a scope chain becomes Cypher. Both consumers — `ScopeGuard`
+ * (post-filtering records an agent already read) and `ScopePredicateService`
+ * (pre-filtering retrieval before it reads anything) — build their patterns
+ * here, so "is this node inside the run's scope root" cannot drift between
+ * the two.
+ */
+export declare const buildScopePattern: (params: {
+    scope: CatalogScope;
+    alias: string;
+    /** Pins the root to a known id: `(:Root { id: $<paramName> })`. */
+    paramName?: string;
+    /**
+     * Binds the root to a variable instead of pinning it: `(<rootAlias>:Root)`.
+     * For the inverse question — "which root is this node under?" — where the id
+     * is the answer rather than the input. Ignored when `paramName` is given.
+     */
+    rootAlias?: string;
+}) => string;
+//# sourceMappingURL=scope.pattern.d.ts.map

package/dist/agents/graph/services/scope.pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.pattern.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/services/scope.pattern.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAErE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ;IACxC,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,KAAG,MAWH,CAAC"}

package/dist/agents/graph/services/scope.pattern.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildScopePattern = void 0;
+/**
+ * `(alias)-[:REL]->(:Label)…-[:REL]->(:Root { id: $<paramName> })`
+ *
+ * The single place a scope chain becomes Cypher. Both consumers — `ScopeGuard`
+ * (post-filtering records an agent already read) and `ScopePredicateService`
+ * (pre-filtering retrieval before it reads anything) — build their patterns
+ * here, so "is this node inside the run's scope root" cannot drift between
+ * the two.
+ */
+const buildScopePattern = (params) => {
+    let pattern = `(${params.alias})`;
+    params.scope.path.forEach((hop, index) => {
+        const isLast = index === params.scope.path.length - 1;
+        const root = params.paramName
+            ? `(:${hop.targetLabel} { id: $${params.paramName} })`
+            : `(${params.rootAlias ?? "scopeRoot"}:${hop.targetLabel})`;
+        const node = isLast ? root : `(:${hop.targetLabel})`;
+        pattern += hop.cypherDirection === "out" ? `-[:${hop.cypherLabel}]->${node}` : `<-[:${hop.cypherLabel}]-${node}`;
+    });
+    return pattern;
+};
+exports.buildScopePattern = buildScopePattern;
+//# sourceMappingURL=scope.pattern.js.map

package/dist/agents/graph/services/scope.pattern.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.pattern.js","sourceRoot":"","sources":["../../../../src/agents/graph/services/scope.pattern.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;GAQG;AACI,MAAM,iBAAiB,GAAG,CAAC,MAWjC,EAAU,EAAE;IACX,IAAI,OAAO,GAAG,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC;IAClC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACvC,MAAM,MAAM,GAAG,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QACtD,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS;YAC3B,CAAC,CAAC,KAAK,GAAG,CAAC,WAAW,WAAW,MAAM,CAAC,SAAS,KAAK;YACtD,CAAC,CAAC,IAAI,MAAM,CAAC,SAAS,IAAI,WAAW,IAAI,GAAG,CAAC,WAAW,GAAG,CAAC;QAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,WAAW,GAAG,CAAC;QACrD,OAAO,IAAI,GAAG,CAAC,eAAe,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,WAAW,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;IACnH,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAtBW,QAAA,iBAAiB,qBAsB5B"}

package/dist/agents/graph/services/scope.predicate.service.d.ts

@@ -0,0 +1,32 @@
+import { ScopePredicateResult, ScopePredicateSource } from "../../../common/repositories/scope-predicate.source";
+import { AgentScope } from "../../../common/types/agent.scope";
+import { GraphCatalogService } from "./graph.catalog.service";
+/**
+ * Turns the catalog's compiled scope chains into ONE boolean expression that
+ * confines a node alias to the run's scope root.
+ *
+ * The expression is a union over labels, because the alias it guards is
+ * untyped — retrieval binds `(data)` to any entity that owns chunks:
+ *
+ *   (
+ *     (data:Root AND data.id = $agentScopeId)
+ *     OR (data:Child AND EXISTS { MATCH (data)-[:PART_OF]->(:Root { id: $agentScopeId }) })
+ *     …
+ *   )
+ *
+ * FAIL-CLOSED, twice over:
+ *  - a type with no chain to THIS root contributes no branch, so it can never
+ *    match — the same ruling `ScopeGuard` already applies when it post-filters;
+ *  - if no type at all can reach the root, `build` returns null and the caller
+ *    must retrieve nothing rather than fall back to company-wide retrieval.
+ */
+export declare class ScopePredicateService implements ScopePredicateSource {
+    private readonly catalog;
+    private readonly logger;
+    constructor(catalog: GraphCatalogService);
+    build(params: {
+        alias: string;
+        scope: AgentScope;
+    }): ScopePredicateResult | null;
+}
+//# sourceMappingURL=scope.predicate.service.d.ts.map

package/dist/agents/graph/services/scope.predicate.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.predicate.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph/services/scope.predicate.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qDAAqD,CAAC;AACjH,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAG9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,qBAAsB,YAAW,oBAAoB;IAGpD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;gBAEpC,OAAO,EAAE,mBAAmB;IAEzD,KAAK,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,GAAG,oBAAoB,GAAG,IAAI;CA8BjF"}

package/dist/agents/graph/services/scope.predicate.service.js

@@ -0,0 +1,71 @@
+"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 ScopePredicateService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopePredicateService = void 0;
+const common_1 = require("@nestjs/common");
+const graph_catalog_service_1 = require("./graph.catalog.service");
+const scope_pattern_1 = require("./scope.pattern");
+/**
+ * Turns the catalog's compiled scope chains into ONE boolean expression that
+ * confines a node alias to the run's scope root.
+ *
+ * The expression is a union over labels, because the alias it guards is
+ * untyped — retrieval binds `(data)` to any entity that owns chunks:
+ *
+ *   (
+ *     (data:Root AND data.id = $agentScopeId)
+ *     OR (data:Child AND EXISTS { MATCH (data)-[:PART_OF]->(:Root { id: $agentScopeId }) })
+ *     …
+ *   )
+ *
+ * FAIL-CLOSED, twice over:
+ *  - a type with no chain to THIS root contributes no branch, so it can never
+ *    match — the same ruling `ScopeGuard` already applies when it post-filters;
+ *  - if no type at all can reach the root, `build` returns null and the caller
+ *    must retrieve nothing rather than fall back to company-wide retrieval.
+ */
+let ScopePredicateService = ScopePredicateService_1 = class ScopePredicateService {
+    constructor(catalog) {
+        this.catalog = catalog;
+        this.logger = new common_1.Logger(ScopePredicateService_1.name);
+    }
+    build(params) {
+        const branches = [];
+        for (const entity of this.catalog.getAllEntities()) {
+            const scope = entity.scope;
+            if (!scope || scope.rootType !== params.scope.type)
+                continue;
+            if (scope.path.length === 0) {
+                // The entity IS the root: in scope iff it is that exact node.
+                branches.push(`(${params.alias}:${entity.labelName} AND ${params.alias}.id = $agentScopeId)`);
+                continue;
+            }
+            const pattern = (0, scope_pattern_1.buildScopePattern)({ scope, alias: params.alias, paramName: "agentScopeId" });
+            branches.push(`(${params.alias}:${entity.labelName} AND EXISTS { MATCH ${pattern} })`);
+        }
+        if (branches.length === 0) {
+            this.logger.warn(`build: no catalogued entity has a scope chain to root type "${params.scope.type}" — ` +
+                `retrieval in this run is confined to nothing.`);
+            return null;
+        }
+        return {
+            cypher: `(\n        ${branches.join("\n        OR ")}\n      )`,
+            params: { agentScopeId: params.scope.id },
+        };
+    }
+};
+exports.ScopePredicateService = ScopePredicateService;
+exports.ScopePredicateService = ScopePredicateService = ScopePredicateService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [graph_catalog_service_1.GraphCatalogService])
+], ScopePredicateService);
+//# sourceMappingURL=scope.predicate.service.js.map

package/dist/agents/graph/services/scope.predicate.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.predicate.service.js","sourceRoot":"","sources":["../../../../src/agents/graph/services/scope.predicate.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;AAAA,2CAAoD;AAGpD,mEAA8D;AAC9D,mDAAoD;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AAEI,IAAM,qBAAqB,6BAA3B,MAAM,qBAAqB;IAGhC,YAA6B,OAA4B;QAA5B,YAAO,GAAP,OAAO,CAAqB;QAFxC,WAAM,GAAG,IAAI,eAAM,CAAC,uBAAqB,CAAC,IAAI,CAAC,CAAC;IAEL,CAAC;IAE7D,KAAK,CAAC,MAA4C;QAChD,MAAM,QAAQ,GAAa,EAAE,CAAC;QAE9B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;YACnD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YAC3B,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI;gBAAE,SAAS;YAE7D,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,8DAA8D;gBAC9D,QAAQ,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,SAAS,QAAQ,MAAM,CAAC,KAAK,sBAAsB,CAAC,CAAC;gBAC9F,SAAS;YACX,CAAC;YAED,MAAM,OAAO,GAAG,IAAA,iCAAiB,EAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,CAAC;YAC7F,QAAQ,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,SAAS,uBAAuB,OAAO,KAAK,CAAC,CAAC;QACzF,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,MAAM,CAAC,IAAI,CACd,+DAA+D,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM;gBACpF,+CAA+C,CAClD,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO;YACL,MAAM,EAAE,cAAc,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,WAAW;YAC/D,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE;SAC1C,CAAC;IACJ,CAAC;CACF,CAAA;AAnCY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,mBAAU,GAAE;qCAI2B,2CAAmB;GAH9C,qBAAqB,CAmCjC"}

package/dist/agents/index.d.ts

@@ -30,6 +30,9 @@ export { GraphSearchService } from "./graph/services/graph.search.service";
 export type { MatchMode, RunSearchParams } from "./graph/services/graph.search.service";
 export { GRAPH_EXACT_MAX_RESULTS, GRAPH_FUZZY_MAX_RESULTS, GRAPH_SEMANTIC_MAX_RESULTS, GRAPH_SEMANTIC_MIN_SCORE, } from "./graph/services/graph.search.service";
 export { GraphDescriptorRegistry } from "./graph/services/descriptor.source";
+export { ScopeGuard } from "./graph/services/scope.guard";
+export { ScopePredicateService } from "./graph/services/scope.predicate.service";
+export { buildScopePattern } from "./graph/services/scope.pattern";
 export { UserModulesRepository } from "./graph/repositories/user-modules.repository";
 export { ResolveEntityTool } from "./graph/tools/resolve-entity.tool";
 export { DescribeEntityTool } from "./graph/tools/describe-entity.tool";

package/dist/agents/index.d.ts.map

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

package/dist/agents/index.js

@@ -14,7 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OperatorToolRegistry = exports.OperatorTestActionTool = exports.SearchCommunitiesTool = exports.SearchDocumentsTool = exports.OPERATOR_TOOLS = exports.OPERATOR_DEFAULT_APPROVAL_TTL_DAYS = exports.OperatorCheckpointerService = exports.defaultOperatorSystemPrompt = exports.OperatorContext = exports.OperatorService = exports.OperatorController = exports.operatorMeta = exports.OperatorModule = exports.TraverseTool = exports.ReadEntityTool = exports.SearchEntitiesTool = exports.DescribeEntityTool = exports.ResolveEntityTool = exports.UserModulesRepository = exports.GraphDescriptorRegistry = exports.GRAPH_SEMANTIC_MIN_SCORE = exports.GRAPH_SEMANTIC_MAX_RESULTS = exports.GRAPH_FUZZY_MAX_RESULTS = exports.GRAPH_EXACT_MAX_RESULTS = exports.GraphSearchService = exports.GraphModule = exports.SummariserService = exports.SummariserModule = exports.ResponderService = exports.ResponderModule = exports.isValidKeyConcept = exports.buildGraphCreatorOutputSchema = exports.graphCreatorOutputSchema = exports.GraphCreatorService = exports.GraphCreatorModule = exports.CONTEXTUALISER_TOOLS = exports.RETRIEVAL_SOURCES = exports.ContextualiserContextFactoryService = exports.ContextualiserService = exports.ContextualiserModule = exports.DriftMigrationService = exports.DriftSearchService = exports.DriftModule = exports.CommunitySummariserService = exports.CommunitySummariserModule = exports.CommunityDetectorService = exports.CommunityDetectorModule = exports.AgentsModule = void 0;
+exports.OperatorTestActionTool = exports.SearchCommunitiesTool = exports.SearchDocumentsTool = exports.OPERATOR_TOOLS = exports.OPERATOR_DEFAULT_APPROVAL_TTL_DAYS = exports.OperatorCheckpointerService = exports.defaultOperatorSystemPrompt = exports.OperatorContext = exports.OperatorService = exports.OperatorController = exports.operatorMeta = exports.OperatorModule = exports.TraverseTool = exports.ReadEntityTool = exports.SearchEntitiesTool = exports.DescribeEntityTool = exports.ResolveEntityTool = exports.UserModulesRepository = exports.buildScopePattern = exports.ScopePredicateService = exports.ScopeGuard = exports.GraphDescriptorRegistry = exports.GRAPH_SEMANTIC_MIN_SCORE = exports.GRAPH_SEMANTIC_MAX_RESULTS = exports.GRAPH_FUZZY_MAX_RESULTS = exports.GRAPH_EXACT_MAX_RESULTS = exports.GraphSearchService = exports.GraphModule = exports.SummariserService = exports.SummariserModule = exports.ResponderService = exports.ResponderModule = exports.isValidKeyConcept = exports.buildGraphCreatorOutputSchema = exports.graphCreatorOutputSchema = exports.GraphCreatorService = exports.GraphCreatorModule = exports.CONTEXTUALISER_TOOLS = exports.RETRIEVAL_SOURCES = exports.ContextualiserContextFactoryService = exports.ContextualiserService = exports.ContextualiserModule = exports.DriftMigrationService = exports.DriftSearchService = exports.DriftModule = exports.CommunitySummariserService = exports.CommunitySummariserModule = exports.CommunityDetectorService = exports.CommunityDetectorModule = exports.AgentsModule = void 0;
+exports.OperatorToolRegistry = void 0;
 // Centralized AgentsModule - prompts configured via baseConfig.prompts
 var agents_modules_1 = require("./agents.modules");
 Object.defineProperty(exports, "AgentsModule", { enumerable: true, get: function () { return agents_modules_1.AgentsModule; } });
@@ -80,6 +81,12 @@ Object.defineProperty(exports, "GRAPH_SEMANTIC_MAX_RESULTS", { enumerable: true,
 Object.defineProperty(exports, "GRAPH_SEMANTIC_MIN_SCORE", { enumerable: true, get: function () { return graph_search_service_2.GRAPH_SEMANTIC_MIN_SCORE; } });
 var descriptor_source_1 = require("./graph/services/descriptor.source");
 Object.defineProperty(exports, "GraphDescriptorRegistry", { enumerable: true, get: function () { return descriptor_source_1.GraphDescriptorRegistry; } });
+var scope_guard_1 = require("./graph/services/scope.guard");
+Object.defineProperty(exports, "ScopeGuard", { enumerable: true, get: function () { return scope_guard_1.ScopeGuard; } });
+var scope_predicate_service_1 = require("./graph/services/scope.predicate.service");
+Object.defineProperty(exports, "ScopePredicateService", { enumerable: true, get: function () { return scope_predicate_service_1.ScopePredicateService; } });
+var scope_pattern_1 = require("./graph/services/scope.pattern");
+Object.defineProperty(exports, "buildScopePattern", { enumerable: true, get: function () { return scope_pattern_1.buildScopePattern; } });
 var user_modules_repository_1 = require("./graph/repositories/user-modules.repository");
 Object.defineProperty(exports, "UserModulesRepository", { enumerable: true, get: function () { return user_modules_repository_1.UserModulesRepository; } });
 // The graph tool builders, for app-side agents that bind the catalog tools to

package/dist/agents/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uEAAuE;AACvE,mDAAgD;AAAvC,8GAAA,YAAY,OAAA;AAErB,gCAAgC;AAChC,4CAA0B;AAO1B,6BAA6B;AAC7B,4FAAyF;AAAhF,oIAAA,uBAAuB,OAAA;AAChC,uGAAoG;AAA3F,sIAAA,wBAAwB,OAAA;AAEjC,+BAA+B;AAC/B,kGAA+F;AAAtF,wIAAA,yBAAyB,OAAA;AAClC,6GAA0G;AAAjG,0IAAA,0BAA0B,OAAA;AAEnC,eAAe;AACf,qDAAmD;AAA1C,2GAAA,WAAW,OAAA;AACpB,8EAA2G;AAAlG,0HAAA,kBAAkB,OAAA;AAC3B,oFAAkG;AAAzF,gIAAA,qBAAqB,OAAA;AAG9B,4BAA4B;AAC5B,gFAA8E;AAArE,6HAAA,oBAAoB,OAAA;AAC7B,2FAAyF;AAAhF,+HAAA,qBAAqB,OAAA;AAC9B,4GAAgH;AAAvG,qJAAA,mCAAmC,OAAA;AAE5C,qGAAiH;AAAxG,+HAAA,iBAAiB,OAAA;AAAE,kIAAA,oBAAoB,OAAA;AAOhD,gBAAgB;AAChB,6EAA0E;AAAjE,0HAAA,kBAAkB,OAAA;AAC3B,wFAQwD;AAPtD,4HAAA,mBAAmB,OAAA;AACnB,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,iIAAA,wBAAwB,OAAA;AACxB,sIAAA,6BAA6B,OAAA;AAC7B,0HAAA,iBAAiB,OAAA;AAInB,YAAY;AACZ,iEAA+D;AAAtD,mHAAA,eAAe,OAAA;AACxB,4EAA0E;AAAjE,qHAAA,gBAAgB,OAAA;AAKzB,aAAa;AACb,oEAAkE;AAAzD,qHAAA,gBAAgB,OAAA;AACzB,+EAA6E;AAApE,uHAAA,iBAAiB,OAAA;AAE1B,2EAA2E;AAC3E,qDAAmD;AAA1C,2GAAA,WAAW,OAAA;AACpB,8EAA2E;AAAlE,0HAAA,kBAAkB,OAAA;AAE3B,8EAK+C;AAJ7C,+HAAA,uBAAuB,OAAA;AACvB,+HAAA,uBAAuB,OAAA;AACvB,kIAAA,0BAA0B,OAAA;AAC1B,gIAAA,wBAAwB,OAAA;AAE1B,wEAA6E;AAApE,4HAAA,uBAAuB,OAAA;AAChC,wFAAqF;AAA5E,gIAAA,qBAAqB,OAAA;AAC9B,8EAA8E;AAC9E,oFAAoF;AACpF,yEAAsE;AAA7D,wHAAA,iBAAiB,OAAA;AAC1B,2EAAwE;AAA/D,0HAAA,kBAAkB,OAAA;AAC3B,2EAAwE;AAA/D,0HAAA,kBAAkB,OAAA;AAC3B,mEAAgE;AAAvD,kHAAA,cAAc,OAAA;AACvB,6DAA2D;AAAlD,6GAAA,YAAY,OAAA;AAGrB,WAAW;AACX,8DAA4D;AAAnD,iHAAA,cAAc,OAAA;AACvB,mEAAiE;AAAxD,6GAAA,YAAY,OAAA;AACrB,kFAAgF;AAAvE,yHAAA,kBAAkB,OAAA;AAC3B,yEAAuE;AAA9D,mHAAA,eAAe,OAAA;AAExB,yEAAuE;AAA9D,mHAAA,eAAe,OAAA;AAExB,oFAAwF;AAA/E,qIAAA,2BAA2B,OAAA;AACpC,mGAG2D;AAFzD,4IAAA,2BAA2B,OAAA;AAC3B,mJAAA,kCAAkC,OAAA;AAGpC,wBAAwB;AACxB,yFAA+E;AAAtE,yHAAA,cAAc,OAAA;AAQvB,gFAA6E;AAApE,4HAAA,mBAAmB,OAAA;AAC5B,oFAAiF;AAAxE,gIAAA,qBAAqB,OAAA;AAC9B,wFAAoF;AAA3E,mIAAA,sBAAsB,OAAA;AAC/B,kFAA+E;AAAtE,8HAAA,oBAAoB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAAA,uEAAuE;AACvE,mDAAgD;AAAvC,8GAAA,YAAY,OAAA;AAErB,gCAAgC;AAChC,4CAA0B;AAO1B,6BAA6B;AAC7B,4FAAyF;AAAhF,oIAAA,uBAAuB,OAAA;AAChC,uGAAoG;AAA3F,sIAAA,wBAAwB,OAAA;AAEjC,+BAA+B;AAC/B,kGAA+F;AAAtF,wIAAA,yBAAyB,OAAA;AAClC,6GAA0G;AAAjG,0IAAA,0BAA0B,OAAA;AAEnC,eAAe;AACf,qDAAmD;AAA1C,2GAAA,WAAW,OAAA;AACpB,8EAA2G;AAAlG,0HAAA,kBAAkB,OAAA;AAC3B,oFAAkG;AAAzF,gIAAA,qBAAqB,OAAA;AAG9B,4BAA4B;AAC5B,gFAA8E;AAArE,6HAAA,oBAAoB,OAAA;AAC7B,2FAAyF;AAAhF,+HAAA,qBAAqB,OAAA;AAC9B,4GAAgH;AAAvG,qJAAA,mCAAmC,OAAA;AAE5C,qGAAiH;AAAxG,+HAAA,iBAAiB,OAAA;AAAE,kIAAA,oBAAoB,OAAA;AAOhD,gBAAgB;AAChB,6EAA0E;AAAjE,0HAAA,kBAAkB,OAAA;AAC3B,wFAQwD;AAPtD,4HAAA,mBAAmB,OAAA;AACnB,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,iIAAA,wBAAwB,OAAA;AACxB,sIAAA,6BAA6B,OAAA;AAC7B,0HAAA,iBAAiB,OAAA;AAInB,YAAY;AACZ,iEAA+D;AAAtD,mHAAA,eAAe,OAAA;AACxB,4EAA0E;AAAjE,qHAAA,gBAAgB,OAAA;AAKzB,aAAa;AACb,oEAAkE;AAAzD,qHAAA,gBAAgB,OAAA;AACzB,+EAA6E;AAApE,uHAAA,iBAAiB,OAAA;AAE1B,2EAA2E;AAC3E,qDAAmD;AAA1C,2GAAA,WAAW,OAAA;AACpB,8EAA2E;AAAlE,0HAAA,kBAAkB,OAAA;AAE3B,8EAK+C;AAJ7C,+HAAA,uBAAuB,OAAA;AACvB,+HAAA,uBAAuB,OAAA;AACvB,kIAAA,0BAA0B,OAAA;AAC1B,gIAAA,wBAAwB,OAAA;AAE1B,wEAA6E;AAApE,4HAAA,uBAAuB,OAAA;AAChC,4DAA0D;AAAjD,yGAAA,UAAU,OAAA;AACnB,oFAAiF;AAAxE,gIAAA,qBAAqB,OAAA;AAC9B,gEAAmE;AAA1D,kHAAA,iBAAiB,OAAA;AAC1B,wFAAqF;AAA5E,gIAAA,qBAAqB,OAAA;AAC9B,8EAA8E;AAC9E,oFAAoF;AACpF,yEAAsE;AAA7D,wHAAA,iBAAiB,OAAA;AAC1B,2EAAwE;AAA/D,0HAAA,kBAAkB,OAAA;AAC3B,2EAAwE;AAA/D,0HAAA,kBAAkB,OAAA;AAC3B,mEAAgE;AAAvD,kHAAA,cAAc,OAAA;AACvB,6DAA2D;AAAlD,6GAAA,YAAY,OAAA;AAGrB,WAAW;AACX,8DAA4D;AAAnD,iHAAA,cAAc,OAAA;AACvB,mEAAiE;AAAxD,6GAAA,YAAY,OAAA;AACrB,kFAAgF;AAAvE,yHAAA,kBAAkB,OAAA;AAC3B,yEAAuE;AAA9D,mHAAA,eAAe,OAAA;AAExB,yEAAuE;AAA9D,mHAAA,eAAe,OAAA;AAExB,oFAAwF;AAA/E,qIAAA,2BAA2B,OAAA;AACpC,mGAG2D;AAFzD,4IAAA,2BAA2B,OAAA;AAC3B,mJAAA,kCAAkC,OAAA;AAGpC,wBAAwB;AACxB,yFAA+E;AAAtE,yHAAA,cAAc,OAAA;AAQvB,gFAA6E;AAApE,4HAAA,mBAAmB,OAAA;AAC5B,oFAAiF;AAAxE,gIAAA,qBAAqB,OAAA;AAC9B,wFAAoF;AAA3E,mIAAA,sBAAsB,OAAA;AAC/B,kFAA+E;AAAtE,8HAAA,oBAAoB,OAAA"}

package/dist/common/repositories/agent-scope.filter.d.ts

@@ -0,0 +1,64 @@
+import { ClsService } from "nestjs-cls";
+import { ScopePredicateSource } from "./scope-predicate.source";
+import { AgentScope } from "../types/agent.scope";
+import { DataLimits } from "../types/data.limits";
+/** A Cypher fragment to place immediately after the source query's `WITH <alias>`. */
+export interface AgentScopeFilter {
+    /** `WHERE …`, or `""` when the run is deliberately unscoped. */
+    cypher: string;
+    params: Record<string, unknown>;
+    /** True when a scope was in force and the fragment narrows retrieval. */
+    applied: boolean;
+}
+/**
+ * The retrieval-side half of scope enforcement.
+ *
+ * WHY THIS IS NOT INSIDE `AiSourceQueryProvider`: that provider is an app
+ * override point (`CoreModule.forRoot({ aiSourceQuery })`). Putting the scope
+ * predicate inside the DEFAULT implementation would mean any app that
+ * customised its source query silently opted out of scope enforcement — a
+ * fail-OPEN seam guarding a security boundary. Applying the filter at the call
+ * sites, on top of whatever the provider returned, makes the guard impossible
+ * for an override to drop.
+ */
+export declare class AgentScopeFilterService {
+    private readonly cls;
+    private readonly predicates?;
+    private readonly logger;
+    constructor(cls: ClsService, predicates?: ScopePredicateSource);
+    /** The scope published for this turn, if any. */
+    current(): AgentScope | undefined;
+    /**
+     * Builds the `WHERE` that confines `alias` to the run's scope root.
+     *
+     * Three outcomes, all deliberate:
+     *  - no scope in CLS, or a HowTo run → `""`. HowTo content is global and has
+     *    no scope root; help mode is scope-independent by design.
+     *  - scope + a predicate → `WHERE (…)`, retrieval narrowed to that root.
+     *  - scope + NO predicate (no `SCOPE_PREDICATE_SOURCE` registered, or no
+     *    entity can reach the root) → `WHERE false`. FAIL CLOSED: a run that
+     *    declares a scope it cannot enforce retrieves nothing. Returning `""`
+     *    here would silently restore company-wide retrieval — a cross-scope leak,
+     *    which is the whole failure this guard exists to prevent.
+     */
+    build(params: {
+        alias: string;
+        dataLimits?: DataLimits;
+    }): AgentScopeFilter;
+    /**
+     * The bare boolean expression, for callers that must embed it somewhere a
+     * standalone `WHERE` cannot go — inside an `EXISTS { … }`, or ANDed onto a
+     * clause that already has a `WHERE`.
+     *
+     * `null` means the run is unscoped and nothing should be filtered. It never
+     * means "could not work it out": that case returns the constant `false`.
+     */
+    predicate(params: {
+        alias: string;
+        dataLimits?: DataLimits;
+    }): {
+        cypher: string;
+        params: Record<string, unknown>;
+    } | null;
+}
+//# sourceMappingURL=agent-scope.filter.d.ts.map

package/dist/common/repositories/agent-scope.filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-scope.filter.d.ts","sourceRoot":"","sources":["../../../src/common/repositories/agent-scope.filter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAA0B,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,EAAuB,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;CAClB;AAID;;;;;;;;;;GAUG;AACH,qBACa,uBAAuB;IAIhC,OAAO,CAAC,QAAQ,CAAC,GAAG;IACwB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAJ1E,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;gBAGhD,GAAG,EAAE,UAAU,EAC6B,UAAU,CAAC,EAAE,oBAAoB;IAGhG,iDAAiD;IACjD,OAAO,IAAI,UAAU,GAAG,SAAS;IAOjC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,gBAAgB;IAM3E;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,UAAU,CAAC;KACzB,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI;CAkB/D"}

package/dist/common/repositories/agent-scope.filter.js

@@ -0,0 +1,96 @@
+"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 __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var AgentScopeFilterService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentScopeFilterService = void 0;
+const common_1 = require("@nestjs/common");
+const nestjs_cls_1 = require("nestjs-cls");
+const scope_predicate_source_1 = require("./scope-predicate.source");
+const agent_scope_1 = require("../types/agent.scope");
+const UNSCOPED = { cypher: "", params: {}, applied: false };
+/**
+ * The retrieval-side half of scope enforcement.
+ *
+ * WHY THIS IS NOT INSIDE `AiSourceQueryProvider`: that provider is an app
+ * override point (`CoreModule.forRoot({ aiSourceQuery })`). Putting the scope
+ * predicate inside the DEFAULT implementation would mean any app that
+ * customised its source query silently opted out of scope enforcement — a
+ * fail-OPEN seam guarding a security boundary. Applying the filter at the call
+ * sites, on top of whatever the provider returned, makes the guard impossible
+ * for an override to drop.
+ */
+let AgentScopeFilterService = AgentScopeFilterService_1 = class AgentScopeFilterService {
+    constructor(cls, predicates) {
+        this.cls = cls;
+        this.predicates = predicates;
+        this.logger = new common_1.Logger(AgentScopeFilterService_1.name);
+    }
+    /** The scope published for this turn, if any. */
+    current() {
+        const scope = this.cls.has(agent_scope_1.AGENT_SCOPE_CLS_KEY)
+            ? this.cls.get(agent_scope_1.AGENT_SCOPE_CLS_KEY)
+            : undefined;
+        return scope?.id && scope?.type ? scope : undefined;
+    }
+    /**
+     * Builds the `WHERE` that confines `alias` to the run's scope root.
+     *
+     * Three outcomes, all deliberate:
+     *  - no scope in CLS, or a HowTo run → `""`. HowTo content is global and has
+     *    no scope root; help mode is scope-independent by design.
+     *  - scope + a predicate → `WHERE (…)`, retrieval narrowed to that root.
+     *  - scope + NO predicate (no `SCOPE_PREDICATE_SOURCE` registered, or no
+     *    entity can reach the root) → `WHERE false`. FAIL CLOSED: a run that
+     *    declares a scope it cannot enforce retrieves nothing. Returning `""`
+     *    here would silently restore company-wide retrieval — a cross-scope leak,
+     *    which is the whole failure this guard exists to prevent.
+     */
+    build(params) {
+        const predicate = this.predicate(params);
+        if (!predicate)
+            return UNSCOPED;
+        return { cypher: `WHERE ${predicate.cypher}`, params: predicate.params, applied: true };
+    }
+    /**
+     * The bare boolean expression, for callers that must embed it somewhere a
+     * standalone `WHERE` cannot go — inside an `EXISTS { … }`, or ANDed onto a
+     * clause that already has a `WHERE`.
+     *
+     * `null` means the run is unscoped and nothing should be filtered. It never
+     * means "could not work it out": that case returns the constant `false`.
+     */
+    predicate(params) {
+        if (params.dataLimits?.howToMode || params.dataLimits?.limitToHowToId)
+            return null;
+        const scope = this.current();
+        if (!scope)
+            return null;
+        const predicate = this.predicates?.build({ alias: params.alias, scope });
+        if (!predicate) {
+            this.logger.error(`predicate: run is scoped to ${scope.type}:${scope.id} but no scope predicate could be compiled ` +
+                `(${this.predicates ? "no entity reaches that root" : "no SCOPE_PREDICATE_SOURCE registered"}) — ` +
+                `failing closed, this retrieval returns nothing.`);
+            return { cypher: "false", params: {} };
+        }
+        return predicate;
+    }
+};
+exports.AgentScopeFilterService = AgentScopeFilterService;
+exports.AgentScopeFilterService = AgentScopeFilterService = AgentScopeFilterService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(scope_predicate_source_1.SCOPE_PREDICATE_SOURCE)),
+    __metadata("design:paramtypes", [nestjs_cls_1.ClsService, Object])
+], AgentScopeFilterService);
+//# sourceMappingURL=agent-scope.filter.js.map

package/dist/common/repositories/agent-scope.filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-scope.filter.js","sourceRoot":"","sources":["../../../src/common/repositories/agent-scope.filter.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAsE;AACtE,2CAAwC;AACxC,qEAAwF;AACxF,sDAAuE;AAYvE,MAAM,QAAQ,GAAqB,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAE9E;;;;;;;;;;GAUG;AAEI,IAAM,uBAAuB,+BAA7B,MAAM,uBAAuB;IAGlC,YACmB,GAAe,EACY,UAAkD;QAD7E,QAAG,GAAH,GAAG,CAAY;QAC6B,eAAU,GAAV,UAAU,CAAuB;QAJ/E,WAAM,GAAG,IAAI,eAAM,CAAC,yBAAuB,CAAC,IAAI,CAAC,CAAC;IAKhE,CAAC;IAEJ,iDAAiD;IACjD,OAAO;QACL,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,iCAAmB,CAAC;YAC7C,CAAC,CAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,iCAAmB,CAA4B;YAC/D,CAAC,CAAC,SAAS,CAAC;QACd,OAAO,KAAK,EAAE,EAAE,IAAI,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAkD;QACtD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,SAAS;YAAE,OAAO,QAAQ,CAAC;QAChC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAS,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1F,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,MAGT;QACC,IAAI,MAAM,CAAC,UAAU,EAAE,SAAS,IAAI,MAAM,CAAC,UAAU,EAAE,cAAc;YAAE,OAAO,IAAI,CAAC;QAEnF,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,CACf,+BAA+B,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,4CAA4C;gBAC/F,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,sCAAsC,MAAM;gBAClG,iDAAiD,CACpD,CAAC;YACF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;QACzC,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;CACF,CAAA;AAhEY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,mBAAU,GAAE;IAMR,WAAA,IAAA,iBAAQ,GAAE,CAAA;IAAE,WAAA,IAAA,eAAM,EAAC,+CAAsB,CAAC,CAAA;qCADrB,uBAAU;GAJvB,uBAAuB,CAgEnC"}

package/dist/common/repositories/index.d.ts

@@ -1,3 +1,5 @@
+export * from "./agent-scope.filter";
+export * from "./scope-predicate.source";
 export * from "./ai.source.query";
 export * from "./ai-source-query.provider";
 export * from "./default.ai-source-query.provider";

package/dist/common/repositories/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/repositories/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/repositories/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC"}

package/dist/common/repositories/index.js

@@ -14,6 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./agent-scope.filter"), exports);
+__exportStar(require("./scope-predicate.source"), exports);
 __exportStar(require("./ai.source.query"), exports);
 __exportStar(require("./ai-source-query.provider"), exports);
 __exportStar(require("./default.ai-source-query.provider"), exports);

package/dist/common/repositories/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/repositories/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oDAAkC;AAClC,6DAA2C;AAC3C,qEAAmD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/repositories/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAqC;AACrC,2DAAyC;AACzC,oDAAkC;AAClC,6DAA2C;AAC3C,qEAAmD"}

package/dist/common/repositories/scope-predicate.source.d.ts

@@ -0,0 +1,32 @@
+import { AgentScope } from "../types/agent.scope";
+export interface ScopePredicateResult {
+    /**
+     * A Cypher BOOLEAN EXPRESSION over `alias` — no `WHERE`, no `AND` prefix, so
+     * the caller decides how to join it. References `$agentScopeId` only.
+     */
+    cypher: string;
+    /** Parameters the expression references — bound, never interpolated. */
+    params: Record<string, unknown>;
+}
+/**
+ * Compiles "is this node inside the run's scope root?" into Cypher.
+ *
+ * The knowledge needed to answer that — every entity type's hop chain to the
+ * scope root — lives in the graph catalog, which sits ABOVE the core layer
+ * where retrieval repositories live. This token is the seam between the two:
+ * the graph layer registers an implementation, and core-layer retrieval asks
+ * for a predicate without depending on the catalog.
+ *
+ * FAIL-CLOSED CONTRACT: an implementation returns `null` only when it can
+ * prove nothing is in scope. A caller holding a scope that gets `null` MUST
+ * retrieve nothing — never fall back to unfiltered retrieval, which is the
+ * cross-scope leak this seam exists to prevent.
+ */
+export interface ScopePredicateSource {
+    build(params: {
+        alias: string;
+        scope: AgentScope;
+    }): ScopePredicateResult | null;
+}
+export declare const SCOPE_PREDICATE_SOURCE: unique symbol;
+//# sourceMappingURL=scope-predicate.source.d.ts.map

package/dist/common/repositories/scope-predicate.source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-predicate.source.d.ts","sourceRoot":"","sources":["../../../src/common/repositories/scope-predicate.source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,GAAG,oBAAoB,GAAG,IAAI,CAAC;CAClF;AAED,eAAO,MAAM,sBAAsB,eAAmC,CAAC"}

package/dist/common/repositories/scope-predicate.source.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCOPE_PREDICATE_SOURCE = void 0;
+exports.SCOPE_PREDICATE_SOURCE = Symbol("SCOPE_PREDICATE_SOURCE");
+//# sourceMappingURL=scope-predicate.source.js.map

package/dist/common/repositories/scope-predicate.source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-predicate.source.js","sourceRoot":"","sources":["../../../src/common/repositories/scope-predicate.source.ts"],"names":[],"mappings":";;;AA8Ba,QAAA,sBAAsB,GAAG,MAAM,CAAC,wBAAwB,CAAC,CAAC"}

package/dist/common/types/agent.scope.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The scope ROOT one agent run is confined to.
+ *
+ * A scope root is a catalogued entity whose compiled scope chain is empty —
+ * every other entity reaches it through a chain of relationship hops. A run
+ * bound to one may read only content that reaches that root.
+ *
+ * WHY THIS IS AMBIENT (CLS) RATHER THAN A PARAMETER
+ * -------------------------------------------------
+ * Retrieval reads the run's scope from CLS for the same reason it reads
+ * `companyId` from CLS: a security boundary that every call site must REMEMBER
+ * to pass is a boundary that eventually is not passed. Publishing it once per
+ * turn, next to `companyId`, means a new retrieval path is confined by
+ * construction rather than by review.
+ */
+export interface AgentScope {
+    /** Id of the scope-root node. */
+    id: string;
+    /** JSON:API type of the scope root, e.g. "campaigns". */
+    type: string;
+    /** Neo4j label of the scope root, e.g. "Campaign". */
+    label: string;
+}
+/**
+ * CLS key under which a turn publishes its `AgentScope`.
+ *
+ * Absent = the run is deliberately unscoped (company-wide MCP tools, a worker
+ * job, an app with no scope roots at all) and retrieval behaves as it always
+ * has. Present = every retrieval in the turn is confined to that root.
+ */
+export declare const AGENT_SCOPE_CLS_KEY = "agentScope";
+//# sourceMappingURL=agent.scope.d.ts.map

package/dist/common/types/agent.scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.scope.d.ts","sourceRoot":"","sources":["../../../src/common/types/agent.scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,eAAe,CAAC"}

package/dist/common/types/agent.scope.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_SCOPE_CLS_KEY = void 0;
+/**
+ * CLS key under which a turn publishes its `AgentScope`.
+ *
+ * Absent = the run is deliberately unscoped (company-wide MCP tools, a worker
+ * job, an app with no scope roots at all) and retrieval behaves as it always
+ * has. Present = every retrieval in the turn is confined to that root.
+ */
+exports.AGENT_SCOPE_CLS_KEY = "agentScope";
+//# sourceMappingURL=agent.scope.js.map

package/dist/common/types/agent.scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.scope.js","sourceRoot":"","sources":["../../../src/common/types/agent.scope.ts"],"names":[],"mappings":";;;AAwBA;;;;;;GAMG;AACU,QAAA,mBAAmB,GAAG,YAAY,CAAC"}

package/dist/common/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./agent.scope";
 export * from "./data.limits";
 export * from "./reducers";
 //# sourceMappingURL=index.d.ts.map

package/dist/common/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC"}

package/dist/common/types/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./agent.scope"), exports);
 __exportStar(require("./data.limits"), exports);
 __exportStar(require("./reducers"), exports);
 //# sourceMappingURL=index.js.map