@starci/hfs 5.2.0 → 5.4.0

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.16.0
+version: 3.17.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -58,6 +58,9 @@ versioning:
 # 3.13.0 (rulings lite-pgmq-bus-bullmq-jobs and lite-db-image-in-stacks, 2026-10-29) is a change for lite only: ruleParams.db.extensions
 # admits pgmq, the event bus, ruleParams.db.queueOutbox is retired with the pg_cron half of R258, the lite event-bus functions replace
 # event_bus_write in ruleParams.be.dbFunctions, and app.db.image moves to .starcistacks/images/db/Dockerfile (db/ keeps schema and data).
+# 3.17.0 (ruling auth-oidc-package, 2026-11-03) adds the optional full-edition be.integrations.keycloak, the glue of @starci/auth-oidc (the OIDC client of the
+# identity provider behind the PrincipalVerifier of @starci/auth), and gives @starci/auth-oidc to it in ruleParams.be.infraOwners.
+# 3.17.0 (ruling module-packages, 2026-11-03) adds the optional app.packages and app.module-registry: the workspace packages of the app root (the agent SDK, the module packages, the managed registry).
 # 3.15.0 (ruling app-check-cache, 2026-10-31) adds the optional app.starcistacks.cache, the committed check cache of the app (.starcistacks/cache/, both editions).
 # 3.14.0 (ruling app-secrets-one-standard, 2026-10-29) adds the optional app.ci-stack-key-restore, the managed workflow that writes the
 # deploy server's age identity back from its GitHub Environment backup.
@@ -256,6 +259,8 @@ ruleParams:
       "@aws-sdk/s3-request-presigner": []
       "@starci/object-storage": [integrations/object-storage]   # the ObjectStorage port: one S3 adapter for MinIO, S3 and Spaces (R331)
       minio: []                                          # storage goes through @starci/object-storage
+      nodemailer: []                                     # the SMTP client is a dependency of @starci/mail alone; no app file imports it
+      "@starci/mail": [integrations/mail]                # outgoing mail: the Mailer port, parsed and registered by its one glue
       "@supabase": []                                    # no Supabase client in a back end
       "@nestjs/passport": []                             # the identity libraries are @starci/auth's dependencies, never an app's (R328)
       passport: []
@@ -264,8 +269,15 @@ ruleParams:
       "@nestjs/jwt": []
       jose: []
       bcryptjs: []
+      jsonwebtoken: []                                   # no other JWT or OIDC client library in a back end: the tokens of an identity provider are verified by @starci/auth-oidc (R328)
+      jwks-rsa: []
+      jwt-decode: []
+      passport-jwt: []
+      openid-client: []
       "@starci/auth": [integrations/passport]            # the lite sign-in package: its server entry is reached only through integrations/passport (R328)
       "@starci/auth/testing": [integrations/passport]   # its test doubles, for the glue's specs
+      "@starci/auth-oidc": [integrations/keycloak]       # the full sign-in package (jose is its dependency, imported by no app file): its server entry is reached only through integrations/keycloak (R328)
+      "@starci/auth-oidc/testing": [integrations/keycloak]   # its fake issuer, for the glue's specs
       bcrypt: []
       cache-manager: [integrations/cache, integrations/redis]
       "@nestjs/cache-manager": [integrations/cache, integrations/redis]     # the CACHE_MANAGER token: caching goes through the cache capability
@@ -479,6 +491,14 @@ ruleParams:
       - {name: public.event_bus_bury, reason: "platform/event-bus (add webhook, lite): the move of an exhausted or malformed message to its consumer's dead-letter queue"}
       - {name: public.event_bus_dead_letters, reason: "platform/event-bus (add webhook, lite): the operator read of a consumer's dead-letter queue"}
       - {name: public.event_bus_requeue, reason: "platform/event-bus (add webhook, lite): the operator requeue of one dead letter"}
+      - {name: public.be_auth_user_by_email, reason: "domain/identity (lite sign-in): the account of an exact sign-in address with its bcrypt hash, through the account-doors definer of the baseline"}
+      - {name: public.be_auth_user_by_id, reason: "domain/identity (lite sign-in): the standing of one account by id (a refresh), through the account-doors definer"}
+      - {name: public.be_auth_user_by_google, reason: "domain/identity (lite sign-in): the account a Google subject is linked to, through the account-doors definer"}
+      - {name: public.be_auth_create_user, reason: "domain/identity (lite sign-in): the account a first Google sign-in creates, through the account-doors definer"}
+      - {name: public.be_auth_link_google, reason: "domain/identity (lite sign-in): the link of a Google subject to an account, through the account-doors definer"}
+      - {name: public.be_auth_touch_user, reason: "domain/identity (lite sign-in): the sign-in record of an account and its profile keys, through the account-doors definer"}
+      - {name: public.be_auth_confirm_user, reason: "domain/identity (lite sign-in): the confirmation stamp of a mailbox whose link was spent, through the account-doors definer"}
+      - {name: public.be_auth_set_password, reason: "domain/identity (lite sign-in): the new password hash of a spent reset link (and the mailbox it proved), through the account-doors definer"}
     # R334 (lite): the only `.query(` outside platform/database's composer and the test world is the pass-through of a file listed here
     # (or in hfs.json sides.be.sqlPassThrough), whose SQL text is not the app's own. Paths are relative to the side folder.
     sqlPassThrough:
@@ -606,13 +626,24 @@ slots:
   - id: app.tool-config-local
     since: 3.1.0
     profiles: [app]
-    path: "{tsconfig.json,.eslintrc,.eslintrc.*,.eslintignore,eslint.config.*,.stylelintrc,.stylelintrc.*,.stylelintignore,stylelint.config.*,.prettierrc.*,prettier.config.*,jest.config.*,lint-staged.config.*,.lintstagedrc*}"
+    path: "{tsconfig.json,.eslintrc,.eslintrc.*,.eslintignore,eslint.config.js,eslint.config.cjs,eslint.config.ts,eslint.config.mts,eslint.config.cts,.stylelintrc,.stylelintrc.*,.stylelintignore,stylelint.config.*,.prettierrc.*,prettier.config.*,jest.config.*,lint-staged.config.*,.lintstagedrc*}"
     presence: forbidden
     tracked: external
     tier: none
     tests: none
