@carlonicora/nestjs-neo4jsonapi 4.10.0 → 4.12.0

package/dist/common/interfaces/entity.schema.interface.d.ts

@@ -91,6 +91,18 @@ export interface FieldDef {
      */
     kind?: FieldKind;
 }
+/**
+ * An inline scope hop: a scope path that is NOT a descriptor relationship.
+ * Used only for the chat scope chain. It is never added to the catalog
+ * relationships, never read by repositories and never serialised.
+ */
+export interface ChatScopeHop {
+    /** Meta of the type one hop closer to the root. It must itself declare chat.scope. */
+    model: DataMeta;
+    direction: "in" | "out";
+    /** Neo4j relationship type(s); "A|B" allowed. */
+    relationship: string;
+}
 /**
  * Which parts of a `chat.writable` entity the operator's write tools may set.
  * Declared by the host app on the descriptor, surfaced to the model through
@@ -187,6 +199,17 @@ export interface RelationshipDef {
     immutable?: boolean;
     /** If true, the relationship is never written by generic descriptor-driven paths (create/put/patch skip it; relationship handlers reject it). Serialisation-only. */
     readOnly?: boolean;
+    /**
+     * If true, the related records live outside this database (e.g. an external
+     * corpus): the local node is only a link target. Generic reads
+     * (`buildReturnStatement()`, so find/findById/findByIds/findByRelated/
+     * findByRelatedEdge) project the related node as its id and labels only —
+     * `{ labels, properties: { id } }` — and never return its stored properties.
+     * The owning service hydrates the fields from the external source.
+     * Not allowed together with `include` (an external node has no local
+     * relationships to expand). Default: false.
+     */
+    externalSource?: boolean;
     /** Human-readable description. Required for the relationship to be visible to the chatbot. */
     description?: string;
     /** Opts in reverse traversal from the target entity. Omit to keep one-way. */
@@ -281,10 +304,27 @@ export interface EntitySchemaInput<T, R extends Record<string, RelationshipDef>
         list?: string[];
         /**
          * Campaign/tenant-style scoping. Either "self" (this entity IS the scope
-         * root) or the key of a relationship on THIS descriptor pointing one hop
-         * closer to the root. The catalog walks the chain at boot.
+         * root), the key of a relationship on THIS descriptor pointing one hop
+         * closer to the root, or an inline {@link ChatScopeHop} for a scope path
+         * that is not a descriptor relationship. The catalog walks the chain at boot.
          */
-        scope?: string;
+        scope?: string | ChatScopeHop;
+        /**
+         * Reference data: visible in every scoped run, whatever the root.
+         * Mutually exclusive with `scope`; not allowed on a `writable` type.
+         */
+        scopeShared?: boolean;
+        /**
+         * Scope decided by the type's own service rather than by a Cypher path:
+         * for records whose scope edge does not exist in the app database. The
+         * service must implement `ExternalEntitySource.filterInScope`; without it
+         * every record of this type is out of scope in a scoped run.
+         * `rootType` must be a catalogued type whose `chat.scope` is `"self"`.
+         * Mutually exclusive with `scope` and `scopeShared` (boot throws).
+         */
+        scopeByService?: {
+            rootType: string;
+        };
         /**
          * Opts this type into the operator's generic write tools.
          * `true` keeps the legacy meaning (every described field, every forward
@@ -373,10 +413,27 @@ export interface EntityDescriptor<T, R extends Record<string, RelationshipDef> =
         list?: string[];
         /**
          * Campaign/tenant-style scoping. Either "self" (this entity IS the scope
-         * root) or the key of a relationship on THIS descriptor pointing one hop
-         * closer to the root. The catalog walks the chain at boot.
+         * root), the key of a relationship on THIS descriptor pointing one hop
+         * closer to the root, or an inline {@link ChatScopeHop} for a scope path
+         * that is not a descriptor relationship. The catalog walks the chain at boot.
+         */
+        scope?: string | ChatScopeHop;
+        /**
+         * Reference data: visible in every scoped run, whatever the root.
+         * Mutually exclusive with `scope`; not allowed on a `writable` type.
+         */
+        scopeShared?: boolean;
+        /**
+         * Scope decided by the type's own service rather than by a Cypher path:
+         * for records whose scope edge does not exist in the app database. The
+         * service must implement `ExternalEntitySource.filterInScope`; without it
+         * every record of this type is out of scope in a scoped run.
+         * `rootType` must be a catalogued type whose `chat.scope` is `"self"`.
+         * Mutually exclusive with `scope` and `scopeShared` (boot throws).
          */
