@starci/eslint-canon-be 3.7.0 → 3.7.1

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,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.7.1 - 2026-10-29
4
+
5
+ - Changed: the entity registry (persistence.md BE-PERSISTENCE-3, Debug ruling on lite-persistence-typeorm-entities): the bundled slot manifest 3.10.0 adds the lite slot `be.platform.database.entities`, the entity registry (slot fields `role: entity-registry` and `importedBy`, validated by the manifest shape); the bundled architecture machine reads it (`architecture/entity-registry.mjs`): `tier-direction` (R26 `BE_TIER_DIRECTION`) admits the registry's import of a domain or platform capability's `index.ts` that binds only that capability's `<c>Entities`, and `owner-export-bypass` (R30 `ARCH_OWNER_EXPORT_BYPASS`) admits a direct import of the registry from the files `importedBy` names (`apps/*/src/compose/*.ts`, `apps/*/src/app.module.ts`, `src/tests/world/**`); every other import of either shape stays refused, and full has no registry. `import-owner-entry` (R30) admits the deep path `@modules/platform/database/entities` from the same importers only. Spec: `src/entity-registry.spec.ts`.
6
+ - Changed: the bundled canon pins name hfs 4.10.1, eslint-canon-be 3.7.1, eslint-canon-fe 9.5.1 and the Grammar family 0.15.12.
7
+ - Changed: the owner-cycle check (R27 `ARCH_OWNER_CYCLE`) counts the entity registry as a unit of its own, not part of `platform/database`, so naming every `<c>Entities` closes no cycle among capabilities while any other platform/database file importing a domain still does (spec in `src/entity-registry.spec.ts`); the bundled rule catalog's R26 and R30 laws name the entity registry.
8
+
3
9
  ## 3.7.0 - 2026-10-29
4
10
 
5
11
  - Added: the `auth-passport` law (contexts/code/be/api-auth.md BE-AUTH-2): `own-jwks-only` (R329 `BE_AUTH_JWT_OWN_JWKS`) refuses `createRemoteJWKSet`, `decodeJwt` and `decodeProtectedHeader` of jose anywhere and `jwtVerify` outside `integrations/passport`; `refresh-token-cookie-only` (R330 `BE_AUTH_REFRESH_COOKIE`) refuses a `refreshToken`/`refresh_token` property or member and a refresh cookie set or cleared outside `integrations/passport`.
@@ -51,6 +51,10 @@ export interface HfsSlot {
51
51
  readonly trigger?: string;
52
52
  readonly coverage?: string;
53
53
  readonly allows?: readonly string[];
54
+ /** The one special part a file slot plays that a rule reads: `entity-registry` (persistence.md BE-PERSISTENCE-3). */
55
+ readonly role?: string;
56
+ /** The side-relative path patterns of the only files that may import this file by deep path. */
57
+ readonly importedBy?: readonly string[];
54
58
  }
55
59
  /** A unit-tested role (`ruleParams.be.unitRoles`). */
56
60
  export interface HfsUnitRole {
@@ -7,7 +7,9 @@
7
7
  *
8
8
  * - `import-owner-entry` - a cross-owner import targets the owner's `index.ts` (`@modules/domain/plan`,
9
9
  * `@features/api/plan`), never a file inside it, and an alias that names a tier but no owner (`@modules/domain`) names
10
- * nothing importable. A same-owner import is relative and never goes through the owner's own `index.ts`.
10
+ * nothing importable. A same-owner import is relative and never goes through the owner's own `index.ts`. The entity
11
+ * registry (slot role `entity-registry`, `@modules/platform/database/entities`) is the one file reached by deep path, and only
12
+ * from the files its slot's `importedBy` names (persistence.md BE-PERSISTENCE-3).
11
13
  * - `no-self-module-alias` - inside an owner, imports are relative, never the owner's own alias.
12
14
  * - `no-relative-capability-escape` - a relative import never walks out of its own owner.