-    goesTo: "nowhere at the app root: each side holds exactly its managed tool configuration (be.tool-config, fe.tool-config) and the root only the formatter (app.format-config)"
+    goesTo: "nowhere at the app root: each side holds exactly its managed tool configuration (be.tool-config, fe.tool-config) and the root only the formatter (app.format-config) and the eslint config of its root packages (app.packages-lint)"
     rules: [HFS_TOOL_CONFIG_LOCAL]
+  - id: app.packages-lint
+    since: 3.17.0
+    profiles: [app]
+    # The one eslint config at the app root: `starci app sync` renders it when the app has root workspace packages (app.packages), and it lints their
+    # source by subpath (the back-end canon, the front-end canon and the Grammar family each over their own subpaths). No other tool config lives here.
+    path: eslint.config.mjs
+    presence: optional
+    tracked: tracked
+    tier: none
+    tests: none
+    rules: [HFS_MANAGED_FILE_DRIFT]
   - id: app.quality-config
     since: 3.1.0
     profiles: [app]
@@ -857,6 +888,31 @@ slots:
     rules: [HFS_PLAINTEXT_SECRET, HFS_SCRIPT_ONE_OFF, BE_SPEC_PLACEMENT, HFS_REPO_LOCAL_CHECK]
     exemplifiedBy:
       - {path: packages/hfs/src/hfs-slot-ownership.spec.mjs, editions: [lite, full]}
+  - id: app.packages
+    since: 3.17.0
+    profiles: [app]
+    editionWhy: Lite and full share the slot; a product's agent SDK and its agent modules are workspace packages in both.
+    # A workspace package of the app ROOT (packages/agent-sdk, packages/module-<name>): first-party source that both sides import through its
+    # package entry points and never past them (ARCH_INTERNAL_IMPORT_OUTSIDE), linted by the root eslint config by subpath.
+    path: "packages/{agent-sdk,module-<name>}/"
+    presence: optional
+    tracked: tracked
+    tier: none
+    requires: [package.json, tsconfig.json, src/index.ts]
+    tests: unit-beside
+    rules: [HFS_UNUSED_EXPORT]
+  - id: app.module-registry
+    since: 3.17.0
+    profiles: [app]
+    editionWhy: Lite and full share the slot; the registry lists the module packages of the app.
+    path: packages/modules/
+    presence: optional
+    tracked: tracked
+    tier: none
+    requires: [package.json, src/index.ts]
+    allows: [package.json, tsconfig.json, tsconfig.build.json, src/index.ts, src/template/index.ts, src/manifest/index.ts]
+    tests: none
+    rules: [HFS_MANAGED_FILE_DRIFT]
   - id: app.sides
     since: 3.1.0
     profiles: [app]
@@ -2055,8 +2111,8 @@ slots:
     profiles: [be]
     editions: [lite]
     editionWhy: "lite signs people in with the package @starci/auth, so its sign-in glue is rendered, not written (owner ruling auth-package); full uses its identity provider."
-    # The identity capability's sign-in glue over @starci/auth: the entities of the session, attempt and user tables, the stores the package asks for (sessions, accounts, rate counter), the authenticator and the service the doors call, with their specs. `starci app sync` renders them; a hand edit is drift.
-    path: "{src/modules/domain/identity/account-directory.service.spec.ts,src/modules/domain/identity/account-directory.service.ts,src/modules/domain/identity/authenticator.service.spec.ts,src/modules/domain/identity/authenticator.service.ts,src/modules/domain/identity/persistence/entities/auth-identity.entity.ts,src/modules/domain/identity/persistence/entities/auth-user.entity.ts,src/modules/domain/identity/persistence/entities/identity-attempt.entity.ts,src/modules/domain/identity/persistence/entities/identity-refresh-token.entity.ts,src/modules/domain/identity/persistence/entities/identity-session.entity.ts,src/modules/domain/identity/persistence/entities/index.ts,src/modules/domain/identity/rate-counter.service.spec.ts,src/modules/domain/identity/rate-counter.service.ts,src/modules/domain/identity/session-store.service.spec.ts,src/modules/domain/identity/session-store.service.ts,src/modules/domain/identity/sign-in.service.spec.ts,src/modules/domain/identity/sign-in.service.ts,src/tests/fixtures/builders/identity.builder.ts}"
+    # The identity capability's sign-in glue over @starci/auth: the entities of the session, attempt, refresh-token and email-token tables, the account doors over auth.users and auth.identities, the stores the package asks for (sessions, accounts, rate counter), the authenticator and the service the doors call, with their specs. `starci app sync` renders them; a hand edit is drift.
+    path: "{src/modules/domain/identity/account-directory.service.spec.ts,src/modules/domain/identity/account-directory.service.ts,src/modules/domain/identity/authenticator.service.spec.ts,src/modules/domain/identity/authenticator.service.ts,src/modules/domain/identity/identity-email.log-events.ts,src/modules/domain/identity/identity-email.service.spec.ts,src/modules/domain/identity/identity-email.service.ts,src/modules/domain/identity/identity-sign-in.log-events.ts,src/modules/domain/identity/persistence/account-doors.port.ts,src/modules/domain/identity/persistence/entities/identity-attempt.entity.ts,src/modules/domain/identity/persistence/entities/identity-email-token.entity.ts,src/modules/domain/identity/persistence/entities/identity-refresh-token.entity.ts,src/modules/domain/identity/persistence/entities/identity-session.entity.ts,src/modules/domain/identity/persistence/entities/index.ts,src/modules/domain/identity/rate-counter.service.spec.ts,src/modules/domain/identity/rate-counter.service.ts,src/modules/domain/identity/session-store.service.spec.ts,src/modules/domain/identity/session-store.service.ts,src/modules/domain/identity/sign-in.service.spec.ts,src/modules/domain/identity/sign-in.service.ts,src/tests/fixtures/builders/identity.builder.ts}"
     presence: optional
     tracked: tracked
     tier: inherit