-        scope?: string;
+        scopeByService?: {
+            rootType: string;
+        };
         /**
          * Opts this type into the operator's generic write tools.
          * `true` keeps the legacy meaning (every described field, every forward

package/dist/common/interfaces/entity.schema.interface.d.ts.map

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

package/dist/common/interfaces/external.entity.source.interface.d.ts

@@ -0,0 +1,43 @@
+/**
+ * External entity sources: optional capabilities an `AbstractService` subclass
+ * implements when its records live outside the app database (for example a
+ * corpus served over HTTP).
+ *
+ * Every hook is optional and discovered on the registered service instance
+ * (`EntityServiceRegistry.get(type)`). A service that implements none of them
+ * behaves exactly as before.
+ */
+/** One name-lookup candidate returned by {@link ExternalEntitySource.resolveByText}. */
+export interface ExternalResolveCandidate {
+    id: string;
+    name: string;
+    score: number;
+}
+/** One related record returned by {@link ExternalEntitySource.findRelatedIds}. */
+export interface ExternalRelatedId {
+    type: string;
+    id: string;
+}
+/** Optional capabilities an AbstractService subclass implements when its records live outside the app database. */
+export interface ExternalEntitySource {
+    /** resolve_entity for this type: replaces the app-DB fulltext/semantic tiers. Global reference data: no record-level access check is applied to these candidates. */
+    resolveByText(params: {
+        text: string;
+        limit: number;
+    }): Promise<ExternalResolveCandidate[]>;
+    /** Scope check for a type declared with chat.scopeByService. Returns the subset of ids inside the scope root. */
+    filterInScope?(params: {
+        ids: string[];
+        scopeType: string;
+        scopeId: string;
+    }): Promise<string[]>;
+    /** Polymorphic traverse for edges that do not exist in the app database. */
+    findRelatedIds?(params: {
+        id: string;
+        cypherLabel: string;
+        limit: number;
+    }): Promise<ExternalRelatedId[]>;
+}
+/** True when the service implements {@link ExternalEntitySource.resolveByText}. */
+export declare function isExternalEntitySource(svc: unknown): svc is ExternalEntitySource;
+//# sourceMappingURL=external.entity.source.interface.d.ts.map

package/dist/common/interfaces/external.entity.source.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.entity.source.interface.d.ts","sourceRoot":"","sources":["../../../src/common/interfaces/external.entity.source.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,wFAAwF;AACxF,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,mHAAmH;AACnH,MAAM,WAAW,oBAAoB;IACnC,qKAAqK;IACrK,aAAa,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC,CAAC;IAC5F,iHAAiH;IACjH,aAAa,CAAC,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjG,4EAA4E;IAC5E,cAAc,CAAC,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CAC3G;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,oBAAoB,CAEhF"}

package/dist/common/interfaces/external.entity.source.interface.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * External entity sources: optional capabilities an `AbstractService` subclass
+ * implements when its records live outside the app database (for example a
+ * corpus served over HTTP).
+ *
+ * Every hook is optional and discovered on the registered service instance
+ * (`EntityServiceRegistry.get(type)`). A service that implements none of them
+ * behaves exactly as before.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExternalEntitySource = isExternalEntitySource;
+/** True when the service implements {@link ExternalEntitySource.resolveByText}. */
+function isExternalEntitySource(svc) {
+    return typeof svc?.resolveByText === "function";
+}
+//# sourceMappingURL=external.entity.source.interface.js.map

