@starci/hfs 4.10.0 → 4.10.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 4.10.1 - 2026-10-29
+
+- Changed: 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; 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; the lite skeleton's `platform/database/entities.ts` names its importers (app composition and the test world).
+- Changed: the bundled architecture machine: 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; the bundled rule catalog's R26 and R30 laws name the entity registry.
+
 ## 4.10.0 - 2026-10-29
 
 Breaking for lite apps (ruling lite-self-hosted-postgres-passport-minio; the migration note is contexts/project/lite.md "Moving an app off Supabase").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.10.0",
+  "version": "4.10.1",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     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.'
   '@starci/grammar':
-    version: 0.15.11
+    version: 0.15.12
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     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.'
   '@starci/eslint-canon-be':
-    version: 3.7.0
+    version: 3.7.1
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     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.'
   '@starci/eslint-canon-fe':
-    version: 9.5.0
+    version: 9.5.1
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     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.'
   '@starci/eslint-grammar-core':
-    version: 0.15.11
+    version: 0.15.12
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.15.11
+    version: 0.15.12
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     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.'
   '@starci/hfs':
-    version: 4.10.0
+    version: 4.10.1
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -474,7 +474,7 @@ rules:
     witness:
       - {path: packages/eslint/be/legacy-owner-graph.a16.spec.mjs, editions: [lite, full]}
     templateNa: "Tier and package direction are constraints on cross-owner import graphs; no dedicated cross-owner graph scaffold is generated."
