@starci/eslint-canon-be 3.6.4 → 3.6.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,7 +1,23 @@
1
1
  # Changelog
2
2
 
3
- ## Unreleased
3
+ ## 3.6.8 - 2026-10-29
4
4
 
5
+ - Added: the `ai-gateway` law (contexts/code/be/ai.md). `provider-key-custody` (R326 `BE_AI_KEY_CUSTODY`) refuses an upstream provider key variable (`PROVIDER_KEY_VARIABLES` of `src/ai-gateway.ts`, the one list: `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and the rest, with their `_FILE` twins) named in a literal, a member or a property anywhere but the gateway's custody owner `integrations/ai-gateway`, specs and the test world included. `ai-client-through-gateway` (R327 `BE_AI_GATEWAY_CLIENT`) lets code build only `ChatOpenAI` and `OpenAIEmbeddings` of `@langchain/openai` (found by import), each from an inline options object with no spread, `configuration.baseURL` a member of a `<c>.options.ts` type and `apiKey` the `reveal()` of a `platform/config` `Secret`.
6
+ - Changed: the bundled slot manifest gives the model libraries their owners in `ruleParams.be.infraOwners` (`@starci/ai-router` to `integrations/ai-gateway`, `@langchain/*` to `integrations/ai`; `openai`, `langchain`, `@langchain/langgraph`, `@langchain/community` and the provider SDKs nowhere) and lists R326 and R327 on `be.integrations`, so `infra-import-owner` (R90) holds LangChain in one integration and refuses provider SDKs and agent frameworks; its `nowhere` message names the model and agent owners. The bundled rule catalog carries R326 and R327; the bundled canon pins name hfs 4.9.11, eslint-canon-be 3.6.8, eslint-canon-fe 9.4.9, the Grammar family 0.15.10 (grammar, eslint-grammar-core, eslint-grammar-offset-pop), and pin `@langchain/core` 1.3.1 and `@langchain/openai` 1.8.0.
7
+
8
+ ## 3.6.7 - 2026-10-29
9
+
10
+ - Changed: the bundled canon pins name hfs 4.9.10, eslint-canon-be 3.6.7, eslint-canon-fe 9.4.8, eslint-grammar-core 0.15.9 and eslint-grammar-offset-pop 0.15.9. No rule changed.
11
+
12
+ ## 3.6.6 - 2026-10-29
13
+
14
+ - Changed: the bundled canon pins name the Grammar family 0.15.8 (grammar, eslint-grammar-core, eslint-grammar-offset-pop), eslint-canon-fe 9.4.7 and eslint-canon-be 3.6.6. No rule changed.
15
+
16
+ ## 3.6.5 - 2026-10-29
17
+
18
+ - Changed: `starci-be/em-injection-slots` (R88) admits `platform/http-security` as a persistence capability: it owns the shared rate limit windows (BE-AUTH-4), and its guard counts in them through the primary `EntityManager`. Spec: `src/connections.spec.ts`.
19
+ - Changed: the bundled canon pins name hfs 4.9.9 and eslint-canon-be 3.6.5.
20
+ - Changed: the bundled canon pins name the Grammar family 0.15.7 (grammar, eslint-grammar-core, eslint-grammar-offset-pop) and eslint-canon-fe 9.4.6. No rule changed.
5
21
  - Changed: the bundled canon pins name the Grammar family 0.15.5 (grammar, eslint-grammar-core, eslint-grammar-offset-pop). No rule changed.
6
22
  - Changed: the bundled rule catalog states R225 with the app pre-push hook's dependency push gate (`starci deps check`). No rule changed.
7
23
 
package/README.md CHANGED
@@ -40,6 +40,7 @@ A sample, not the list:
40
40
  | **Errors** | A `catch` rethrows, calls a method on a `Logger` receiver (typed, from `platform/logging`) or returns an outcome carrying its cause; a `DomainError` subclass lives only in `errors/<capability>.error.ts` of its owner, and that file is one code enum, one `Record<Code, ErrorKind>` table and one empty class; a `throw` throws a `DomainError`, never a bare `Error`, a framework exception or a platform error out of a domain (`catch-must-account`, `error-home`, `throw-domain-error`, `error-family-shape`) |
41
41
  | **Schema authority** | Migrations only: every DataSource or TypeORM options object states the literal `synchronize: false` (found by the contextual type), no `migrationsRun`, no DDL string outside a migration, no entity glob; no `@Entity` type reachable from a transport signature, a handler `execute`, a contract or a message, and no GraphQL or validator import in an entity file (`no-runtime-schema`, `no-entity-in-contract`) |
42
42
  | **Config and secrets** | `process.env` (any form) is allowed in the `platform/config` file declaring `EnvSource`, the test world (slot `be.tests.world`) and the app bootstrap roles `apps/<app>/src/main.ts` and its matching `<app>.env.ts`; only those two app roles may read `EnvSource` or capability parse helpers. Compose groups and `<app>.options.ts` never read `process.env` or `EnvSource`. `@nestjs/config` and `dotenv` are forbidden config paths. A function exported by a `<capability>.config.ts` keeps its existing name and is called only from these bootstrap roles, its own config file or spec, the test world and a provider contract spec (`config-parsed-in-main`). Secrets use `EnvSource.secret()`: `<NAME>_FILE` takes priority for `.starcistacks` custody, and plain `<NAME>` is read only when the file key is absent; a declared file supplies exact contents and an empty or unreadable path fails startup without fallback. No default of any kind for a value typed `Secret` or `Url`; secrets compare with `timingSafeEqual` (`no-direct-env-read`, `config-parsed-in-main`, `no-secret-default`, `secret-compare-timing-safe`) |
43
+ | **Model calls** (R326, R327) | Every model call goes through the `@starci/ai-router` gateway: an upstream provider key variable (`PROVIDER_KEY_VARIABLES` of `src/ai-gateway.ts`, with its `_FILE` twin) is named only in the gateway's custody owner `integrations/ai-gateway`, specs and the test world included; code builds only `ChatOpenAI` and `OpenAIEmbeddings` of `@langchain/openai`, each from an inline options object whose `configuration.baseURL` is read from a `<c>.options.ts` type and whose `apiKey` is a `platform/config` `Secret` revealed. Which owner may import LangChain, `openai`, a provider SDK or an agent framework is the infrastructure table (`provider-key-custody`, `ai-client-through-gateway`, `infra-import-owner`) |
43
44
  | **Ambient ids** (R142) | `randomUUID` of Node's crypto (named, namespace or global), the `v1`, `v4`, `v6` and `v7` generators of `uuid`, `nanoid` and `ulid` are used only inside `platform/ids`, specs included: code asks the injected `Ids` port and a spec provides `fakeIds()`; the generators are found by the module they are imported from, never by a local name (`no-ambient-id`) |
44
45
  | **App composition** (R245, R246) | `apps/<app>/src/<app>.env.ts` exports an explicit typed `<App>Env` interface and `read<App>Env(env: EnvSource): <App>Env` (for example `ApiEnv` and `readApiEnv`). The interface declares its own readonly parsed members, such as `readonly server: ReturnType<typeof parseServerConfig>`, structurally compatible with the app's options. The role name stays `<app>.env.ts`, never `env.ts`; capability `<capability>.config.ts` files stay unchanged. `main.ts` creates `EnvSource` once, imports and calls the reader, builds options and boots. The env file holds fail-fast parsing only, with no localhost or default host fallback, logic, module composition, business code or feature imports; `<app>.options.ts` holds env-derived options and port bindings only, with no parsing. Both refuse an array listing `*Module` classes, module or queue registrations (`register`, `forRoot`, `registerQueue`) or scheduler entries, and an `imports`, `modules`, `schedulers` or `processors` list; the env file also refuses standalone module or queue registration calls. Composition belongs in a `compose/<area>.ts` group that `app.module.ts` spreads (`app-options-composition-free`, `BE_APP_OPTIONS_COMPOSITION`). Each app file stays within its slot's line budget: `main.ts` 80, env 150, options 200, group 120, root 250 (`app-file-budget`, `BE_APP_COMPOSITION_BUDGET`). The interface and reader exports are a documented scaffold contract; they need no new lint rule |
45
46
  | **Sonar parity** (R235) | The smells SonarCloud measures that a lint rule can decide: no `await` inside a loop (`no-await-in-loop`, S9382; `for (;;)` and `while (true)` are spared), no `charCodeAt`/`fromCharCode` (`prefer-code-point`), no string that only escapes backslashes (`prefer-string-raw`), no nested conditional (`no-nested-conditional`), `void` only on a call (`no-void-operator`), no unused import (`no-unused-import`), `export ... from` for an import that is only handed on (`prefer-export-from`); the factory also turns on typescript-eslint `no-deprecated`, `no-base-to-string` and `require-await`. The files `*.spec.ts` and `*.e2e-spec.ts` are outside the scan, so outside these rules |
@@ -0,0 +1,19 @@
1
+ import type { Recommended, RuleModule } from "./lib/rule.js";
2
+ /** The owner id (`<tier>/<capability>`) that holds the provider keys and registers the gateway's pool. */
3
+ export declare const GATEWAY_CUSTODY = "integrations/ai-gateway";
4
+ /**
5
+ * The upstream provider key variables, the one list: a key that reaches any of these providers is read only by the
6
+ * gateway's custody owner. A provider the gateway adds joins this list.
7
+ */
8
+ export declare const PROVIDER_KEY_VARIABLES: readonly string[];
9
+ /** Only the gateway's custody owner names an upstream provider key. */
10
+ export declare const providerKeyCustody: RuleModule;
11
+ /** The LangChain clients point at the gateway: base URL from options, virtual key from a `Secret`. */
12
+ export declare const aiClientThroughGateway: RuleModule;
13
+ /** The rules this law contributes to the plugin. */
14
+ export declare const rules: {
15
+ "provider-key-custody": RuleModule;
16
+ "ai-client-through-gateway": RuleModule;
17
+ };
18
+ /** Every rule of this law at `error`. */
19
+ export declare const recommended: Recommended;
@@ -0,0 +1,184 @@
1
+ /**
2
+ * The rules that hold model calls behind the ai-router gateway (catalog R326 `BE_AI_KEY_CUSTODY`, R327
3
+ * `BE_AI_GATEWAY_CLIENT`; contexts/code/be/ai.md BE-AI-1 and BE-AI-3).
4
+ *
5
+ * - `provider-key-custody` keeps every upstream provider key inside the gateway's custody owner, `integrations/ai-gateway`,
6
+ * the one owner that registers `@starci/ai-router` with the provider pool. Anywhere else a provider key variable
7
+ * (`PROVIDER_KEY_VARIABLES` below, the one list) is refused in any spelling a read can take: a string literal or a
8
+ * template without substitutions naming it or its `<NAME>_FILE` custody twin, and a non-computed member or property
9
+ * named like it (`process.env.OPENAI_API_KEY`, `{ OPENROUTER_API_KEY } = env`, `{ OPENAI_API_KEY: value }`). Specs and the
10
+ * test world are judged too: they reach a model through the gateway's fake provider, never with a provider key.
11
+ * - `ai-client-through-gateway` judges every `new` of an export of `@langchain/openai`, the one LangChain provider package:
12
+ * only `ChatOpenAI` and `OpenAIEmbeddings` are built, each from an inline options object with no spread, whose
13
+ * `configuration.baseURL` is a member read off an options type declared in a `<c>.options.ts` (the gateway URL the
14
+ * integration's config parsed), and whose `apiKey` is the `reveal()` of a `Secret` of `platform/config` (the gateway's
15
+ * virtual key). A literal provider URL, a missing base URL (the library falls back to the provider's own) and a
16
+ * missing key (the library falls back to `OPENAI_API_KEY`) are refused. The constructor is found by its import, never
17
+ * by its spelling.
18
+ *
19
+ * Which owner may import LangChain, `openai` or another provider SDK at all is the infrastructure table of the slot
20
+ * manifest (`ruleParams.be.infraOwners`, judged by `infra-import-owner`, R90).
21
+ */
22
+ import { keyName, staticText } from "./lib/ast.js";
23
+ import { originsOf } from "./lib/declared.js";
24
+ import { hfsOf } from "./lib/hfs.js";
25
+ import { importOf } from "./lib/import-source.js";
26
+ import { isOwnedType } from "./lib/ports.js";
27
+ /** The owner id (`<tier>/<capability>`) that holds the provider keys and registers the gateway's pool. */
28
+ export const GATEWAY_CUSTODY = "integrations/ai-gateway";
29
+ /**
30
+ * The upstream provider key variables, the one list: a key that reaches any of these providers is read only by the
31
+ * gateway's custody owner. A provider the gateway adds joins this list.
32
+ */
33
+ export const PROVIDER_KEY_VARIABLES = Object.freeze([
34
+ "OPENROUTER_API_KEY",
35
+ "OPENROUTER_KEY",
36
+ "OPENAI_API_KEY",
37
+ "OPENAI_KEY",
38
+ "ANTHROPIC_API_KEY",
39
+ "CLAUDE_API_KEY",
40
+ "GEMINI_API_KEY",
41
+ "GOOGLE_API_KEY",
42
+ "GOOGLE_GENERATIVE_AI_API_KEY",
43
+ "AZURE_OPENAI_API_KEY",
44
+ "MISTRAL_API_KEY",
45
+ "GROQ_API_KEY",
46
+ "DEEPSEEK_API_KEY",
47
+ "TOGETHER_API_KEY",
48
+ "FIREWORKS_API_KEY",
49
+ "COHERE_API_KEY",
50
+ "XAI_API_KEY",
51
+ "PERPLEXITY_API_KEY",
52
+ "HUGGINGFACEHUB_API_KEY",
53
+ "HF_TOKEN",
54
+ ]);
55
+ const PROVIDER_KEYS = new Set(PROVIDER_KEY_VARIABLES.flatMap((name) => [name, `${name}_FILE`]));
56
+ /** The LangChain provider package whose clients are judged, and the clients code may build from it. */
57
+ const LANGCHAIN_OPENAI = "@langchain/openai";
58
+ const GATEWAY_CLIENTS = new Set(["ChatOpenAI", "OpenAIEmbeddings"]);
59
+ /** The owner id of a file: the last two segments of its owner root, or null when no owner holds it. */
60
+ const ownerIdOf = (context, filename) => {
61
+ const root = hfsOf(context).ownerOf(filename);
62
+ return root === null ? null : root.split("/").slice(-2).join("/");
63
+ };
64
+ /** Only the gateway's custody owner names an upstream provider key. */
65
+ export const providerKeyCustody = {
66
+ meta: {
67
+ type: "problem",
68
+ docs: { description: "An upstream provider key variable (OPENROUTER_API_KEY, OPENAI_API_KEY, ...) is read only by the gateway's custody owner `integrations/ai-gateway`." },
69
+ schema: [],
70
+ messages: {
71
+ custody: "`{{name}}` is an upstream provider key, held only by the ai-router gateway's custody owner `integrations/ai-gateway`. Call a model through the gateway: the `integrations/ai` LangChain client with its virtual key (`sk-starci-...`), or the agent runtime's own virtual key.",
72
+ },
73
+ },
74
+ create(context) {
75
+ if (ownerIdOf(context, context.filename) === GATEWAY_CUSTODY)
76
+ return {};
77
+ const judge = (node, name) => {
78
+ if (name !== null && PROVIDER_KEYS.has(name))
79
+ context.report({ node, messageId: "custody", data: { name } });
80
+ };
81
+ return {
82
+ Literal(node) {
83
+ judge(node, staticText(node));
84
+ },
85
+ TemplateLiteral(node) {
86
+ judge(node, staticText(node));
87
+ },
88
+ MemberExpression(node) {
89
+ if (!node.computed)
90
+ judge(node.property, keyName(node.property));
91
+ },
92
+ Property(node) {
93
+ if (!node.computed && node.key.type === "Identifier")
94
+ judge(node.key, node.key.name);
95
+ },
96
+ };
97
+ },
98
+ };
99
+ /** The `@langchain/openai` export a constructor callee names, or null when it names none. */
100
+ const langchainExportOf = (context, callee) => {
101
+ const fromPackage = (source) => source === LANGCHAIN_OPENAI || source.startsWith(`${LANGCHAIN_OPENAI}/`);
102
+ if (callee.type === "Identifier") {
103
+ const binding = importOf(context, callee);
104
+ return binding !== null && fromPackage(binding.source) ? (binding.imported ?? "default") : null;
105
+ }
106
+ if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier") {
107
+ const binding = importOf(context, callee.object);
108
+ return binding?.imported === "*" && fromPackage(binding.source) ? keyName(callee.property) : null;
109
+ }
110
+ return null;
111
+ };
112
+ /** The value of a plain (non-computed, non-spread) property of an object literal, or null. */
113
+ const propertyOf = (object, name) => {
114
+ for (const property of object.properties) {
115
+ if (property.type === "Property" && !property.computed && keyName(property.key) === name)
116
+ return property.value;
117
+ }
118
+ return null;
119
+ };
120
+ /** True when the object literal, or any object literal nested in it, spreads another value in. */
121
+ const spreads = (object) => object.properties.some((property) => property.type === "SpreadElement" || (property.value.type === "ObjectExpression" && spreads(property.value)));
122
+ /** A member read off a value whose type a `<c>.options.ts` of the repository declares: the URL the integration's config parsed. */
123
+ const isOptionsMember = (context, node) => {
124
+ if (node.type !== "MemberExpression" || node.computed)
125
+ return false;
126
+ const hfs = hfsOf(context);
127
+ return originsOf(context, node.object).some((origin) => origin.file.endsWith(".options.ts") && hfs.slotOf(origin.file) !== null);
128
+ };
129
+ /** `secret.reveal()` on a `Secret` of `platform/config`: the virtual key handed to the library that needs it. */
130
+ const isRevealedSecret = (context, node) => node.type === "CallExpression" &&
131
+ node.arguments.length === 0 &&
132
+ node.callee.type === "MemberExpression" &&
133
+ !node.callee.computed &&
134
+ keyName(node.callee.property) === "reveal" &&
135
+ isOwnedType(context, node.callee.object, { name: "Secret", capability: "config", tier: "platform" });
136
+ /** The LangChain clients point at the gateway: base URL from options, virtual key from a `Secret`. */
137
+ export const aiClientThroughGateway = {
138
+ meta: {
139
+ type: "problem",
140
+ docs: { description: "Only `ChatOpenAI` and `OpenAIEmbeddings` of `@langchain/openai` are built, each with `configuration.baseURL` read from the integration's options and `apiKey` revealed from a `Secret`." },
141
+ schema: [],
142
+ messages: {
143
+ client: "`{{name}}` of `@langchain/openai` is not a gateway client. Build `ChatOpenAI` for chat and `OpenAIEmbeddings` for vectors, both pointed at the ai-router gateway; another provider is a pool entry of the gateway, never a client here.",
144
+ inline: "`{{name}}` takes an inline options object with no spread, so its base URL and key are visible here: `new {{name}}({ model, apiKey: this.options.virtualKey.reveal(), configuration: { baseURL: this.options.gatewayUrl } })`.",
145
+ baseUrl: "`{{name}}` needs `configuration.baseURL` read from the integration's options (`this.options.gatewayUrl`, parsed by its `<c>.config.ts`). A missing base URL calls the provider directly and a literal URL hard-codes one: every model call goes through the ai-router gateway.",
146
+ apiKey: "`{{name}}` needs `apiKey` set to the gateway's virtual key as `<secret>.reveal()` of a `Secret` from `platform/config` (`this.options.virtualKey.reveal()`). Without it the library reads `OPENAI_API_KEY` from the environment.",
147
+ },
148
+ },
149
+ create(context) {
150
+ return {
151
+ NewExpression(node) {
152
+ const name = langchainExportOf(context, node.callee);
153
+ if (name === null)
154
+ return;
155
+ if (!GATEWAY_CLIENTS.has(name)) {
156
+ context.report({ node, messageId: "client", data: { name } });
157
+ return;
158
+ }
159
+ const options = node.arguments[0];
160
+ if (node.arguments.length !== 1 || options?.type !== "ObjectExpression" || spreads(options)) {
161
+ context.report({ node, messageId: "inline", data: { name } });
162
+ return;
163
+ }
164
+ const configuration = propertyOf(options, "configuration");
165
+ const baseUrl = configuration?.type === "ObjectExpression" ? propertyOf(configuration, "baseURL") : null;
166
+ if (baseUrl === null || !isOptionsMember(context, baseUrl))
167
+ context.report({ node: baseUrl ?? node, messageId: "baseUrl", data: { name } });
168
+ const apiKey = propertyOf(options, "apiKey");
169
+ if (apiKey === null || !isRevealedSecret(context, apiKey))
170
+ context.report({ node: apiKey ?? node, messageId: "apiKey", data: { name } });
171
+ },
172
+ };
173
+ },
174
+ };
175
+ /** The rules this law contributes to the plugin. */
176
+ export const rules = {
177
+ "provider-key-custody": providerKeyCustody,
178
+ "ai-client-through-gateway": aiClientThroughGateway,
179
+ };
180
+ /** Every rule of this law at `error`. */
181
+ export const recommended = {
182
+ "starci-be/provider-key-custody": "error",
183
+ "starci-be/ai-client-through-gateway": "error",
184
+ };
@@ -214,7 +214,7 @@ export const emInjectionSlots = {
214
214
  docs: { description: "An `EntityManager` is injected only in application handlers, domain services, projections and the platform capabilities that own a `persistence/`." },
215
215
  schema: [],
216
216
  messages: {
217
- slot: "`EntityManager` is injected in a file of slot `{{slot}}`. Only an application `*.handler.ts`, a domain `*.service.ts`, a projection's `*.projection.ts` and the platform database, inbox, event-bus, queue and jobs capabilities reach the database. Transport dispatches a command or query, an integration calls its provider, an app composes: move the data access into a handler or a domain service.",
217
+ slot: "`EntityManager` is injected in a file of slot `{{slot}}`. Only an application `*.handler.ts`, a domain `*.service.ts`, a projection's `*.projection.ts` and the platform capabilities that own a `persistence/` (database, inbox, event-bus, queue, jobs, saga, outbox, realtime, http-security) reach the database. Transport dispatches a command or query, an integration calls its provider, an app composes: move the data access into a handler or a domain service.",
218
218
  },
219
219
  },