package/dist/common/interfaces/external.entity.source.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external.entity.source.interface.js","sourceRoot":"","sources":["../../../src/common/interfaces/external.entity.source.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AA0BH,wDAEC;AAHD,mFAAmF;AACnF,SAAgB,sBAAsB,CAAC,GAAY;IACjD,OAAO,OAAQ,GAAW,EAAE,aAAa,KAAK,UAAU,CAAC;AAC3D,CAAC"}

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

@@ -1,8 +1,12 @@
+export * from "./assistant.scope.interface";
+export * from "./assistant.title.interface";
 export * from "./authenticated.request.interface";
 export * from "./datamodel.interface";
 export * from "./entity.descriptor.interface";
 export * from "./entity.schema.interface";
+export * from "./external.entity.source.interface";
 export * from "./message.interface";
+export * from "./s3.key-access.policy.interface";
 export * from "./seed.context.interface";
 export * from "./token.usage.interface";
 export * from "./langchain.usage.interface";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/interfaces/index.ts"],"names":[],"mappings":"AAAA,cAAc,mCAAmC,CAAC;AAClD,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/interfaces/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC"}

package/dist/common/interfaces/index.js

@@ -14,11 +14,15 @@ 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("./assistant.scope.interface"), exports);
+__exportStar(require("./assistant.title.interface"), exports);
 __exportStar(require("./authenticated.request.interface"), exports);
 __exportStar(require("./datamodel.interface"), exports);
 __exportStar(require("./entity.descriptor.interface"), exports);
 __exportStar(require("./entity.schema.interface"), exports);
+__exportStar(require("./external.entity.source.interface"), exports);
 __exportStar(require("./message.interface"), exports);
+__exportStar(require("./s3.key-access.policy.interface"), exports);
 __exportStar(require("./seed.context.interface"), exports);
 __exportStar(require("./token.usage.interface"), exports);
 __exportStar(require("./langchain.usage.interface"), exports);

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/interfaces/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,oEAAkD;AAClD,wDAAsC;AACtC,gEAA8C;AAC9C,4DAA0C;AAC1C,sDAAoC;AACpC,2DAAyC;AACzC,0DAAwC;AACxC,8DAA4C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/interfaces/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8DAA4C;AAC5C,8DAA4C;AAC5C,oEAAkD;AAClD,wDAAsC;AACtC,gEAA8C;AAC9C,4DAA0C;AAC1C,qEAAmD;AACnD,sDAAoC;AACpC,mEAAiD;AACjD,2DAAyC;AACzC,0DAAwC;AACxC,8DAA4C"}

package/dist/common/interfaces/s3.key-access.policy.interface.d.ts

@@ -0,0 +1,48 @@
+/**
+ * S3 key access policy: an app-provided check deciding whether the current
+ * caller may act on a client-supplied object key through the `/s3` routes.
+ *
+ * The token is optional. When unbound, the `/s3` routes accept every
+ * well-formed key, as before. Bind it from a `@Global()` application module so
+ * the package `S3Module`, which imports no app modules, can resolve it.
+ */
+/** What the caller wants to do with the key. */
+export type S3KeyAction = "upload" | "download" | "delete";
+/**
+ * Parameters handed to the policy for one `/s3` request.
+ *
+ * `userId`, `companyId` and `roles` come from the request CLS context set by
+ * the JWT guard (the same values the repositories scope by).
+ */
+export interface S3KeyAccessParams {
+    key: string;
+    action: S3KeyAction;
+    isPublic: boolean;
+    userId?: string;
+    companyId?: string;
+    roles: string[];
+}
+/**
+ * Contract implemented by an application-provided S3 key access policy.
+ *
+ * Return false to refuse the request (HTTP 403).
+ */
+export interface S3KeyAccessPolicy {
+    canAccess(params: S3KeyAccessParams): boolean | Promise<boolean>;
+}
+/**
+ * Optional injection token resolving to an S3KeyAccessPolicy.
+ * When unbound, every well-formed key is accepted.
+ */
+export declare const S3_KEY_ACCESS_POLICY: unique symbol;
+/**
+ * True when `key` is a well-formed object key: a non-empty string that does
+ * not start with `/` and has no `..` path segment.
+ *
+ * MinIO, Azure and any URL-normalising proxy resolve `..` and a leading `/`
+ * in the request path, so such a key can address an object outside the
+ * prefix it appears to name. The `/s3` routes reject it whether or not a
+ * policy is bound.
+ */
+export declare function isWellFormedS3Key(key: unknown): key is string;
+//# sourceMappingURL=s3.key-access.policy.interface.d.ts.map