-    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."
+    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`."
     kinds: [lint, design]
     gates: [settle, land, ci]
     failureCodes: ["BE_TIER_DIRECTION", "FE_TIER_DIRECTION", "ARCH_PACKAGE_IMPORTS_APP"]
@@ -541,7 +541,7 @@ rules:
       - {path: packages/eslint/be/a16-r29-r31.spec.mjs, edition: full}
   - id: R30
     code: "BE_PUBLIC_SURFACE"
-    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."
+    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."
     kinds: [lint, codemod]
     gates: [settle, land, ci]
     failureCodes: ["BE_PUBLIC_SURFACE", "ARCH_OWNER_EXPORT_BYPASS", "ARCH_OWNER_EXPORT_STAR", "HFS_ALIAS_REEXPORT", "ARCH_PACKAGE_EXPORT_BYPASS"]

package/runtime/knowledge/hfs/slots.yaml

@@ -7,7 +7,7 @@
 # catalog READ this file through scripts/hfs/slots.mjs; none of them hardcodes a path.
 # Shape: modules/schemas/hfs-slots.schema.yaml. The repository side is hfs.json: modules/schemas/hfs-repo.schema.yaml.
 schema: starci/hfs-slots@3
-version: 3.9.0
+version: 3.10.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -50,6 +50,8 @@ versioning:
 # 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).
 # 3.8.0 is a minor (urgent release, 2026-10-29): it ADDS the optional fe.dev-server-generated slot (apps/*/AGENTS.md, which `next dev` rewrites) and the
 # slot field rewrittenBy, so the release gate's clean-tree check passes over an untracked file a declared dev server writes, and over nothing else.
+# 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
+# tier matrix and the public-entry rules admit exactly its <c>Entities imports and its deep importers (persistence.md BE-PERSISTENCE-3).
 
 # Field meaning, per slot.
 #   id          stable name, never changes meaning inside a major.
@@ -72,6 +74,10 @@ versioning:
 #   outcomeHome true on a file slot: the one file that declares the repository's Outcome union. A repository holds exactly one such
 #               file (modules/api/outcome.ts, the api package's outcome.ts, or modules/db/outcome.ts of a lite app),
 #               and no other file declares an Outcome union (one-outcome-union, FE_TRANSPORT_OWNER).
+#   role        on a file slot: the one part it plays that a rule reads. entity-registry = the lite PRIMARY_ENTITIES list
+#               (be.platform.database.entities): the one platform file that imports capability <c>Entities, imported by deep path
+#               only from the files importedBy names (architecture/entity-registry.mjs).
+#   importedBy  on a slot with a role: the side-relative path patterns of the only files that import its file by deep path.
 #   requires    files or directories that must exist inside each instance; <var> is replaced by the bound name,
 #               a leading / means repository root; a trailing / means directory.
 #   requiredInstances  variable -> names that must exist as instances (config, logging ... of platform).
@@ -1725,6 +1731,21 @@ slots:
     coverage: required
     budget: {indexExports: 60}
     rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE]
+  - id: be.platform.database.entities
+    since: 3.10.0
+    profiles: [be]
+    editions: [lite]
+    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."
+    path: "src/modules/platform/database/entities.ts"
+    presence: optional
+    tracked: tracked
+    tier: inherit
+    role: entity-registry
+    importedBy: ["apps/*/src/compose/*.ts", "apps/*/src/app.module.ts", "src/tests/world/**"]
+    tests: none
+    coverage: none
+    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"
+    rules: [BE_TIER_DIRECTION, BE_PUBLIC_SURFACE, BE_SCHEMA_OWNER]
   - id: be.platform.logging
     since: 3.5.0
     profiles: [be]

package/runtime/scripts/hfs/architecture/entity-registry.mjs

@@ -0,0 +1,53 @@
+import { braceVariants, globExpression } from '../../lib/glob.mjs';
+
+/**
+ * The entity registry (persistence.md BE-PERSISTENCE-3): the one file whose slot plays `role: entity-registry`
+ * (`be.platform.database.entities`, lite's `src/modules/platform/database/entities.ts`). It lists every capability's `<c>Entities`
+ * array as `PRIMARY_ENTITIES`, so it is the one platform file that imports domain and platform capability barrels, and only for
+ * that name; and it is imported by deep path only from the files its slot's `importedBy` names (app composition and the test world).
+ * The tier matrix (tiers.mjs), the public-entry check (owners.mjs) and the lint rule `import-owner-entry` read it here.
+ */
+export const ENTITY_REGISTRY_ROLE = 'entity-registry';
+
+/** The tiers whose capabilities contribute an entity list to the registry. */
+const CONTRIBUTING_TIERS = new Set(['domain', 'platform']);
+
+/** The entity list a capability exports: `<c>Entities`, `<c>` its folder name in camelCase. */
+export const entityListName = capability => `${capability.replace(/-([a-z0-9])/g, (_, next) => next.toUpperCase())}Entities`;
+
+/** The slot of `file` (side-relative or absolute) when it plays the entity-registry role, else null. */
+export function registrySlot(resolver, file) {
+  const slot = resolver?.slotOf?.(file);
+  return slot?.role === ENTITY_REGISTRY_ROLE ? slot : null;
+}
+
+/**
+ * Whether `file` is one of the importers the registry slot admits by deep path (`importedBy`, side-relative patterns); an app-wide
+ * resolver answers for a side-prefixed path (`be/apps/...`), which is read without its side folder.
+ */
+export function registryImporter(resolver, slot, file) {
+  const side = resolver?.sideOf?.(file);
+  const rel = side ? file.slice(side.length + 1) : file;
+  return (slot.importedBy ?? []).some(pattern => braceVariants(pattern).some(variant => globExpression(variant).test(rel)));
+}
+
+/** The names an import declaration binds by name; null for a default, namespace or side-effect import and for any re-export. */
+function namedImports(declaration) {
+  const clause = declaration?.importClause;
+  if (!clause || clause.name || !Array.isArray(clause.namedBindings?.elements) || !clause.namedBindings.elements.length) return null;
+  return clause.namedBindings.elements.map(element => (element.propertyName ?? element.name).text);
+}
+
+/**
+ * Whether an owner-graph edge (side-relative `from` and `to`, `edge.declaration` the TypeScript statement) is the registry naming a
+ * capability's entity list: it leaves the registry, imports the public entry (`index.ts`) of a domain or platform capability, and
+ * binds that capability's `<c>Entities` and nothing else.
+ */
+export function registryListImport(resolver, edge) {
+  if (!registrySlot(resolver, edge.from)) return false;
+  const owner = resolver.ownerOf(edge.to);
+  if (!owner || !CONTRIBUTING_TIERS.has(resolver.slot(owner.slot)?.tier) || edge.to !== `${owner.root}/index.ts`) return false;
+  const names = namedImports(edge.edge?.declaration ?? edge.declaration);
+  const listName = entityListName(owner.root.split('/').at(-1));
+  return names !== null && names.every(name => name === listName);
+}

package/runtime/scripts/hfs/architecture/owners.mjs

@@ -4,6 +4,7 @@ import { relativePath, workspaceExportSources } from './typescript.mjs';
 import { sourceLocation } from '../../lib/ts-ast.mjs';
 import { globExpression } from '../../lib/glob.mjs';
 import { posixPath } from '../../lib/path-key.mjs';
+import { registryImporter, registrySlot } from './entity-registry.mjs';
 
 function absolute(root, relative) {
   return canonical(path.resolve(root, ...relative.split('/')));
@@ -68,6 +69,15 @@ function arrangesSchema(config, from, to) {
     && resolver.classifyPath(relativePath(config.root, to)).slot === 'be.persistence';
 }
 
+/**
+ * The entity registry (slot role entity-registry, entity-registry.mjs) is imported by deep path, and only from the files its slot's
+ * `importedBy` names: app composition and the test world. Any other importer goes through the owner's entry, which never exports it.
+ */
+function importsRegistry(config, from, to) {
+  const slot = registrySlot(config.hfs, relativePath(config.root, to));
+  return slot !== null && registryImporter(config.hfs, slot, relativePath(config.root, from));
+}
+
 function publicEntryViolations(config, context, owners, sourceFiles) {
   const violations = [];
   for (const owner of owners) {
@@ -104,6 +114,7 @@ function ownerImportViolations(config, context, owners) {
       const bypass = privateOwnerChain(context, owners, edge);
       if (!bypass) continue;
       if (arrangesSchema(config, from, bypass.chain.at(-1))) continue;
+      if (bypass.chain.length === 2 && importsRegistry(config, from, bypass.chain.at(-1))) continue;
       violations.push({
         ruleId: 'ARCH_OWNER_EXPORT_BYPASS',
         path: relativePath(config.root, from),

package/runtime/scripts/hfs/architecture/tiers.mjs

@@ -1,4 +1,5 @@
 import { byCodeUnit } from '../../lib/list.mjs';
+import { registryListImport, registrySlot } from './entity-registry.mjs';
 
 /**
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
@@ -8,7 +9,9 @@ import { byCodeUnit } from '../../lib/list.mjs';
  *      kind (slot field `trigger`: api, webhooks, realtime, saga, reactors, jobs, cli) importing a feature of another is
  *      BE_KIND_ISOLATION, whose fix is the event bus,
  *      an app never imports another app (BE_SERVICE_ISOLATION / FE_APP_ISOLATION), and a component layer imports only the layers after it;
- *   2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE),
+ *      the entity registry naming a capability's `<c>Entities` from its public entry is the one platform-to-domain edge (entity-registry.mjs);
+ *   2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE), the entity
+ *      registry counted as a unit of its own,
  *      reported with the cycle path and the import that closes each hop.
  * Importing inside one owner is always allowed; the public-entry rule stays with owners.mjs (ARCH_OWNER_EXPORT_BYPASS).
  */
@@ -138,15 +141,23 @@ function inspectTierEdge(graph, edge, tierRule, counts, violations, coverage) {
     return;
   }
   coverage.edgesChecked += 1;
+  if (verdict.reason === 'tierDirection' && registryListImport(graph.resolver, edge)) return;
   reportReasonedTierViolation(graph, edge, verdict, tierRule, counts, violations);
 }
 
+/**
+ * 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
+ * platform/database but is composition-level by role (it imports every capability's `<c>Entities`), so it never closes a cycle
+ * among capabilities through the owner it lives in.
+ */
+const cycleUnit = (graph, resolver, rel) => (registrySlot(resolver, rel) ? `entity-registry:${rel}` : graph.unit(rel));
+
 function ownerAdjacency(graph, resolver) {
   const adjacency = new Map();
   const witness = new Map();
   for (const edge of graph.edges) {
-    const a = graph.unit(edge.from);
-    const b = graph.unit(edge.to);
+    const a = cycleUnit(graph, resolver, edge.from);
+    const b = cycleUnit(graph, resolver, edge.to);
     if (!a || !b || a === b) continue;
     if (resolver.tierOf(edge.from) === 'none' || resolver.tierOf(edge.to) === 'none') continue;
     if (!adjacency.has(a)) adjacency.set(a, new Set());

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -87,7 +87,9 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
 export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
 const strList = (v) => stringList(v);
 
-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', 'rewrittenBy'];
+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', 'rewrittenBy'];
+/** 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). */
+const SLOT_ROLES = ['entity-registry'];
 /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
 const LITE_OVERLAY_KEYS = ['path', 'requires', 'allows', 'forbids', 'minInstances', 'requiredInstances', 'why'];
 /** A runtime slot has no app kind, side composition, layer or managed template; it may name the generator of a generated copy. */
@@ -250,6 +252,8 @@ function slotEntryProblems(slot, at) {
     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`);
   }
   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)`);
+  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`);
+  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`);
   return bad;
 }
 

package/templates/be/skeleton-lite/src/modules/platform/database/entities.ts

@@ -1,6 +1,7 @@
 /**
  * The entity list of the primary connection: each capability's `<c>Entities` array (its `persistence/entities/index.ts`), by
- * name, no glob. Only an app's composition root imports this file, from the deep path `@modules/platform/database/entities`;
- * DatabaseModule and the database barrel never do, since the capability barrels import the database capability back.
+ * name, no glob (the entity registry, slot be.platform.database.entities). Only app composition and the test world import this
+ * file, from the deep path `@modules/platform/database/entities`; DatabaseModule and the database barrel never do, since the
+ * capability barrels import the database capability back.
  */
 export const PRIMARY_ENTITIES: ReadonlyArray<Function> = []