@@ -2071,7 +2127,7 @@ slots:
     editions: [lite]
     editionWhy: "lite signs people in with the package @starci/auth, so its sign-in glue is rendered, not written (owner ruling auth-package); full uses its identity provider."
     # The auth feature: the REST doors under /auth (login, refresh, session, logout, Google start and callback, jwks) over IdentitySignInService, one command or query and handler per door.
-    path: "{src/features/api/auth/application/auth.contracts.ts,src/features/api/auth/application/get-jwks.handler.ts,src/features/api/auth/application/get-jwks.query.ts,src/features/api/auth/application/google-begin.command.ts,src/features/api/auth/application/google-begin.handler.ts,src/features/api/auth/application/google-complete.command.ts,src/features/api/auth/application/google-complete.handler.ts,src/features/api/auth/application/login.command.ts,src/features/api/auth/application/login.handler.ts,src/features/api/auth/application/logout.command.ts,src/features/api/auth/application/logout.handler.ts,src/features/api/auth/application/refresh.command.ts,src/features/api/auth/application/refresh.handler.ts,src/features/api/auth/application/session.command.ts,src/features/api/auth/application/session.handler.ts,src/features/api/auth/auth.module-definition.ts,src/features/api/auth/auth.module.ts,src/features/api/auth/auth.options.ts,src/features/api/auth/index.ts,src/features/api/auth/transport/http/auth-http.module-definition.ts,src/features/api/auth/transport/http/auth-http.module.ts,src/features/api/auth/transport/http/auth-http.options.ts,src/features/api/auth/transport/http/auth.controller.ts,src/features/api/auth/transport/http/dto/google-start.request.ts,src/features/api/auth/transport/http/dto/login.request.ts}"
+    path: "{src/features/api/auth/application/auth.contracts.ts,src/features/api/auth/application/confirm.command.ts,src/features/api/auth/application/confirm.handler.ts,src/features/api/auth/application/forgot.command.ts,src/features/api/auth/application/forgot.handler.ts,src/features/api/auth/application/get-jwks.handler.ts,src/features/api/auth/application/get-jwks.query.ts,src/features/api/auth/application/google-begin.command.ts,src/features/api/auth/application/google-begin.handler.ts,src/features/api/auth/application/google-complete.command.ts,src/features/api/auth/application/google-complete.handler.ts,src/features/api/auth/application/login.command.ts,src/features/api/auth/application/login.handler.ts,src/features/api/auth/application/logout.command.ts,src/features/api/auth/application/logout.handler.ts,src/features/api/auth/application/refresh.command.ts,src/features/api/auth/application/refresh.handler.ts,src/features/api/auth/application/resend.command.ts,src/features/api/auth/application/resend.handler.ts,src/features/api/auth/application/reset.command.ts,src/features/api/auth/application/reset.handler.ts,src/features/api/auth/application/session.command.ts,src/features/api/auth/application/session.handler.ts,src/features/api/auth/application/signup.command.ts,src/features/api/auth/application/signup.handler.ts,src/features/api/auth/auth.module-definition.ts,src/features/api/auth/auth.module.ts,src/features/api/auth/auth.options.ts,src/features/api/auth/index.ts,src/features/api/auth/transport/http/auth-http.module-definition.ts,src/features/api/auth/transport/http/auth-http.module.ts,src/features/api/auth/transport/http/auth-http.options.ts,src/features/api/auth/transport/http/auth.controller.ts,src/features/api/auth/transport/http/dto/forgot.request.ts,src/features/api/auth/transport/http/dto/google-start.request.ts,src/features/api/auth/transport/http/dto/login.request.ts,src/features/api/auth/transport/http/dto/resend.request.ts,src/features/api/auth/transport/http/dto/reset.request.ts,src/features/api/auth/transport/http/dto/signup.request.ts,src/features/api/auth/transport/http/dto/token.request.ts}"
     presence: optional
     tracked: tracked
     tier: inherit
@@ -2080,6 +2136,25 @@ slots:
     managedBy: auth-lite
     managedOnly: true     # lists files sync renders; the slot owning the path judges them
     rules: [HFS_MANAGED_FILE_DRIFT]
+  - id: be.integrations.mail
+    profiles: [be]
+    editions: [lite]
+    exemplifiedBy:
+      - packages/hfs/templates/be/skeleton-lite/src/modules/integrations/mail/
+    # The glue of @starci/mail, the owner of the SMTP client (nodemailer): this folder parses the settings (the server, the sender and the
+    # link lifetimes of the confirmation and reset mails), registers the module and names the injectors; no app file imports nodemailer,
+    # and no other module imports the package. The words and layout of each mail belong to the domain that sends it.
+    path: "src/modules/integrations/mail/"
+    presence: required
+    tracked: tracked
+    tier: integrations
+    owner: true
+    requires: [index.ts, mail.config.ts, mail.options.ts, mail.decorators.ts, mail.module-definition.ts, mail.module.ts]
+    allows: [index.ts, mail.config.ts, mail.options.ts, mail.decorators.ts, mail.module-definition.ts, mail.module.ts, errors/]
+    tests: unit-beside
+    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER]
+    coverage: required
+    since: 5.3.0
   - id: be.integrations.object-storage
     profiles: [be]
     exemplifiedBy:
@@ -2099,6 +2174,24 @@ slots:
     rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_STORAGE_OWNER]
     coverage: required
     since: 3.9.0