13
15
  * - `no-folder-reexport` - a specifier that names a directory is refused; a nested `index.ts` (any index that is not
@@ -23,6 +25,7 @@ import { posix } from "node:path";
23
25
  import { hfsOf } from "./lib/hfs.js";
24
26
  import { baseName } from "./lib/ports.js";
25
27
  import { resolveAlias } from "./lib/specifier.js";
28
+ import { ENTITY_REGISTRY_ROLE, registryImporter } from "../runtime/scripts/hfs/architecture/entity-registry.mjs";
26
29
  /** The tiers whose files belong to an owner with a root `index.ts`. */
27
30
  const OWNER_TIERS = new Set(["feature", "domain", "platform", "integrations"]);
28
31
  /**
@@ -64,6 +67,12 @@ const onSpecifiers = (check) => ({
64
67
  /** The public-surface width: the file's slot budget, else its tier's owner-slot budget, else a back-end owner default. */
65
68
  const indexExportBudget = (hfs, filename) => [hfs.slotOf(filename), `be.${hfs.tierOf(filename)}`, "be.domain", "be.feature"].map((id) => (id ? hfs.slot(id)?.budget?.indexExports : undefined)).find(Number.isInteger);
66
69
  // -- R30: import-owner-entry -----------------------------------------------------------------------
70
+ /** Whether `filename` may reach the import path `target` (absolute, no extension) by deep path: it is the entity registry and its slot's `importedBy` names the importer. */
71
+ const importsRegistry = (hfs, filename, target) => {
72
+ const id = hfs.slotOf(`${target}.ts`);
73
+ const slot = id ? hfs.slot(id) : undefined;
74
+ return slot?.role === ENTITY_REGISTRY_ROLE && registryImporter(null, slot, hfs.relative(filename));
75
+ };
67
76
  /**
68
77
  * A cross-owner import targets the owner's public entry: the alias and the owner, nothing deeper. A same-owner import
69
78
  * is relative and never goes through the owner's own `index.ts` (BE-CONVENTION 2.4).
@@ -111,7 +120,7 @@ export const importOwnerEntry = {
111
120
  return;
112
121
  const ownerAbsolute = absolute(hfs, owner);
113
122
  const inside = alias.target === ownerAbsolute ? "" : alias.target.slice(ownerAbsolute.length + 1);
114
- if (inside !== "" && inside !== "index")
123
+ if (inside !== "" && inside !== "index" && !importsRegistry(hfs, filename, alias.target))
115
124
  context.report({ node, messageId: "deep", data: { specifier } });
116
125
  });
117
126
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.7.0",
3
+ "version": "3.7.1",
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.11
34
+ version: 0.15.12
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.7.0
41
+ version: 3.7.1
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.5.0
48
+ version: 9.5.1
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.11
55
+ version: 0.15.12
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.11
62
+ version: 0.15.12
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.10.0
109
+ version: 4.10.1
110
110
  group: starci
111
111
  install: registry
112
112
  side: both
@@ -474,7 +474,7 @@ rules:
474
474
  witness:
475
475
  - {path: packages/eslint/be/legacy-owner-graph.a16.spec.mjs, editions: [lite, full]}
476
476
  templateNa: "Tier and package direction are constraints on cross-owner import graphs; no dedicated cross-owner graph scaffold is generated."
477
- law: "The tier direction matrix; a shared package never imports an app. Front-end page and layout owners may import overlay entries; every other cross-owner feature-to-feature edge is forbidden, including layout-to-page and overlay-to-overlay. Components never import overlays."
477
+ law: "The tier direction matrix; a shared package never imports an app. Front-end page and layout owners may import overlay entries; every other cross-owner feature-to-feature edge is forbidden, including layout-to-page and overlay-to-overlay. Components never import overlays. The one platform-to-domain edge is the lite entity registry (be.platform.database.entities) importing a capability's `<c>Entities` alone from its `index.ts`."
478
478
  kinds: [lint, design]
479
479
  gates: [settle, land, ci]
480
480
  failureCodes: ["BE_TIER_DIRECTION", "FE_TIER_DIRECTION", "ARCH_PACKAGE_IMPORTS_APP"]
@@ -541,7 +541,7 @@ rules:
541
541
  - {path: packages/eslint/be/a16-r29-r31.spec.mjs, edition: full}
542
542
  - id: R30
543
543
  code: "BE_PUBLIC_SURFACE"
544
- law: "Every owner has one `index.ts`; cross-owner imports use it, same-owner imports are relative and never go through it; it holds only named `export { }` lines, no `export *`, no alias re-export (`export { X as Y }`, `export const Y = X`, `export type Y = X`, `export interface Y extends X {}`: one declaration has one name), within the owner slot's `indexExports` budget (60 for domain and feature owners, 80 for `be.integrations` provider entries); cross-package imports use the package name and a declared export."
544
+ law: "Every owner has one `index.ts`; cross-owner imports use it, except the lite entity registry, reached by deep path only from the files its slot's `importedBy` names; same-owner imports are relative and never go through it; it holds only named `export { }` lines, no `export *`, no alias re-export (`export { X as Y }`, `export const Y = X`, `export type Y = X`, `export interface Y extends X {}`: one declaration has one name), within the owner slot's `indexExports` budget (60 for domain and feature owners, 80 for `be.integrations` provider entries); cross-package imports use the package name and a declared export."
545
545
  kinds: [lint, codemod]
546
546
  gates: [settle, land, ci]
547
547
  failureCodes: ["BE_PUBLIC_SURFACE", "ARCH_OWNER_EXPORT_BYPASS", "ARCH_OWNER_EXPORT_STAR", "HFS_ALIAS_REEXPORT", "ARCH_PACKAGE_EXPORT_BYPASS"]
@@ -7,7 +7,7 @@
7
7
  # catalog READ this file through scripts/hfs/slots.mjs; none of them hardcodes a path.
8
8
  # Shape: modules/schemas/hfs-slots.schema.yaml. The repository side is hfs.json: modules/schemas/hfs-repo.schema.yaml.
9
9
  schema: starci/hfs-slots@3
10
- version: 3.9.0
10
+ version: 3.10.0
11
11
 
12
12
  versioning:
13
13
  # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -48,6 +48,8 @@ versioning:
48
48
  # 2026-10-24: lite may serve SSE, and SSE is the default door for one-way push), and lets fe.modules.api hold the SSE stream operations (sse/).
49
49
  # 3.7.0 is a minor (alpha.31): it ADDS the optional app.scripts.integration slot (scripts/integration/*.mjs, the product test-support scripts that only the integration harness runs) and the optional fe.transport.stream slot, the fetch reader of server-sent-events streams (the stream half of the
50
50
  # transport client layer), and lets fe.hooks.swr hold the SWR subscription hooks (api/sse/subscriptions/useSubscribe<X>Swr.ts, one useSWRSubscription per stream operation).
51
+ # 3.10.0 is a minor (2026-10-29): it ADDS the lite be.platform.database.entities slot, the entity registry (slot fields role and importedBy), so the
52
+ # tier matrix and the public-entry rules admit exactly its <c>Entities imports and its deep importers (persistence.md BE-PERSISTENCE-3).
51
53
 
52
54
  # Field meaning, per slot.
53
55
  # id stable name, never changes meaning inside a major.
@@ -68,6 +70,10 @@ versioning:
68
70
  # outcomeHome true on a file slot: the one file that declares the repository's Outcome union. A repository holds exactly one such
69
71
  # file (modules/api/outcome.ts, the api package's outcome.ts, or modules/db/outcome.ts of a lite app),
70
72
  # and no other file declares an Outcome union (one-outcome-union, FE_TRANSPORT_OWNER).
73
+ # role on a file slot: the one part it plays that a rule reads. entity-registry = the lite PRIMARY_ENTITIES list
74
+ # (be.platform.database.entities): the one platform file that imports capability <c>Entities, imported by deep path
75
+ # only from the files importedBy names (architecture/entity-registry.mjs).
76
+ # importedBy on a slot with a role: the side-relative path patterns of the only files that import its file by deep path.
71
77
  # requires files or directories that must exist inside each instance; <var> is replaced by the bound name,
72
78
  # a leading / means repository root; a trailing / means directory.
73
79
  # requiredInstances variable -> names that must exist as instances (config, logging ... of platform).
@@ -1711,6 +1717,21 @@ slots:
1711
1717
  coverage: required
1712
1718
  budget: {indexExports: 60}
1713
1719
  rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE]
1720
+ - id: be.platform.database.entities
1721
+ since: 3.10.0
1722
+ profiles: [be]
1723
+ editions: [lite]
1724
+ editionWhy: "lite registers the one PRIMARY_ENTITIES list on its single primary connection; full registers each capability's <c>Entities per connection from persistence/connection.ts."
1725
+ path: "src/modules/platform/database/entities.ts"
1726
+ presence: optional
1727
+ tracked: tracked
1728
+ tier: inherit
1729
+ role: entity-registry
1730
+ importedBy: ["apps/*/src/compose/*.ts", "apps/*/src/app.module.ts", "src/tests/world/**"]
1731
+ tests: none
1732
+ coverage: none
1733
+ why: "the entity registry (persistence.md BE-PERSISTENCE-3): it lists every capability's <c>Entities array by name, no glob, as PRIMARY_ENTITIES, the one list the primary connection maps, and exports nothing else. It is the one platform file that imports domain and platform capabilities, each import naming only that capability's <c>Entities from its index.ts (BE_TIER_DIRECTION, ARCH_OWNER_EXPORT_BYPASS); DatabaseModule and the platform/database index never import it, and only the files importedBy names (app composition and the test world) import it, by the deep path @modules/platform/database/entities (BE_PUBLIC_SURFACE), since database.module, this list and the capability indexes would otherwise form a cycle that fails at boot"
1734
+ rules: [BE_TIER_DIRECTION, BE_PUBLIC_SURFACE, BE_SCHEMA_OWNER]
1714
1735
  - id: be.platform.logging
1715
1736
  since: 3.5.0
1716
1737
  profiles: [be]
@@ -0,0 +1,53 @@
1
+ import { braceVariants, globExpression } from '../../lib/glob.mjs';
2
+
3
+ /**
4
+ * The entity registry (persistence.md BE-PERSISTENCE-3): the one file whose slot plays `role: entity-registry`
5
+ * (`be.platform.database.entities`, lite's `src/modules/platform/database/entities.ts`). It lists every capability's `<c>Entities`
6
+ * array as `PRIMARY_ENTITIES`, so it is the one platform file that imports domain and platform capability barrels, and only for
7
+ * that name; and it is imported by deep path only from the files its slot's `importedBy` names (app composition and the test world).
8
+ * The tier matrix (tiers.mjs), the public-entry check (owners.mjs) and the lint rule `import-owner-entry` read it here.
9
+ */
10
+ export const ENTITY_REGISTRY_ROLE = 'entity-registry';
11
+
12
+ /** The tiers whose capabilities contribute an entity list to the registry. */
13
+ const CONTRIBUTING_TIERS = new Set(['domain', 'platform']);
14
+
15
+ /** The entity list a capability exports: `<c>Entities`, `<c>` its folder name in camelCase. */
16
+ export const entityListName = capability => `${capability.replace(/-([a-z0-9])/g, (_, next) => next.toUpperCase())}Entities`;
17
+
18
+ /** The slot of `file` (side-relative or absolute) when it plays the entity-registry role, else null. */
19
+ export function registrySlot(resolver, file) {
20
+ const slot = resolver?.slotOf?.(file);
21
+ return slot?.role === ENTITY_REGISTRY_ROLE ? slot : null;
22
+ }
23
+
24
+ /**
25
+ * Whether `file` is one of the importers the registry slot admits by deep path (`importedBy`, side-relative patterns); an app-wide
26
+ * resolver answers for a side-prefixed path (`be/apps/...`), which is read without its side folder.
27
+ */
28
+ export function registryImporter(resolver, slot, file) {
29
+ const side = resolver?.sideOf?.(file);
30
+ const rel = side ? file.slice(side.length + 1) : file;
31
+ return (slot.importedBy ?? []).some(pattern => braceVariants(pattern).some(variant => globExpression(variant).test(rel)));
32
+ }
33
+
34
+ /** The names an import declaration binds by name; null for a default, namespace or side-effect import and for any re-export. */
35
+ function namedImports(declaration) {
36
+ const clause = declaration?.importClause;
37
+ if (!clause || clause.name || !Array.isArray(clause.namedBindings?.elements) || !clause.namedBindings.elements.length) return null;
38
+ return clause.namedBindings.elements.map(element => (element.propertyName ?? element.name).text);
39
+ }
40
+
41
+ /**
42
+ * Whether an owner-graph edge (side-relative `from` and `to`, `edge.declaration` the TypeScript statement) is the registry naming a
43
+ * capability's entity list: it leaves the registry, imports the public entry (`index.ts`) of a domain or platform capability, and
44
+ * binds that capability's `<c>Entities` and nothing else.
45
+ */
46
+ export function registryListImport(resolver, edge) {
47
+ if (!registrySlot(resolver, edge.from)) return false;
48
+ const owner = resolver.ownerOf(edge.to);
49
+ if (!owner || !CONTRIBUTING_TIERS.has(resolver.slot(owner.slot)?.tier) || edge.to !== `${owner.root}/index.ts`) return false;
50
+ const names = namedImports(edge.edge?.declaration ?? edge.declaration);
51
+ const listName = entityListName(owner.root.split('/').at(-1));
52
+ return names !== null && names.every(name => name === listName);
53
+ }
@@ -4,6 +4,7 @@ import { relativePath, workspaceExportSources } from './typescript.mjs';
4
4
  import { sourceLocation } from '../../lib/ts-ast.mjs';
5
5
  import { globExpression } from '../../lib/glob.mjs';
6
6
  import { posixPath } from '../../lib/path-key.mjs';
7
+ import { registryImporter, registrySlot } from './entity-registry.mjs';
7
8
 
8
9
  function absolute(root, relative) {
9
10
  return canonical(path.resolve(root, ...relative.split('/')));
@@ -68,6 +69,15 @@ function arrangesSchema(config, from, to) {
68
69
  && resolver.classifyPath(relativePath(config.root, to)).slot === 'be.persistence';
69
70
  }
70
71
 
72
+ /**
73
+ * The entity registry (slot role entity-registry, entity-registry.mjs) is imported by deep path, and only from the files its slot's
74
+ * `importedBy` names: app composition and the test world. Any other importer goes through the owner's entry, which never exports it.
75
+ */
76
+ function importsRegistry(config, from, to) {
77
+ const slot = registrySlot(config.hfs, relativePath(config.root, to));
78
+ return slot !== null && registryImporter(config.hfs, slot, relativePath(config.root, from));
79
+ }
80
+
71
81
  function publicEntryViolations(config, context, owners, sourceFiles) {
72
82
  const violations = [];
73
83
  for (const owner of owners) {
@@ -104,6 +114,7 @@ function ownerImportViolations(config, context, owners) {
104
114
  const bypass = privateOwnerChain(context, owners, edge);
105
115
  if (!bypass) continue;
106
116
  if (arrangesSchema(config, from, bypass.chain.at(-1))) continue;
117
+ if (bypass.chain.length === 2 && importsRegistry(config, from, bypass.chain.at(-1))) continue;
107
118
  violations.push({
108
119
  ruleId: 'ARCH_OWNER_EXPORT_BYPASS',
109
120
  path: relativePath(config.root, from),
@@ -1,4 +1,5 @@
1
1
  import { byCodeUnit } from '../../lib/list.mjs';
2
+ import { registryListImport, registrySlot } from './entity-registry.mjs';
2
3
 
3
4
  /**
4
5
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
@@ -8,7 +9,9 @@ import { byCodeUnit } from '../../lib/list.mjs';
8
9
  * kind (slot field `trigger`: api, webhooks, realtime, saga, reactors, jobs, cli) importing a feature of another is
9
10
  * BE_KIND_ISOLATION, whose fix is the event bus,
10
11
  * an app never imports another app (BE_SERVICE_ISOLATION / FE_APP_ISOLATION), and a component layer imports only the layers after it;
11
- * 2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE),
12
+ * the entity registry naming a capability's `<c>Entities` from its public entry is the one platform-to-domain edge (entity-registry.mjs);
13
+ * 2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE), the entity
14
+ * registry counted as a unit of its own,
12
15
  * reported with the cycle path and the import that closes each hop.
13
16
  * Importing inside one owner is always allowed; the public-entry rule stays with owners.mjs (ARCH_OWNER_EXPORT_BYPASS).
14
17
  */
@@ -138,15 +141,23 @@ function inspectTierEdge(graph, edge, tierRule, counts, violations, coverage) {
138
141
  return;
139
142
  }
140
143
  coverage.edgesChecked += 1;
144
+ if (verdict.reason === 'tierDirection' && registryListImport(graph.resolver, edge)) return;
141
145
  reportReasonedTierViolation(graph, edge, verdict, tierRule, counts, violations);
142
146
  }
143
147
 
148
+ /**
149
+ * The cycle unit of a file: its owner unit, except the entity registry (entity-registry.mjs), which is a unit of its own. It sits in
150
+ * platform/database but is composition-level by role (it imports every capability's `<c>Entities`), so it never closes a cycle
151
+ * among capabilities through the owner it lives in.
152
+ */
153
+ const cycleUnit = (graph, resolver, rel) => (registrySlot(resolver, rel) ? `entity-registry:${rel}` : graph.unit(rel));
154
+
144
155
  function ownerAdjacency(graph, resolver) {
145
156
  const adjacency = new Map();
146
157
  const witness = new Map();
147
158
  for (const edge of graph.edges) {
148
- const a = graph.unit(edge.from);
149
- const b = graph.unit(edge.to);
159
+ const a = cycleUnit(graph, resolver, edge.from);
160
+ const b = cycleUnit(graph, resolver, edge.to);
150
161
  if (!a || !b || a === b) continue;
151
162
  if (resolver.tierOf(edge.from) === 'none' || resolver.tierOf(edge.to) === 'none') continue;
152
163
  if (!adjacency.has(a)) adjacency.set(a, new Set());
@@ -87,7 +87,9 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
87
87
  export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
88
88
  const strList = (v) => stringList(v);
89
89
 
90
- const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy'];
90
+ const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy'];
91
+ /** The roles a file slot may play that a rule reads (`role`): the entity registry of persistence.md BE-PERSISTENCE-3 (architecture/entity-registry.mjs). */
92
+ const SLOT_ROLES = ['entity-registry'];
91
93
  /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
92
94
  const LITE_OVERLAY_KEYS = ['path', 'requires', 'allows', 'forbids', 'minInstances', 'requiredInstances', 'why'];
93
95
  /** A runtime slot has no app kind, side composition, layer or managed template; it may name the generator of a generated copy. */
@@ -249,6 +251,8 @@ function slotEntryProblems(slot, at) {
249
251
  else if (Array.isArray(slot.allows) && slot.entries.some((entry) => !slot.allows.includes(entry))) bad.push(`${at}: every entry must be one of the names the slot allows`);
250
252
  }
251
253
  if (slot.outcomeHome !== undefined && !(slot.outcomeHome === true && typeof slot.path === 'string' && slot.path && !slot.path.endsWith('/'))) bad.push(`${at}: outcomeHome is true and belongs to a file slot (the one file that declares the repository's Outcome union)`);
254
+ if (slot.role !== undefined && !(SLOT_ROLES.includes(slot.role) && typeof slot.path === 'string' && slot.path && !slot.path.endsWith('/'))) bad.push(`${at}: role is one of ${SLOT_ROLES.join(', ')} and belongs to a file slot`);
255
+ if (slot.importedBy !== undefined && !(slot.role !== undefined && strList(slot.importedBy) && slot.importedBy.length && new Set(slot.importedBy).size === slot.importedBy.length && slot.importedBy.every(relPath))) bad.push(`${at}: importedBy is a non-empty list of unique relative path patterns of the only files that import the slot's file by deep path, on a slot with a role`);
252
256
  return bad;
253
257
  }
254
258