package/dist/common/interfaces/s3.key-access.policy.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.key-access.policy.interface.d.ts","sourceRoot":"","sources":["../../../src/common/interfaces/s3.key-access.policy.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClE;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CAK7D"}

package/dist/common/interfaces/s3.key-access.policy.interface.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * S3 key access policy: an app-provided check deciding whether the current
+ * caller may act on a client-supplied object key through the `/s3` routes.
+ *
+ * The token is optional. When unbound, the `/s3` routes accept every
+ * well-formed key, as before. Bind it from a `@Global()` application module so
+ * the package `S3Module`, which imports no app modules, can resolve it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3_KEY_ACCESS_POLICY = void 0;
+exports.isWellFormedS3Key = isWellFormedS3Key;
+/**
+ * Optional injection token resolving to an S3KeyAccessPolicy.
+ * When unbound, every well-formed key is accepted.
+ */
+exports.S3_KEY_ACCESS_POLICY = Symbol("S3_KEY_ACCESS_POLICY");
+/**
+ * True when `key` is a well-formed object key: a non-empty string that does
+ * not start with `/` and has no `..` path segment.
+ *
+ * MinIO, Azure and any URL-normalising proxy resolve `..` and a leading `/`
+ * in the request path, so such a key can address an object outside the
+ * prefix it appears to name. The `/s3` routes reject it whether or not a
+ * policy is bound.
+ */
+function isWellFormedS3Key(key) {
+    if (typeof key !== "string")
+        return false;
+    if (key.trim() === "")
+        return false;
+    if (key.startsWith("/"))
+        return false;
+    return !key.split("/").includes("..");
+}
+//# sourceMappingURL=s3.key-access.policy.interface.js.map

package/dist/common/interfaces/s3.key-access.policy.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.key-access.policy.interface.js","sourceRoot":"","sources":["../../../src/common/interfaces/s3.key-access.policy.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AA4CH,8CAKC;AApBD;;;GAGG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAEnE;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAAC,GAAY;IAC5C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1C,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC"}

package/dist/common/tokens.d.ts