+  - id: be.integrations.keycloak
+    profiles: [be]
+    editions: [full]
+    # The glue of @starci/auth-oidc, the OIDC client of the full edition's identity provider (Keycloak): discovery, the provider's JWKS,
+    # algorithm-pinned token checks and the authorization code flow with PKCE and nonce behind the PrincipalVerifier of @starci/auth.
+    # This folder parses the typed options, hands the package the app's bounded HTTP client and clock, and names the injectors;
+    # no app file imports jose, and no other module imports the package (ruleParams.be.infraOwners).
+    path: "src/modules/integrations/keycloak/"
+    presence: optional
+    tracked: tracked
+    tier: integrations
+    owner: true
+    requires: [index.ts, keycloak.config.ts, keycloak.options.ts, keycloak.decorators.ts, keycloak.registration.ts]
+    allows: [index.ts, keycloak.config.ts, keycloak.options.ts, keycloak.decorators.ts, keycloak.registration.ts, errors/, messages/]
+    tests: unit-beside
+    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_AUTH_PASSPORT_OWNER, BE_INTEGRATION_SPEC_MISSING]
+    coverage: required
+    since: 3.17.0
 
   # ----- BE: tests (owner test layout 2026-09-30). Unit specs are <name>.service.spec.ts beside their service and nothing else; everything else
   # lives under src/tests/, one folder per kind, and the folder and the file suffix always agree (a file whose suffix does
@@ -2572,9 +2665,9 @@ slots:
     presence: required
     tracked: tracked
     tier: foundation
-    # The app's routing, request config and catalogs, or its adapter to the shared i18n factory. A single app
-    # owns createNavigation in fe.modules.routes, keeping this public entry safe for its proxy. Shared stacks
-    # belong to fe.package.i18n and expose a routing-only proxy entry separately from navigation.
+    # The app's description of its languages (defineI18n of @starci/next-i18n), its request config and catalogs, or its adapter to the
+    # shared i18n workspace package. A single app builds its navigation (createI18nNavigation) in fe.modules.routes, keeping this
+    # public entry safe for its proxy. A description shared by several apps belongs to fe.package.i18n.
     requires: [index.ts]
     tests: none
     rules: [FE_I18N_PLACEMENT, FE_I18N_CATALOG]
@@ -2643,8 +2736,8 @@ slots:
     profiles: [fe]
     editions: [lite]
     editionWhy: "lite signs people in with the package @starci/auth, so its auth client is rendered, not written (owner ruling auth-package); full wires its identity provider."
-    # The AuthClient every edition shares, implemented by one @starci/auth/client instance over the app's own back-end auth doors.
-    path: "apps/web/src/modules/auth/client.ts"
+    # The AuthClient every edition shares, implemented by one @starci/auth/client instance over the app's own back-end auth doors.  email-doors.ts is the lite-only call of the five email doors (sign up, resend, confirm, forgot, reset), kept off the shared AuthClient interface because the full edition identity provider owns its own recovery flows; index.ts is the module entry that exports both.
+    path: "apps/web/src/modules/auth/{client.ts,email-doors.ts,index.ts}"
     presence: optional
     tracked: tracked
     tier: inherit
@@ -2726,7 +2819,7 @@ slots:
     owner: true
     requires: [package.json, src/index.ts, tsconfig.json]
     tests: none
-    why: the next-intl stack (routing, navigation, request config) written once, exported as the createAppI18n factory every app calls
+    why: the product's languages (defineI18n of @starci/next-i18n) written once and composed into the createAppI18n factory every app calls; the next-intl stack itself is the package's
     rules: [FE_I18N_PLACEMENT, FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT]
 
 # Checks that read this manifest (all ship from .claude; none keeps its own path list)

package/runtime/modules/kernel/failure-codes.yaml

@@ -980,7 +980,7 @@ BE_MODULE_DEFINITION_MISSING:
     - "Có <x>.module.ts nhưng thiếu <x>.module-definition.ts hoặc <x>.options.ts bên cạnh"
     - "Lớp module không kế thừa ConfigurableModuleClass lấy từ ./<x>.module-definition"
     - "Module sản phẩm nằm trong mảng imports (hoặc nhóm compose của app) như một tên lớp trần thay vì XModule.register({...})"
-  nextStep_vi: "Tạo <x>.module-definition.ts (new ConfigurableModuleBuilder<XOptions>().setClassMethodName(\"register\").build()) và <x>.options.ts (export type XOptions = Record<string, never> nếu chưa có tùy chọn), cho lớp kế thừa ConfigurableModuleClass, và đăng ký bằng XModule.register({}); op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra."
+  nextStep_vi: "Tạo <x>.module-definition.ts (export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = defineConfigurableModule<XOptions>() từ @starci/nest-kit; capability dùng defineCapabilityModule) và <x>.options.ts (export type XOptions = Record<string, never> nếu chưa có tùy chọn), cho lớp kế thừa ConfigurableModuleClass, và đăng ký bằng XModule.register({}); op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra."
   owner: op-retry
   kind: check-finding
 
@@ -1013,7 +1013,7 @@ BE_MODULE_SHAPE:
     - "@Global() trên bất kỳ module nào (kể cả trong spec)"
     - "isGlobal: true ở ngoài app.module.ts của app"
     - "Module của một capability khác bị import vào imports thay vì dùng qua Inject<Thing>()"
-    - "new ConfigurableModuleBuilder() không có kiểu options"
+    - "defineConfigurableModule() hay new ConfigurableModuleBuilder() không có kiểu options"
     - "register không static, hoặc có forRoot, forFeature, registerAsync"
     - "new XService() hoặc let ở cấp module tạo trạng thái toàn cục"
     - "Feature có hai module trong một thư mục transport (một module cho mỗi thao tác), module-definition không nằm cạnh module của nó, hoặc @Module ngoài `<f>.module.ts` và `<f>-<protocol>.module.ts`; app import module ứng dụng của feature hoặc module transport không thuộc loại app cho phép (api: graphql/http/websocket; worker: schedule/message; cli: cli)"
@@ -1797,11 +1797,12 @@ CLI_ONLY_ENTRY:
 DB_APP_ROLE:
   title: "The back-end database role has explicit least privileges"
   title_vi: "Role cơ sở dữ liệu của back end có quyền quá rộng"