220
220
  create(context) {
package/dist/index.js CHANGED
@@ -18,6 +18,7 @@
18
18
  */
19
19
  import { buildBeConfig } from "./lib/config.js";
20
20
  import { pluginForEdition } from "./lib/edition.js";
21
+ import { recommended as aiGatewayRecommended, rules as aiGatewayRules } from "./ai-gateway.js";
21
22
  import { recommended as ambientIdRecommended, rules as ambientIdRules } from "./ambient-id.js";
22
23
  import { recommended as appCompositionRecommended, rules as appCompositionRules } from "./app-composition.js";
23
24
  import { recommended as asyncDisciplineRecommended, rules as asyncDisciplineRules } from "./async-discipline.js";
@@ -72,6 +73,7 @@ import { recommended as sonarParityRecommended, rules as sonarParityRules } from
72
73
  /** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
73
74
  const CONTRIBUTIONS = [
74
75
  { law: "project-graph", rules: projectGraphRules, recommended: projectGraphRecommended },
76
+ { law: "ai-gateway", rules: aiGatewayRules, recommended: aiGatewayRecommended },
75
77
  { law: "ambient-id", rules: ambientIdRules, recommended: ambientIdRecommended },
76
78
  { law: "app-composition", rules: appCompositionRules, recommended: appCompositionRecommended },
77
79
  { law: "async-discipline", rules: asyncDisciplineRules, recommended: asyncDisciplineRecommended },
@@ -1,10 +1,12 @@
1
1
  /**
2
2
  * The rule that holds BE-CONVENTION 1.10-1.14 (R90 `BE_INFRA_OWNER`).
3
3
  *
4
- * Every raw infrastructure library (HTTP, cache, queue, scheduler, logger, date, config, in-process events) has exactly
5
- * one owning platform or integration capability, and only files of that capability may import it or reach for it as a
6
- * global. The table lives in the slot manifest (`ruleParams.be.infraOwners`: specifier -> owners, `[]` for "nowhere"),
7
- * so the rule holds no library name of its own and the messages and the check read one source.
4
+ * Every raw infrastructure library (HTTP, cache, queue, scheduler, logger, date, config, in-process events, model SDKs)
5
+ * has exactly one owning platform or integration capability, and only files of that capability may import it or reach
6
+ * for it as a global. The table lives in the slot manifest (`ruleParams.be.infraOwners`: specifier -> owners, `[]` for
7
+ * "nowhere"), so the rule holds no library name of its own and the messages and the check read one source. A key covers
8
+ * its subpaths, so a scope key (`@langchain`) covers every package of the scope, and the longest key wins
9
+ * (`@langchain/langgraph` over `@langchain`).
8
10
  *
9
11
  * "Owning capability" is asked of the slot view (`ownerOf(filename)`), never of a path pattern. A reference is an
10
12
  * import (static, dynamic, `require`, `export ... from`) of the specifier or of a subpath of it, or a value reference to
@@ -53,7 +55,7 @@ export const infraImportOwner = {
53
55
  schema: [],
54
56
  messages: {
55
57
  foreign: "`{{name}}` is owned by {{owners}}. Use that capability's port (injected with its `Inject*()` decorator) instead of the raw library, or move this code into the owner.",
56
- nowhere: "`{{name}}` is not used in a back end: its job belongs to a platform port (config through the typed `<c>.config.ts`, events through `eventBus.publish(event, tx)` of `platform/event-bus`, schedules and background jobs through a queue's BullMQ job scheduler of `platform/queue`). Remove it.",
58
+ nowhere: "`{{name}}` is not used in a back end: its job belongs to another owner's port (config through the typed `<c>.config.ts`, events through `eventBus.publish(event, tx)` of `platform/event-bus`, schedules and background jobs through a queue's BullMQ job scheduler of `platform/queue`, a model call through the LangChain client of `integrations/ai` and the ai-router gateway, an agent loop in the agent runtime). Remove it.",
57
59
  },
58
60
  },
59
61
  create(context) {
@@ -95,7 +95,7 @@ export const connectionFileOf = (hfs, file, role) => {
95
95
  return connectionsOf(hfs).find((connection) => connection.name === name) ?? null;
96
96
  };
97
97
  /** The platform capabilities that own a `persistence/` and so may hold an `EntityManager` (a pattern capability is named by its folder). */
98
- const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jobs", "saga", "outbox", "realtime"];
98
+ const PERSISTENCE_CAPABILITIES = ["database", "inbox", "event-bus", "queue", "jobs", "saga", "outbox", "realtime", "http-security"];
99
99
  /**
100
100
  * Whether a class in this file may receive an `EntityManager`: an application handler, a domain service, a projection, a typed queue producer (it takes the transaction of its caller), a platform persistence capability.
101
101
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.6.4",
3
+ "version": "3.6.8",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -31,35 +31,35 @@ pins:
31
31
  source: packages/event-stream/package.json
32
32
  why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
33
33
  '@starci/grammar':
34
- version: 0.15.6
34
+ version: 0.15.10
35
35
  group: starci
36
36
  install: registry
37
37
  side: fe
38
38
  source: packages/grammar/package.json
39
39
  why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
40
40
  '@starci/eslint-canon-be':
41
- version: 3.6.4
41
+ version: 3.6.8
42
42
  group: starci
43
43
  install: registry
44
44
  side: be
45
45
  source: packages/eslint-canon-be/package.json
46
46
  why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
47
47
  '@starci/eslint-canon-fe':
48
- version: 9.4.5
48
+ version: 9.4.9
49
49
  group: starci
50
50
  install: registry
51
51
  side: fe
52
52
  source: packages/eslint-canon-fe/package.json
53
53
  why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
54
54
  '@starci/eslint-grammar-core':
55
- version: 0.15.6
55
+ version: 0.15.10
56
56
  group: starci
57
57
  install: registry
58
58
  side: fe
59
59
  source: packages/eslint-grammar-core/package.json
60
60
  why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
61
61
  '@starci/eslint-grammar-offset-pop':
62
- version: 0.15.6
62
+ version: 0.15.10
63
63
  group: starci
64
64
  install: registry
65
65
  side: fe
@@ -106,7 +106,7 @@ pins:
106
106
  source: packages/ai-router/package.json
107
107
  why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
108
108
  '@starci/hfs':
109
- version: 4.9.8
109
+ version: 4.9.11
110
110
  group: starci
111
111
  install: registry
112
112
  side: both
@@ -241,6 +241,16 @@ pins:
241
241
  group: framework
242
242
  side: be
243
243
  why: readiness probes with dependency indicators use Terminus (the liveness route of the scaffolded skeleton does not, being a thin door over the liveness service); every measured product back end resolves 11.1.1.
244
+ '@langchain/core':
245
+ version: 1.3.1
246
+ group: framework
247
+ side: be
248
+ why: 'the LangChain core of the one AI integration (BE-AI-3): prompt templates, output parsers, runnables and BaseRetriever; @langchain/openai takes it as its peer. The registry latest on 2026-10-29.'
249
+ '@langchain/openai':
250
+ version: 1.8.0
251
+ group: framework
252
+ side: be
253
+ why: 'ChatOpenAI and OpenAIEmbeddings of the one AI integration, pointed at the ai-router gateway with a virtual key (BE-AI-1, BE-AI-3, R327); peer @langchain/core ^1.3.1. The registry latest on 2026-10-29.'
244
254
  '@nestjs/cqrs':
245
255
  version: 11.0.3
246
256
  group: framework
@@ -1820,7 +1820,7 @@ rules:
1820
1820
  - {path: packages/eslint/be/be-r89-source-form-coverage.spec.mjs, edition: full, codes: [BE_SOURCE_FORM, BE_PUBLIC_CONTRACT_FORM]}
1821
1821
  - id: R90
1822
1822
  code: "BE_INFRA_OWNER"
1823
- law: "Each raw infrastructure library (HTTP, cache, queue, scheduler, logger, date, config, events) is imported or referenced only by its one owning platform or integration capability, and the `HttpClient` port of `platform/http` is called only by an `integrations` capability."
1823
+ law: "Each raw infrastructure library (HTTP, cache, queue, scheduler, logger, date, config, events, model SDKs) is imported or referenced only by its one owning platform or integration capability, and the `HttpClient` port of `platform/http` is called only by an `integrations` capability."
1824
1824
  kinds: [lint, codemod]
1825
1825
  failureCodes: ["BE_INFRA_OWNER"]
1826
1826
  enforcers:
@@ -5756,3 +5756,74 @@ rules:
5756
5756
  source: owner
5757
5757
  quote: "ok trò"
5758
5758
  ruling: "A route page is one Grammar Page (owner ruling page-frame): the single owner of the page inset and rhythm; the lint refuses a sibling beside the Page and a bare PageHeader or PageContainer in a page owner."
5759
+ - id: R326
5760
+ code: "BE_AI_KEY_CUSTODY"
5761
+ law: "An upstream model provider key variable (OPENROUTER_API_KEY, OPENAI_API_KEY and the rest of the canon's one list) is named only inside the ai-router gateway's custody owner integrations/ai-gateway, in a literal, a member or a destructured property; every other file reaches a model through the gateway with a virtual key."
5762
+ kinds: [lint]
5763
+ gates: [pre-commit, settle, land, ci]
5764
+ failureCodes: ["BE_AI_KEY_CUSTODY"]
5765
+ enforcers:
5766
+ - {kind: eslint-be, id: provider-key-custody}
5767
+ editions: [lite, full]
5768
+ docs: [contexts/code/be/ai.md]
5769
+ templateNa: "The skeleton scaffolds no model call; an app adds the ai and ai-gateway integrations when it calls a model."
5770
+ proves:
5771
+ - packages/eslint-canon-be/src/ai-gateway.spec.ts
5772
+ exemplifiedBy:
5773
+ - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_KEY_CUSTODY]}
5774
+ witness:
5775
+ - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_KEY_CUSTODY]}
5776
+ cases:
5777
+ - id: case-1
5778
+ date: "2026-10-29"
5779
+ source: owner
5780
+ quote: "nhớ làm langchain nhé update .claude lun là call thẳng từ code phải dùng langchain với embeded context"
5781
+ ruling: "A model call made straight from code uses LangChain with retrieved context, through the ai-router gateway (owner ruling be-ai-langchain-gateway): only the gateway's custody owner reads a provider key."
5782
+ - id: R327
5783
+ code: "BE_AI_GATEWAY_CLIENT"
5784
+ law: "Code builds only the ChatOpenAI and OpenAIEmbeddings clients of @langchain/openai, each from an inline options object with no spread, its configuration.baseURL read from a <c>.options.ts type and its apiKey the reveal() of a platform/config Secret, so every model call goes through the ai-router gateway with a virtual key."
5785
+ kinds: [lint]
5786
+ gates: [pre-commit, settle, land, ci]
5787
+ failureCodes: ["BE_AI_GATEWAY_CLIENT"]
5788
+ enforcers:
5789
+ - {kind: eslint-be, id: ai-client-through-gateway}
5790
+ editions: [lite, full]
5791
+ docs: [contexts/code/be/ai.md]
5792
+ templateNa: "The skeleton scaffolds no model call; an app adds the ai and ai-gateway integrations when it calls a model."
5793
+ proves:
5794
+ - packages/eslint-canon-be/src/ai-gateway.spec.ts
5795
+ exemplifiedBy:
5796
+ - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_GATEWAY_CLIENT]}
5797
+ witness:
5798
+ - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_GATEWAY_CLIENT]}
5799
+ cases:
5800
+ - id: case-1
5801
+ date: "2026-10-29"
5802
+ source: owner
5803
+ quote: "nhớ làm langchain nhé update .claude lun là call thẳng từ code phải dùng langchain với embeded context"
5804
+ ruling: "A model call made straight from code uses LangChain with retrieved context, through the ai-router gateway (owner ruling be-ai-langchain-gateway): the LangChain clients point at the gateway's base URL with its virtual key."
5805
+ - id: R333
5806
+ code: "BE_ENTITY_SCHEMA_DRIFT"
5807
+ law: "Every TypeORM entity column of an app's entity list (be/src/platform/database/entities.ts) matches the schema its SQL migrations build: `starci app db drift` applies db/bootstrap.sql and every active db/migrations/*.sql to a scratch database (a container of the app's db image, or the empty database --url-env names), reads information_schema.columns and pg_catalog, and refuses a missing table, a missing column, a type that differs once both are normalised to PostgreSQL's format_type names (an enum by its type name), and a nullability that differs. A database column no entity maps is fine. A host that cannot provide the scratch database gets no verdict (exit 2, needs a database), never a green."
5808
+ kinds: [check]
5809
+ gates: [ci]
5810
+ failureCodes: ["BE_ENTITY_SCHEMA_DRIFT"]
5811
+ enforcers:
5812
+ - {kind: hfs, id: db-drift, at: packages/hfs/db/drift.mjs}
5813
+ editions: [lite]
5814
+ editionWhy: "The owner ruling of 2026-10-29 maps lite tables with TypeORM entities while db/migrations/*.sql stays the only DDL and synchronize is false, so only lite entities can drift from a schema they do not create; full entities ship with their own TypeORM migrations."
5815
+ docs: [contexts/code/be/persistence.md]
5816
+ templateNa: "The entities and the migrations are the product's tables; the check judges whichever an app writes, and a template scaffolds no table."
5817
+ proves:
5818
+ - {path: packages/hfs/src/db-drift.spec.mjs, edition: lite, codes: [BE_ENTITY_SCHEMA_DRIFT]}
5819
+ - {path: packages/hfs/src/db-drift-docker.spec.mjs, edition: lite, codes: [BE_ENTITY_SCHEMA_DRIFT]}
5820
+ exemplifiedBy:
5821
+ - {path: packages/hfs/src/db-drift.spec.mjs, edition: lite, codes: [BE_ENTITY_SCHEMA_DRIFT]}
5822
+ witness:
5823
+ - {path: packages/hfs/src/db-drift.spec.mjs, edition: lite, codes: [BE_ENTITY_SCHEMA_DRIFT]}
5824
+ cases:
5825
+ - id: case-1
5826
+ date: "2026-10-29"
5827
+ source: owner
5828
+ quote: "lite persistence moves to TypeORM entities while db/migrations/*.sql stays the only DDL and synchronize is false"
5829
+ ruling: "Lite entities only map tables the migrations create, so each entity column is checked against the migrated schema by starci app db drift, which CI runs in the build job and the release gate runs as its db-drift row."
@@ -254,6 +254,25 @@ ruleParams:
254
254
  "@socket.io/postgres-adapter": [platform/realtime] # the stateless socket.io adapter of a scaled lite back end without Redis
255
255
  "@socket.io/redis-adapter": [platform/realtime] # the sharded socket.io adapter of a scaled back end on the declared Redis
256
256
  pg: [platform/realtime] # the LISTEN connection of the Postgres hub; every other query goes through TypeORM
257
+ # BE-AI-1, BE-AI-3: every model call goes through the ai-router gateway. Its custody owner registers @starci/ai-router with the
258
+ # provider keys; the one LangChain integration owns @langchain/*; no provider SDK, openai client or agent framework is imported.
259
+ "@starci/ai-router": [integrations/ai-gateway]
260
+ "@starci/ai-router/testing": [integrations/ai-gateway, integrations/ai] # the fake provider a spec of either side boots the gateway with
261
+ "@langchain": [integrations/ai] # a scope key: every @langchain/* package
262
+ "@langchain/langgraph": [] # an agent loop runs in the agent runtime, never in code
263
+ "@langchain/community": [] # retrieval reads the app's own persistence through its owner
264
+ langchain: [] # createAgent is an agent loop
265
+ openai: [] # code calls models through @langchain/openai
266
+ "@anthropic-ai/sdk": []
267
+ "@google/genai": []
268
+ "@google/generative-ai": []
269
+ "@mistralai/mistralai": []
270
+ "@openrouter/ai-sdk-provider": []
271
+ "@ai-sdk": []
272
+ ai: []
273
+ cohere-ai: []
274
+ groq-sdk: []
275
+ ollama: []
257
276
  # R87 BE_CQRS_SHAPE no-event-bus: the in-process event vocabulary the rule refuses. `imports` maps a module
258
277
  # specifier to the member names that are an in-process event; `[]` flags the package itself (its emitter packages
259
278
  # are the `[]` owners of infraOwners above). `classes` maps a module specifier to the class names that are an
@@ -1892,7 +1911,7 @@ slots:
1892
1911
  tests: unit-beside # <name>.service.spec.ts beside each <name>.service.ts; plus src/tests/integration/<provider>/ (R112)
1893
1912
  coverage: required
1894
1913
  budget: {indexExports: 80} # a provider's port surface includes clients, config, options, tokens and errors
1895
- rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING]
1914
+ rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING, BE_AI_KEY_CUSTODY, BE_AI_GATEWAY_CLIENT]
1896
1915
  - id: be.integrations.model
1897
1916
  since: 3.1.0
1898
1917
  profiles: [be]
@@ -1902,7 +1921,7 @@ slots:
1902
1921
  tier: integrations
1903
1922
  tests: none
1904
1923
  coverage: required
1905
- why: an ML or LLM model client is an integration; weights and datasets are never in git
1924
+ why: a self-hosted ML model client is an integration; weights and datasets are never in git, and a language model is called through the ai-router gateway by the integrations/ai LangChain client (BE-AI-1, BE-AI-3)
1906
1925
  rules: [BE_TIER_DIRECTION, BE_INFRA_OWNER, BE_INTEGRATION_SPEC_MISSING]
1907
1926
 
1908
1927
  - id: be.integrations.supabase