@@ -144,6 +144,19 @@ export interface TokenUsageRecorderInterface {
  * be visible application-wide.
  */
 export declare const CREDIT_VALIDATOR: unique symbol;
+/**
+ * Gates interactive AI requests only (assistant, operator, MCP); falls back to
+ * CREDIT_VALIDATOR when unbound.
+ *
+ * Same `CreditValidatorInterface` contract as `CREDIT_VALIDATOR` above. It
+ * exists so an application can meter the interactive surfaces WITHOUT binding
+ * `CREDIT_VALIDATOR`, which also gates background ingestion (chunk and
+ * embedding processors park no-credit work as `PendingCredits`). Consumers
+ * resolve both tokens as `@Optional()` and pick with `pickInteractiveValidator`
+ * (`common/helpers/credit-gate.ts`): with this token unbound, behaviour is
+ * exactly the `CREDIT_VALIDATOR` behaviour documented above.
+ */
+export declare const INTERACTIVE_CREDIT_VALIDATOR: unique symbol;
 /**
  * Contract implemented by an application-provided credit validator.
  */

package/dist/common/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/common/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAE9E;;;;GAIG;AAGH,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,eAAe,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gBAAgB,CAAC,MAAM,EAAE;QACvB,MAAM,EAAE,mBAAmB,CAAC;QAC5B,IAAI,EAAE,MAAM,CAAC;QACb,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,sJAAsJ;QACtJ,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,6HAA6H;QAC7H,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB;;;;;WAKG;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,2DAA2D;QAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,eAAe,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;;;;OAOG;IACH,WAAW,CAAC,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/common/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAE9E;;;;GAIG;AAGH,eAAO,MAAM,YAAY,eAAyB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,eAAe,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,gBAAgB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5F;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,oBAAoB,eAAiC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,gBAAgB,CAAC,MAAM,EAAE;QACvB,MAAM,EAAE,mBAAmB,CAAC;QAC5B,IAAI,EAAE,MAAM,CAAC;QACb,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,sJAAsJ;QACtJ,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,6HAA6H;QAC7H,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB;;;;;WAKG;QACH,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,2DAA2D;QAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,eAAyC,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,eAAe,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;;;;OAOG;IACH,WAAW,CAAC,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D"}

package/dist/common/tokens.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CREDIT_VALIDATOR = exports.TOKEN_USAGE_RECORDER = exports.AUTH_CONTEXT_HOOK = exports.SYSTEM_ROLES = void 0;
+exports.INTERACTIVE_CREDIT_VALIDATOR = exports.CREDIT_VALIDATOR = exports.TOKEN_USAGE_RECORDER = exports.AUTH_CONTEXT_HOOK = exports.SYSTEM_ROLES = void 0;
 /**
  * Injection tokens for common module dependencies
  *
@@ -99,4 +99,17 @@ exports.TOKEN_USAGE_RECORDER = Symbol("TOKEN_USAGE_RECORDER");
  * be visible application-wide.
  */
 exports.CREDIT_VALIDATOR = Symbol("CREDIT_VALIDATOR");
+/**
+ * Gates interactive AI requests only (assistant, operator, MCP); falls back to
+ * CREDIT_VALIDATOR when unbound.
+ *
+ * Same `CreditValidatorInterface` contract as `CREDIT_VALIDATOR` above. It
+ * exists so an application can meter the interactive surfaces WITHOUT binding
+ * `CREDIT_VALIDATOR`, which also gates background ingestion (chunk and
+ * embedding processors park no-credit work as `PendingCredits`). Consumers
+ * resolve both tokens as `@Optional()` and pick with `pickInteractiveValidator`
+ * (`common/helpers/credit-gate.ts`): with this token unbound, behaviour is
+ * exactly the `CREDIT_VALIDATOR` behaviour documented above.
+ */
+exports.INTERACTIVE_CREDIT_VALIDATOR = Symbol("INTERACTIVE_CREDIT_VALIDATOR");
 //# sourceMappingURL=tokens.js.map

package/dist/common/tokens.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/common/tokens.ts"],"names":[],"mappings":";;;AAIA;;;;GAIG;AAEH,8BAA8B;AACjB,QAAA,YAAY,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAUnD;;;;;;;;;GASG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAS7D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAiCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACU,QAAA,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/common/tokens.ts"],"names":[],"mappings":";;;AAIA;;;;GAIG;AAEH,8BAA8B;AACjB,QAAA,YAAY,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;AAUnD;;;;;;;;;GASG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAS7D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACU,QAAA,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAC;AAiCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACU,QAAA,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAE3D;;;;;;;;;;;GAWG;AACU,QAAA,4BAA4B,GAAG,MAAM,CAAC,8BAA8B,CAAC,CAAC"}

package/dist/config/base.config.d.ts

@@ -3,9 +3,11 @@ import { ConfigChunkQueuesInterface } from "./interfaces/config.chunk.queues.int
 import { ConfigContentTypesInterface } from "./interfaces/config.content.types.interface";
 import { ConfigJobNamesInterface } from "./interfaces/config.job.names.interface";
 import { ConfigOperatorInterface } from "./interfaces/config.operator.interface";
+import { ConfigAssistantInterface } from "./interfaces/config.assistant.interface";
 import { ConfigPromptsInterface } from "./interfaces/config.prompts.interface";
 import { ConfigResponderInterface } from "./interfaces/config.responder.interface";
 import { ConfigSummariserInterface } from "./interfaces/config.summariser.interface";
+import { OAuthScopeDefinition } from "../foundations/oauth/constants/oauth.scopes";
 /**
  * How many chunk jobs the CHUNK worker processes at once. Default 50 —
  * historically a hardcoded literal on `ChunkProcessor`'s `@Processor` decorator.
@@ -53,6 +55,11 @@ export interface BaseConfigOptions {
      * Optional - `approvalTtlDays` defaults to 7 when omitted.
      */
     operator?: ConfigOperatorInterface;
+    /**
+     * Assistant behaviour switches (inline entity links).
+     * Optional - every switch defaults to off.
+     */
+    assistant?: ConfigAssistantInterface;
     /**
      * Additional queue IDs for chunk processing.
      * The library always registers its own CHUNK queue.
@@ -69,6 +76,12 @@ export interface BaseConfigOptions {
      * Defines the job names that processors use to match incoming jobs.
      */
     jobNames?: ConfigJobNamesInterface;
+    /**
+     * App-specific OAuth scopes registered on top of the built-ins
+     * (read, write, profile, mcp, admin). Exposed as `oauth.additionalScopes`.
+     * @default []
+     */
+    oauthScopes?: OAuthScopeDefinition[];
 }
 /**
  * Creates the base configuration object from environment variables.

package/dist/config/base.config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.config.d.ts","sourceRoot":"","sources":["../../src/config/base.config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,4CAA4C,CAAC;AACxF,OAAO,EAAE,2BAA2B,EAAE,MAAM,6CAA6C,CAAC;AAC1F,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAC;AACnF,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AA4IrF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAGlC,CAAC;AAEL;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAEnC;;;OAGG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAEjC,yFAAyF;IACzF,SAAS,CAAC,EAAE,wBAAwB,CAAC;IAErC,gFAAgF;IAChF,UAAU,CAAC,EAAE,yBAAyB,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IAEnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,0BAA0B,CAAC;IAEzC;;;OAGG;IACH,YAAY,CAAC,EAAE,2BAA2B,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,mBAAmB,CA0UjF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,UAAU,qBAAqB,CAAC"}
+{"version":3,"file":"base.config.d.ts","sourceRoot":"","sources":["../../src/config/base.config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,0BAA0B,EAAE,MAAM,4CAA4C,CAAC;AACxF,OAAO,EAAE,2BAA2B,EAAE,MAAM,6CAA6C,CAAC;AAC1F,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAC;AACnF,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AAErF,OAAO,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AAyKnF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAGlC,CAAC;AAEL;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,eAAe,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAEnC;;;OAGG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAEjC,yFAAyF;IACzF,SAAS,CAAC,EAAE,wBAAwB,CAAC;IAErC,gFAAgF;IAChF,UAAU,CAAC,EAAE,yBAAyB,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IAEnC;;;OAGG;IACH,SAAS,CAAC,EAAE,wBAAwB,CAAC;IAErC;;;;OAIG;IACH,WAAW,CAAC,EAAE,0BAA0B,CAAC;IAEzC;;;OAGG;IACH,YAAY,CAAC,EAAE,2BAA2B,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IAEnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,mBAAmB,CA2VjF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,UAAU,qBAAqB,CAAC"}

package/dist/config/base.config.js

@@ -36,6 +36,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.baseConfig = exports.CHUNK_QUEUE_CONCURRENCY = void 0;
 exports.createBaseConfig = createBaseConfig;
 const path = __importStar(require("path"));
+/**
+ * Reads an optional numeric env var, preserving the "unset" state.
+ *
+ * `parseFloat(x || "0")` — the pattern used for the mandatory rates — cannot
+ * express "not configured": it collapses an unset var onto a real, meaningful
+ * 0. Every field that omits itself from a provider request when absent needs
+ * the distinction, so it gets `undefined` instead. A non-numeric value is also
+ * `undefined`, so a typo falls back to the provider default rather than sending
+ * NaN on the wire.
+ */
+const optionalNumber = (value) => {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+};
+/**
+ * Reads an optional boolean env var as a TRI-STATE: unset stays `undefined`
+ * (send nothing, let the provider default apply), "true" is true, anything else
+ * is false. `x === "true"` alone would turn every unset flag into an explicit
+ * `false` on the wire — which is a different request.
+ */
+const optionalBoolean = (value) => value === undefined || value.trim() === "" ? undefined : value === "true";
 /**
  * Resolves one AI model tier from env. `suffix` is "" (normal), "_LITE", or
  * "_LARGE".
@@ -45,11 +68,14 @@ const path = __importStar(require("path"));
  *   provider as the base tier) inherits field-by-field from the normal `AI_*`
  *   vars — a lone `AI_MODEL_LITE` overrides only the model. Mirrors the
  *   existing VISION_ and AUDIO_ env fallback convention.
- * - EXCEPTION: `AI_REGION` and `AI_ALLOW_FALLBACKS` never inherit the base.
- *   They are per-MODEL routing (the OpenRouter provider pin), not provider-wide
- *   credentials, so inheriting them would pin a tier's overridden model to a
- *   provider that may not serve it (404/422). A tier that wants a pin must set
- *   `AI_REGION<suffix>` / `AI_ALLOW_FALLBACKS<suffix>` explicitly.
+ * - EXCEPTION: `AI_REGION` and `AI_ALLOW_FALLBACKS` inherit the base ONLY when
+ *   the tier also inherits the base MODEL (no `AI_MODEL<suffix>`). They are
+ *   per-MODEL routing (the OpenRouter provider pin), not provider-wide
+ *   credentials: a tier that overrides the model must not be pinned to a
+ *   provider that may not serve it (404/422), so it resolves them only from
+ *   `AI_REGION<suffix>` / `AI_ALLOW_FALLBACKS<suffix>`. A tier running the base
+ *   model keeps the base pin — dropping it silently routed that same model
+ *   through every OpenRouter provider, including ones the pin was set to avoid.
  * - A tier that switches to a DIFFERENT provider is standalone: no field
  *   inherits from the base tier, because base values (URL, API key, costs…)
  *   point at the wrong service. Each field resolves only from its suffixed
@@ -61,25 +87,26 @@ const buildAiTier = (suffix) => {
     const standalone = suffix !== "" && tierProvider !== "" && tierProvider !== baseProvider;
     const env = (key) => process.env[`${key}${suffix}`] || (standalone ? "" : process.env[key]) || "";
     // `region` and `allowFallbacks` describe per-MODEL routing (the OpenRouter
-    // provider pin), NOT shared credentials/endpoint. A tier that overrides only
+    // provider pin), NOT shared credentials/endpoint. A tier that overrides
     // AI_MODEL must not drag the base tier's pin onto a different model, or the
-    // provider 404s (model not served there) / 422s (rejects the oneOf). So these
-    // resolve strictly from the tier's own suffixed var and never inherit the
-    // base — unlike apiKey/url/instance/costs, which are provider-wide.
-    const own = (key) => process.env[`${key}${suffix}`] || "";
+    // provider 404s (model not served there) / 422s (rejects the oneOf), so for
+    // it these resolve strictly from the tier's own suffixed var. A tier that
+    // runs the base model (same provider, no AI_MODEL<suffix>) inherits the pin.
+    const runsBaseModel = !standalone && !process.env[`AI_MODEL${suffix}`];
+    const routing = (key) => process.env[`${key}${suffix}`] || (runsBaseModel ? process.env[key] : "") || "";
     const maxOutputTokens = env("AI_MAX_OUTPUT_TOKENS");
     // Conditional spread avoids `parseFloat("") = NaN` — when the env var is unset,
     // the field is omitted entirely so it stays `undefined` (no-discount fallback).
     const cachedInputCost = env("AI_CACHED_INPUT_COST_PER_1M_TOKENS");
     // Default true (matches OpenRouter's own default); only an explicit "false"
     // turns `region` into a hard pin.
-    const allowFallbacks = own("AI_ALLOW_FALLBACKS").toLowerCase() !== "false";
+    const allowFallbacks = routing("AI_ALLOW_FALLBACKS").toLowerCase() !== "false";
     return {
         provider: tierProvider || baseProvider,
         apiKey: env("AI_API_KEY"),
         model: env("AI_MODEL"),
         url: env("AI_URL"),
-        region: own("AI_REGION"),
+        region: routing("AI_REGION"),
         secret: env("AI_SECRET"),
         instance: env("AI_INSTANCE"),
         apiVersion: env("AI_API_VERSION"),
@@ -414,6 +441,21 @@ function createBaseConfig(options) {
                 googleCredentialsBase64: process.env.IMAGE_GOOGLE_CREDENTIALS_BASE64 || "",
                 inputCostPer1MTokens: parseFloat(process.env.IMAGE_INPUT_COST_PER_1M_TOKENS || "0"),
                 outputCostPer1MTokens: parseFloat(process.env.IMAGE_OUTPUT_COST_PER_1M_TOKENS || "0"),
+                // Per-image billing (Venice and friends report no token usage at all).
+                // Undefined rather than 0 when unset, so "not configured" stays
+                // distinguishable from "configured as free".
+                costPerImage: optionalNumber(process.env.IMAGE_COST_PER_IMAGE),
+                // Venice `/image/generate` body defaults. Every one is undefined unless
+                // set, and ImageLLMService omits undefined keys from the request, so an
+                // unset var means "let Venice decide".
+                negativePrompt: process.env.IMAGE_NEGATIVE_PROMPT || undefined,
+                width: optionalNumber(process.env.IMAGE_WIDTH),
+                height: optionalNumber(process.env.IMAGE_HEIGHT),
+                steps: optionalNumber(process.env.IMAGE_STEPS),
+                cfgScale: optionalNumber(process.env.IMAGE_CFG_SCALE),
+                safeMode: optionalBoolean(process.env.IMAGE_SAFE_MODE),
+                hideWatermark: optionalBoolean(process.env.IMAGE_HIDE_WATERMARK),
+                imageFormat: process.env.IMAGE_FORMAT || undefined,
             },
             audio: buildAudioTier(""),
             audioDiarize: {
@@ -484,6 +526,7 @@ function createBaseConfig(options) {
             refreshTokenLifetime: parseInt(process.env.OAUTH_REFRESH_TOKEN_LIFETIME || "604800"),
             requirePkceForPublicClients: process.env.OAUTH_REQUIRE_PKCE_FOR_PUBLIC_CLIENTS !== "false",
             rotateRefreshTokens: process.env.OAUTH_ROTATE_REFRESH_TOKENS !== "false",
+            additionalScopes: options?.oauthScopes ?? [],
         },
         mcp: {
             enabled: process.env.MCP_ENABLED === "true",
@@ -528,6 +571,7 @@ function createBaseConfig(options) {
         responder: options?.responder ?? {},
         summariser: options?.summariser ?? {},
         operator: options?.operator ?? {},
+        assistant: options?.assistant ?? {},
         chunker: {
             strategy: process.env.CHUNKER_STRATEGY || "markdown-structural",
             ocrLanguage: process.env.OCR_LANGUAGE || "eng",