-  meaning_vi: "Migration tại <path> tạo hoặc sửa role của ứng dụng với superuser, bypassrls hay thuộc tính thiếu an toàn, hoặc cấp all thay cho các quyền cần thiết; role mặc định là app_be và có thể khai báo bằng supabase.appRole."
+  meaning_vi: "Migration tại <path> tạo hoặc sửa role của ứng dụng với superuser, bypassrls hay thuộc tính thiếu an toàn, hoặc cấp all thay cho các quyền cần thiết, hoặc cấp cho role quyền trên schema auth (schema, bảng hay sequence trong đó, hay default privileges của nó) mà không có migration sau đó thu hồi; role mặc định là app_be và có thể khai báo bằng supabase.appRole."
   causes_vi:
     - "Vi phạm R255: app role vượt qua RLS hoặc được cấp quyền rộng hơn công việc của back end."
     - "Role không khai báo rõ noinherit và nobypassrls, hoặc nhận grant all trên schema hay bảng."
-  nextStep_vi: "Khai báo app role với noinherit, nobypassrls và các thuộc tính không đặc quyền; bỏ superuser, bypassrls và grant all, rồi cấp từng quyền cần thiết."
+    - "Role nhận grant trên schema auth: tài khoản chỉ được truy cập qua các hàm SECURITY DEFINER be_auth_* (account doors) của baseline."
+  nextStep_vi: "Khai báo app role với noinherit, nobypassrls và các thuộc tính không đặc quyền; bỏ superuser, bypassrls và grant all, rồi cấp từng quyền cần thiết. Với grant trên schema auth: chạy `starci app codemod account-doors --execute`, `starci app sync --execute`, rồi `starci app codemod account-doors --contract --execute`."
   owner: op-retry
   kind: check-finding
 

package/runtime/scripts/hfs/architecture/config.d.mts

@@ -1,6 +1,7 @@
 import { slash } from '../../lib/path-key.mjs';
 import { isInside } from '../../lib/walk.mjs';
 import { openHfs } from '../slots.mjs';
+import type { RootPackage } from './root-packages.mjs';
 /** The compiler API the checkers receive as their `ts` argument (the target repository's own installed TypeScript). */
 export type TypeScriptApi = typeof import('typescript');
 /** One owner derived from the slot manifest: an owner directory with its entry file. */
@@ -28,6 +29,8 @@ export interface ArchitectureConfig {
     kinds: string[];
     projects: string[];
     workspaces: string[];
+    /** The app's own root workspace packages (empty at the app root itself, whose workspaces already hold them). */
+    rootPackages?: RootPackage[];
     apps: {
         name: string;
         kind: string;
@@ -72,3 +75,4 @@ export declare function loadArchitectureConfig(repositoryRoot: string, { hfs }?:
     hfs?: ArchitectureConfig['hfs'] | undefined;
 }): ArchitectureConfig;
 export { canonical, exactKeys, isInside, slash };
+export type { RootPackage };

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

@@ -3,7 +3,8 @@ import path from 'node:path';
 import { slash } from '../../lib/path-key.mjs';
 import { readJsonFile as readJson } from '../../lib/json.mjs';
 import { isInside } from '../../lib/walk.mjs';
-import { openHfs } from '../slots.mjs';
+import { createSlotResolver, openHfs, readRepoDeclaration } from '../slots.mjs';
+import { ROOT_PACKAGE_SLOTS, rootPackageRecord, rootWorkspaceDirectories } from './root-packages.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { grammarContractFor } from '../../lib/grammar-lint.mjs';
 /** A file's identity: its resolved real path, or the resolved path when it does not exist. */
@@ -182,6 +183,28 @@ function workspaceDirectories(root, { packageRoot: appPackageRoot = root, side =
     }
     return [...directories].sort(byCodeUnit);
 }
+/**
+ * The workspace packages of the app root that no side owns: the `workspaces` patterns of the app's one package.json that do not start
+ * with a side folder (`packages/*`), and the directories the slots `app.packages` and `app.module-registry` place under `packages/`
+ * even when the manifest forgot to list them. A side imports them as first-party packages (through their entry points), never as
+ * "outside the side". A side of the app is judged here; the app root itself already counts them among its workspaces.
+ */
+function rootPackageRecords(root, packageRoot, side, opened) {
+    if (side === null)
+        return [];
+    const candidates = new Set(rootWorkspaceDirectories(packageRoot));
+    if (opened.manifest && existingDirectory(packageRoot, 'packages')) {
+        const resolver = createSlotResolver(opened.manifest, readRepoDeclaration(opened.manifest, packageRoot));
+        const container = path.join(packageRoot, 'packages');
+        for (const entry of fs.readdirSync(container, { withFileTypes: true }).filter(item => item.isDirectory())) {
+            const slot = resolver.classifyPath(`packages/${entry.name}`).slot;
+            if (slot !== undefined && ROOT_PACKAGE_SLOTS.has(slot))
+                candidates.add(path.join(container, entry.name));
+        }
+    }
+    return [...candidates].sort(byCodeUnit).filter(candidate => !isInside(root, candidate))
+        .flatMap(candidate => rootPackageRecord(packageRoot, candidate, canonical) ?? []);
+}
 function discoveredProjects(root, workspaces) {
     const projects = [];
     if (fs.existsSync(path.join(root, 'tsconfig.json')))
@@ -373,6 +396,7 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
         kinds,
         projects,
         workspaces,
+        rootPackages: rootPackageRecords(root, packageRoot, side, opened),
         apps: apps.map(app => ({ name: app.name, kind: app.kind })),
         hfs: opened,
         owners: derivedOwners(root, opened),

package/runtime/scripts/hfs/architecture/module-per-transport.d.mts

@@ -9,7 +9,7 @@ import type { MachineContext } from './machine-ast.mjs';
  *
  *   - a `*.module.ts` file below a transport folder other than `<f>-<protocol>.module.ts`, a `*.module-definition.ts` that is
  *     not the sibling of the application module or of the transport module of its own folder, and an `@Module` class (or a
- *     `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a feature file that is neither the application module, the
+ *     `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use or a `defineConfigurableModule`/`defineCapabilityModule` call of `@starci/nest-kit`) in a feature file that is neither the application module, the
  *     transport module of its own folder nor that module's definition are refused;
  *   - apps import only transport modules, of the kinds their app kind allows: the `composedBy` list of each transport slot
  *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root (app.module.ts

package/runtime/scripts/hfs/architecture/module-per-transport.mjs

@@ -11,7 +11,7 @@ import { trimTrailingSlashes } from '../trailing-slashes.mjs';
  *
  *   - a `*.module.ts` file below a transport folder other than `<f>-<protocol>.module.ts`, a `*.module-definition.ts` that is
  *     not the sibling of the application module or of the transport module of its own folder, and an `@Module` class (or a
- *     `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use) in a feature file that is neither the application module, the
+ *     `ConfigurableModuleBuilder`/`ConfigurableModuleClass` use or a `defineConfigurableModule`/`defineCapabilityModule` call of `@starci/nest-kit`) in a feature file that is neither the application module, the
  *     transport module of its own folder nor that module's definition are refused;
  *   - apps import only transport modules, of the kinds their app kind allows: the `composedBy` list of each transport slot
  *     in knowledge/hfs/slots.yaml (api: graphql, http, websocket; worker: schedule, message). An app root (app.module.ts
@@ -99,6 +99,8 @@ function reportModuleClassLocation(file, name, place, composedModuleOf, report)
     if (file.rel !== own)
         report(file, name, `${name.text} is a Nest module declared in ${file.rel}; a feature declares exactly its application module (${place.feature}.module.ts) and one module per transport folder (${place.feature}-<protocol>.module.ts), never a module per operation.`, { feature: place.feature });
 }
+/** The module-definition helpers of @starci/nest-kit: each builds the definition of one module, like `ConfigurableModuleBuilder`. */
+const DEFINITION_HELPERS = ['defineConfigurableModule', 'defineCapabilityModule'];
 function reportConfigurableModuleUses(file, checker, kit, ts, place, env) {
     const own = ownModuleOf(place, file.rel, env.composedModuleOf);
     const isDefinition = file.rel === definitionOf(own);
@@ -106,6 +108,9 @@ function reportConfigurableModuleUses(file, checker, kit, ts, place, env) {
         if (ts.isNewExpression(node) && kit.isImportOf(checker, node.expression, 'ConfigurableModuleBuilder', '@nestjs/common') && !isDefinition) {
             env.report(file, node, `ConfigurableModuleBuilder builds the module definition of one module; in feature ${place.feature} it is written only in ${path.posix.basename(definitionOf(own))}, beside ${path.posix.basename(own)}.`, { feature: place.feature });
         }
+        else if (ts.isCallExpression(node) && !isDefinition && DEFINITION_HELPERS.some(name => kit.isImportOf(checker, node.expression, name, '@starci/nest-kit'))) {
+            env.report(file, node, `${node.expression.getText(file.sourceFile)} builds the module definition of one module; in feature ${place.feature} it is written only in ${path.posix.basename(definitionOf(own))}, beside ${path.posix.basename(own)}.`, { feature: place.feature });
+        }
         else if (ts.isHeritageClause(node) && file.rel !== own) {
             for (const type of node.types)
                 if (kit.isImportOf(checker, type.expression, 'ConfigurableModuleClass', '@nestjs/common')) {

package/runtime/scripts/hfs/architecture/root-packages.d.mts

@@ -0,0 +1,26 @@
+/**
+ * A workspace package of the app root: a first-party package that both sides import through its package entry points and never past
+ * them. `root` is the real path of its folder, `relative` the folder from the app root, `exports` the `exports` of its manifest.
+ */
+export interface RootPackage {
+    root: string;
+    relative: string;
+    name: string;
+    exports: unknown;
+    manifest: Record<string, unknown>;
+    workspace: true;
+    app: false;
+}
+/** The slots whose directories at the app root are first-party packages of the app (agent SDK, module packages, the managed registry). */
+export declare const ROOT_PACKAGE_SLOTS: ReadonlySet<string>;
+/** A package folder with a regular package.json (a link is not one). */
+export declare function packageDirectory(absolute: string): boolean;
+/** The folders the `workspaces` of the app root's package.json name that no side owns, as absolute paths in code-unit order. */
+export declare function rootWorkspaceDirectories(packageRoot: string): string[];
+/**
+ * The record of one package folder of the app root, or null when it is no named package inside the app root.
+ * `canonical` is the file-identity function of the caller (the real path), so a record agrees with the files the graph reads.
+ */
+export declare function rootPackageRecord(packageRoot: string, directory: string, canonical: (file: string) => string): RootPackage | null;
+/** The names of the workspace packages of the app root: what the back-end canon must not read as third-party libraries. */
+export declare function rootPackageNames(packageRoot: string): Set<string>;

package/runtime/scripts/hfs/architecture/root-packages.mjs

@@ -0,0 +1,78 @@
+// root-packages.mjs - the workspace packages of an app ROOT (packages/agent-sdk, packages/module-<name>, the managed packages/modules).
+// They lie outside both side folders and belong to no side; both sides import them by package name, through their package entry points
+// (the `exports` of the manifest), so the import graph reads them as first-party packages and the back-end canon never reads them as
+// a third-party library. The app root's one package.json lists them in `workspaces`; the patterns that start with a side folder
+// (`fe/apps/*`) are that side's own workspaces and are not read here.
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonFile as readJson } from '../../lib/json.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+import { isInside } from '../../lib/walk.mjs';
+import { slash } from '../../lib/path-key.mjs';
+/** The slots whose directories at the app root are first-party packages of the app (agent SDK, module packages, the managed registry). */
+export const ROOT_PACKAGE_SLOTS = new Set(['app.packages', 'app.module-registry']);
+const SIDE_PREFIX = /^(?:be|fe)\//;
+/** A workspace pattern this reader expands (a literal path, or `*` as a whole segment); the others are judged by the workspace rules. */
+const expandablePattern = (written) => !path.isAbsolute(written) && written.split('/').every(segment => segment !== '..' && (!segment.includes('*') || segment === '*'));
+function expandSegment(base, segment) {
+    if (segment !== '*')
+        return [path.join(base, segment)];
+    if (!fs.existsSync(base) || !fs.lstatSync(base).isDirectory())
+        return [];
+    return fs.readdirSync(base, { withFileTypes: true }).filter(item => item.isDirectory()).sort((a, b) => byCodeUnit(a.name, b.name)).map(item => path.join(base, item.name));
+}
+/** A package folder with a regular package.json (a link is not one). */
+export function packageDirectory(absolute) {
+    try {
+        if (!fs.lstatSync(absolute).isDirectory())
+            return false;
+        const manifest = fs.lstatSync(path.join(absolute, 'package.json'));
+        return manifest.isFile() && !manifest.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** The folders the `workspaces` of the app root's package.json name that no side owns, as absolute paths in code-unit order. */
+export function rootWorkspaceDirectories(packageRoot) {
+    const manifest = readJson(path.join(packageRoot, 'package.json'));
+    const declared = manifest?.workspaces;
+    const patterns = Array.isArray(declared) ? declared : declared?.packages;
+    const found = new Set();
+    for (const pattern of Array.isArray(patterns) ? patterns : []) {
+        if (typeof pattern !== 'string' || !pattern.trim())
+            continue;
+        const written = slash(pattern.trim()).replace(/^\.\//, '');
+        if (SIDE_PREFIX.test(written) || !expandablePattern(written))
+            continue;
+        let bases = [packageRoot];
+        for (const segment of written.split('/'))
+            bases = bases.flatMap(base => expandSegment(base, segment));
+        for (const base of bases)
+            found.add(path.resolve(base));
+    }
+    return [...found].sort(byCodeUnit);
+}
+/**
+ * The record of one package folder of the app root, or null when it is no named package inside the app root.
+ * `canonical` is the file-identity function of the caller (the real path), so a record agrees with the files the graph reads.
+ */
+export function rootPackageRecord(packageRoot, directory, canonical) {
+    if (!packageDirectory(directory) || !isInside(packageRoot, directory))
+        return null;
+    const manifest = readJson(path.join(directory, 'package.json'));
+    const name = manifest?.['name'];
+    if (manifest === null || typeof name !== 'string' || !name)
+        return null;
+    return { root: canonical(directory), relative: slash(path.relative(packageRoot, directory)), name, exports: manifest['exports'], manifest, workspace: true, app: false };
+}
+/** The names of the workspace packages of the app root: what the back-end canon must not read as third-party libraries. */
+export function rootPackageNames(packageRoot) {
+    const names = new Set();
+    for (const directory of rootWorkspaceDirectories(packageRoot)) {
+        const record = rootPackageRecord(packageRoot, directory, (file) => file);
+        if (record !== null)
+            names.add(record.name);
+    }
+    return names;
+}

package/runtime/scripts/hfs/architecture/type-context.d.mts

@@ -1,5 +1,5 @@
 import type { CompilerOptions, CreateProgramOptions, Diagnostic, ModuleResolutionCache, ModuleResolutionHost, Node, Program, ProjectReference, SourceFile, TypeChecker } from 'typescript';
-import type { ArchitectureConfig, TypeScriptApi } from './config.mjs';
+import type { ArchitectureConfig, RootPackage, TypeScriptApi } from './config.mjs';
 import type { ProjectRead } from '../typescript-programs.mjs';
 import type { ArchitectureError, ImportEdge, LoadedTypeScript, ModuleReferences, WorkspaceRecord } from './typescript.mjs';
 /** One parsed tsconfig with its compiler program. */
@@ -56,5 +56,8 @@ export interface TypeContextHelpers {
     relativePath(root: string, fileName: string): string;
     packageExported(ts: TypeScriptApi, workspace: WorkspaceRecord, specifier: string, actualTarget: string): boolean;
     boundaryViolation(root: string, edge: ImportEdge, fromWorkspace: WorkspaceRecord | null, toWorkspace: WorkspaceRecord | null, ruleId: string, message: string): ArchitectureError;
+    rootPackageOf(config: Pick<ArchitectureConfig, 'rootPackages'>, specifier: string): RootPackage | null;
+    rootPackageEntryDeclared(item: RootPackage, specifier: string): boolean;
+    rootPackageEntries(item: RootPackage): string[];
 }
 export declare function contextFromProjects(config: ArchitectureConfig, loaded: LoadedTypeScript, paths: string[], helpers: TypeContextHelpers): TypeContext;

package/runtime/scripts/hfs/architecture/type-context.mjs

@@ -241,8 +241,38 @@ function appendEdge(from, sourceFile, project, owningWorkspace, reference, actua
             errors.push(helpers.boundaryViolation(config.root, edge, owningWorkspace, targetWorkspace, 'ARCH_PACKAGE_EXPORT_BYPASS', 'Cross-package imports must use the target package name and a declared package export.'));
     }
 }
+/**
+ * An import of one of the app's root workspace packages (`@scope/agent-sdk`, `@scope/agent-sdk/workbench`). The package lies outside the side
+ * folder, yet it is first-party source both sides may import: through its package entry points (the `exports` of its manifest) and never past
+ * them. An entry point is no import that leaves the side and adds no edge (the package is not part of this side's graph; the package's own
+ * lint judges its files); a path into the package's source is refused. Returns true when the reference was settled here.
+ */
+function rootPackageReference(sourceFile, project, reference, state) {
+    const { config, errors, helpers, host, ts } = state;
+    if (!config.rootPackages?.length)
+        return false;
+    const item = helpers.rootPackageOf(config, reference.specifier);
+    if (item === null)
+        return false;
+    if (!helpers.rootPackageEntryDeclared(item, reference.specifier)) {
+        errors.push({
+            ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
+            project: project.relative,
+            path: helpers.relativePath(config.root, sourceFile.fileName),
+            ...helpers.sourceLocation(sourceFile, reference.node),
+            specifier: reference.specifier,
+            message: `Internal import ${reference.specifier} reaches into the package ${item.name} past its package entry points; import ${helpers.rootPackageEntries(item).join(', ')} instead.`,
+        });
+        return true;
+    }
+    // An entry point that a path alias sends outside the package is no entry point: the ordinary boundary judges it.
+    const resolved = helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host, resolutionCache(state, project));
+    return resolved === undefined || helpers.isInside(item.root, helpers.canonical(resolved));
+}
 function processReference(from, sourceFile, project, owningWorkspace, reference, state) {
     const { config, ts, workspaceNames, workspaces, host, errors, helpers } = state;
+    if (rootPackageReference(sourceFile, project, reference, state))
+        return;
     // A workspace package is read at its source, never at its build: the same import resolves whether or not dist exists.
     const workspaceTarget = workspaces.filter(item => item.root !== helpers.canonical(config.root)).map(item => helpers.workspaceSourceEntry(ts, item, reference.specifier)).find(Boolean);
     const resolvedName = workspaceTarget ?? helpers.resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host, resolutionCache(state, project));

package/runtime/scripts/hfs/architecture/typescript.d.mts

@@ -1,6 +1,6 @@
 import type { TypeContext } from './type-context.mjs';
 import type { Node, SourceFile, TypeChecker } from 'typescript';
-import type { ArchitectureConfig, TypeScriptApi } from './config.mjs';
+import type { ArchitectureConfig, RootPackage, TypeScriptApi } from './config.mjs';
 export { unwrapExpression } from '../../lib/ts-analysis.mjs';
 /** The target repository's loaded TypeScript: the API, where it resolved from and its version. */
 export interface LoadedTypeScript {
@@ -82,6 +82,12 @@ export declare function exportTargetStrings(value: unknown): string[];
 export declare function workspaceSourceEntry(ts: TypeScriptApi, workspace: WorkspaceRecord, specifier: string): string | null;
 /** Every source file the package.json `exports` of a workspace package maps (each non-wildcard subpath, dist back to source): its public entries. */
 export declare function workspaceExportSources(ts: TypeScriptApi, workspace: WorkspaceRecord): string[];
+/** The root workspace package of the app (`packages/agent-sdk`) a specifier names, its name or a subpath of it; the longest name when several match. */
+export declare function rootPackageOf(config: Pick<ArchitectureConfig, 'rootPackages'>, specifier: string): RootPackage | null;
+/** Whether a specifier into a root package names one of its entry points: a subpath its `exports` declare, or its root through `exports`, `main`/`types` or `src/index`. A path into its source is not an entry point. */
+export declare function rootPackageEntryDeclared(item: RootPackage, specifier: string): boolean;
+/** The subpaths a root package declares for import (`.` first), for the message of a refused deep import. */
+export declare function rootPackageEntries(item: RootPackage): string[];
 /** Parse configured tsconfigs, then build only selected programs and their project-reference closure. */
 export declare function buildTypeScriptContext(config: ArchitectureConfig, injectedTypeScript?: TypeScriptApi | null, paths?: string[]): TypeContext;
 export declare function relativePath(root: string, fileName: string): string;

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

@@ -385,6 +385,26 @@ function packageExported(ts, workspace, specifier, actualTarget) {
         return expected === canonical(actualTarget) || sourceOfTarget(ts, workspace, target) === canonical(actualTarget);
     });
 }
+/** The root workspace package of the app (`packages/agent-sdk`) a specifier names, its name or a subpath of it; the longest name when several match. */
+export function rootPackageOf(config, specifier) {
+    let found = null;
+    for (const item of config.rootPackages ?? [])
+        if (sameOrUnder(specifier, item.name) && (found === null || item.name.length > found.name.length))
+            found = item;
+    return found;
+}
+/** Whether a specifier into a root package names one of its entry points: a subpath its `exports` declare, or its root through `exports`, `main`/`types` or `src/index`. A path into its source is not an entry point. */
+export function rootPackageEntryDeclared(item, specifier) {
+    if (exportCandidates(item, specifier).length > 0)
+        return true;
+    return specifier === item.name && !item.exports && (manifestEntryTargets(item.manifest).length > 0 || packageIndexSource(item) !== null);
+}
+/** The subpaths a root package declares for import (`.` first), for the message of a refused deep import. */
+export function rootPackageEntries(item) {
+    const declaration = item.exports;
+    const keys = declaration && typeof declaration === 'object' && !Array.isArray(declaration) ? Object.keys(declaration).filter(key => key.startsWith('.')) : ['.'];
+    return (keys.length ? keys : ['.']).map(key => (key === '.' ? item.name : `${item.name}${key.slice(1)}`));
+}
 function boundaryViolation(root, edge, fromWorkspace, toWorkspace, ruleId, message) {
     return {
         ruleId,
@@ -413,7 +433,7 @@ function typeScriptContext(config, loaded, paths) {
         canonical, compilerError, isInside, slash, readTypeScriptProject, typeScriptProjectReferencePath,
         sameOrUnder, createTypeScriptProgram, isProductionSource, sourceLocation, workspaceMetadata, workspaceOf,
         pathAliasMatches, moduleReferences, workspaceSourceEntry, resolveTypeScriptModule, crossesSide, assetExtension: ASSET_EXTENSION,
-        relativePath, packageExported, boundaryViolation,
+        relativePath, packageExported, boundaryViolation, rootPackageOf, rootPackageEntryDeclared, rootPackageEntries,
     });
 }
 export function relativePath(root, fileName) {

package/runtime/scripts/hfs/explicit-surface-rule.mjs

@@ -6,7 +6,7 @@ const HINTS = {
     'parameter type': 'Give the parameter a type: `(value: Input)`.',
     'property type': 'Give the property a type: `name: Result = ...`.',
     'accessor type': 'Give the accessor a type: `get name(): Result` (a setter takes it from its parameter).',
-    'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name`.',
+    'destructured export': 'A destructuring pattern cannot carry a type per name: export each name as its own variable with a type, `export const name: Type = source.name`; a module definition is `export const { ConfigurableModuleClass, OPTIONS_TYPE } = defineCapabilityModule<XOptions>()` (or `defineConfigurableModule`) of @starci/nest-kit, which states the types (`starci app codemod module-definition` writes it).',
     'exported value': 'Declare the type (an interface or a type alias) and annotate the export with it: `export const name: Shape = ...`.',
 };
 /** The `--isolatedDeclarations` flag name TypeScript ends its reasons with says nothing to the reader. */