@starci/eslint-canon-be 3.18.4 → 3.19.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.
Files changed (211) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +1 -1
  3. package/dist/comments.js +1 -1
  4. package/dist/explicit-surface.js +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/jwt-alg.js +1 -1
  7. package/dist/lib/edition.d.ts +1 -1
  8. package/dist/lib/edition.js +1 -1
  9. package/dist/lib/hfs-view.d.ts +5 -0
  10. package/dist/lib/hfs.d.ts +0 -6
  11. package/dist/lib/hfs.js +7 -5
  12. package/dist/lib/runtime-root.d.ts +6 -1
  13. package/dist/lib/runtime-root.js +8 -2
  14. package/dist/lib/subject-values.js +1 -1
  15. package/dist/module-layering.js +2 -2
  16. package/dist/project-graph.js +1 -1
  17. package/dist/schema-authority.js +66 -2
  18. package/dist/third-party-owner.js +1 -1
  19. package/package.json +3 -1
  20. package/runtime/bundle.json +1 -190
  21. package/runtime/scripts/api/git/recorded-lines.mjs +5 -5
  22. package/runtime/scripts/hfs/project-graph.mjs +6 -6
  23. package/runtime/scripts/hfs/project-rule.mjs +3 -3
  24. package/runtime/config.example.yaml +0 -194
  25. package/runtime/engine/by-code-unit.mjs +0 -12
  26. package/runtime/engine/config.mjs +0 -461
  27. package/runtime/engine/invalid-config.mjs +0 -15
  28. package/runtime/engine/model-config.mjs +0 -112
  29. package/runtime/engine/orca-config.mjs +0 -34
  30. package/runtime/engine/plain-object.mjs +0 -5
  31. package/runtime/engine/release-config.mjs +0 -32
  32. package/runtime/engine/removed-vocabulary.mjs +0 -27
  33. package/runtime/engine/resources-config.mjs +0 -59
  34. package/runtime/engine/runtime-root.mjs +0 -138
  35. package/runtime/engine/secrets.mjs +0 -202
  36. package/runtime/engine/sonar-config.mjs +0 -24
  37. package/runtime/engine/temp-root.mjs +0 -26
  38. package/runtime/engine/yaml.mjs +0 -161
  39. package/runtime/knowledge/grammars/index.yaml +0 -114
  40. package/runtime/knowledge/hfs/canon-pins.yaml +0 -720
  41. package/runtime/knowledge/hfs/fe-stack.yaml +0 -272
  42. package/runtime/knowledge/hfs/rules.yaml +0 -6760
  43. package/runtime/knowledge/hfs/slots.yaml +0 -2783
  44. package/runtime/knowledge/patterns/fe/folder.yaml +0 -425
  45. package/runtime/knowledge/sonar-gate.yaml +0 -151
  46. package/runtime/modules/kernel/removed-vocabulary.yaml +0 -458
  47. package/runtime/modules/models/registry.yaml +0 -221
  48. package/runtime/modules/models/runtimes.yaml +0 -556
  49. package/runtime/modules/models/tiers.yaml +0 -66
  50. package/runtime/scripts/api/git/cat-file.mjs +0 -4
  51. package/runtime/scripts/api/git/config-get.mjs +0 -9
  52. package/runtime/scripts/api/git/diff.mjs +0 -4
  53. package/runtime/scripts/api/git/lib.mjs +0 -80
  54. package/runtime/scripts/api/git/ls-files.mjs +0 -5
  55. package/runtime/scripts/api/git/ls-tree.mjs +0 -4
  56. package/runtime/scripts/api/git/merge-base.mjs +0 -8
  57. package/runtime/scripts/api/git/remote.mjs +0 -4
  58. package/runtime/scripts/api/git/rev-parse-query.mjs +0 -4
  59. package/runtime/scripts/api/git/show.mjs +0 -5
  60. package/runtime/scripts/api/git/tag.mjs +0 -4
  61. package/runtime/scripts/hfs/allows.mjs +0 -77
  62. package/runtime/scripts/hfs/architecture/ast-walks.mjs +0 -250
  63. package/runtime/scripts/hfs/architecture/automatic-gates.mjs +0 -103
  64. package/runtime/scripts/hfs/architecture/backend-app-files.mjs +0 -114
  65. package/runtime/scripts/hfs/architecture/backend.mjs +0 -462
  66. package/runtime/scripts/hfs/architecture/background-unowned.mjs +0 -254
  67. package/runtime/scripts/hfs/architecture/canon-clones.mjs +0 -291
  68. package/runtime/scripts/hfs/architecture/canon-jsx-clones.mjs +0 -224
  69. package/runtime/scripts/hfs/architecture/client-reaches-server.mjs +0 -102
  70. package/runtime/scripts/hfs/architecture/clones.mjs +0 -287
  71. package/runtime/scripts/hfs/architecture/component-tiers.mjs +0 -161
  72. package/runtime/scripts/hfs/architecture/config-unread.mjs +0 -16
  73. package/runtime/scripts/hfs/architecture/config.mjs +0 -407
  74. package/runtime/scripts/hfs/architecture/connection-map.mjs +0 -350
  75. package/runtime/scripts/hfs/architecture/constructor-deps.mjs +0 -115
  76. package/runtime/scripts/hfs/architecture/context-coupling.mjs +0 -117
  77. package/runtime/scripts/hfs/architecture/context-map.mjs +0 -355
  78. package/runtime/scripts/hfs/architecture/context-owner.mjs +0 -102
  79. package/runtime/scripts/hfs/architecture/context-platform-tables.mjs +0 -65
  80. package/runtime/scripts/hfs/architecture/context-transaction.mjs +0 -75
  81. package/runtime/scripts/hfs/architecture/contract-bounds.mjs +0 -72
  82. package/runtime/scripts/hfs/architecture/contract-fixture-guard.mjs +0 -177
  83. package/runtime/scripts/hfs/architecture/contracts-readonly.mjs +0 -360
  84. package/runtime/scripts/hfs/architecture/contracts.mjs +0 -489
  85. package/runtime/scripts/hfs/architecture/cross-app-duplicate.mjs +0 -81
  86. package/runtime/scripts/hfs/architecture/dead-exports-bindings.mjs +0 -173
  87. package/runtime/scripts/hfs/architecture/dead-exports.mjs +0 -420
  88. package/runtime/scripts/hfs/architecture/default-deny.mjs +0 -175
  89. package/runtime/scripts/hfs/architecture/doc-language.mjs +0 -45
  90. package/runtime/scripts/hfs/architecture/entity-registry.mjs +0 -51
  91. package/runtime/scripts/hfs/architecture/entrypoint.mjs +0 -75
  92. package/runtime/scripts/hfs/architecture/error-codes.mjs +0 -54
  93. package/runtime/scripts/hfs/architecture/error-masked.mjs +0 -78
  94. package/runtime/scripts/hfs/architecture/fe-slot-allows.mjs +0 -44
  95. package/runtime/scripts/hfs/architecture/feature-shape.mjs +0 -60
  96. package/runtime/scripts/hfs/architecture/framework-pinned.mjs +0 -41
  97. package/runtime/scripts/hfs/architecture/frontend-block-render.mjs +0 -112
  98. package/runtime/scripts/hfs/architecture/frontend-grammar.mjs +0 -193
  99. package/runtime/scripts/hfs/architecture/frontend-routing.mjs +0 -198
  100. package/runtime/scripts/hfs/architecture/frontend-world-render.mjs +0 -368
  101. package/runtime/scripts/hfs/architecture/frontend-world.mjs +0 -374
  102. package/runtime/scripts/hfs/architecture/frontend.mjs +0 -248
  103. package/runtime/scripts/hfs/architecture/function-spec-providers.mjs +0 -185
  104. package/runtime/scripts/hfs/architecture/hfs-graph.mjs +0 -77
  105. package/runtime/scripts/hfs/architecture/hfs.mjs +0 -394
  106. package/runtime/scripts/hfs/architecture/hooks-are-hooks.mjs +0 -118
  107. package/runtime/scripts/hfs/architecture/i18n-keys.mjs +0 -213
  108. package/runtime/scripts/hfs/architecture/identity.mjs +0 -121
  109. package/runtime/scripts/hfs/architecture/index.mjs +0 -402
  110. package/runtime/scripts/hfs/architecture/injection-token-exported.mjs +0 -69
  111. package/runtime/scripts/hfs/architecture/jwt-ast.mjs +0 -231
  112. package/runtime/scripts/hfs/architecture/machine-ast.mjs +0 -232
  113. package/runtime/scripts/hfs/architecture/managed-scripts.mjs +0 -32
  114. package/runtime/scripts/hfs/architecture/module-per-transport.mjs +0 -237
  115. package/runtime/scripts/hfs/architecture/next-data-contract.mjs +0 -126
  116. package/runtime/scripts/hfs/architecture/next-data-inference.mjs +0 -192
  117. package/runtime/scripts/hfs/architecture/next-data-key.mjs +0 -374
  118. package/runtime/scripts/hfs/architecture/next-data-symbols.mjs +0 -26
  119. package/runtime/scripts/hfs/architecture/next-data.mjs +0 -425
  120. package/runtime/scripts/hfs/architecture/operation-contract-roots.mjs +0 -55
  121. package/runtime/scripts/hfs/architecture/owners.mjs +0 -142
  122. package/runtime/scripts/hfs/architecture/package-shape.mjs +0 -92
  123. package/runtime/scripts/hfs/architecture/presentation.mjs +0 -173
  124. package/runtime/scripts/hfs/architecture/reachability.mjs +0 -330
  125. package/runtime/scripts/hfs/architecture/register-once.mjs +0 -212
  126. package/runtime/scripts/hfs/architecture/registration.mjs +0 -372
  127. package/runtime/scripts/hfs/architecture/render-graph.mjs +0 -449
  128. package/runtime/scripts/hfs/architecture/render-prop-across-server.mjs +0 -58
  129. package/runtime/scripts/hfs/architecture/required-files.mjs +0 -237
  130. package/runtime/scripts/hfs/architecture/root-packages.mjs +0 -78
  131. package/runtime/scripts/hfs/architecture/route-files-thin.mjs +0 -133
  132. package/runtime/scripts/hfs/architecture/schema-owner.mjs +0 -288
  133. package/runtime/scripts/hfs/architecture/server-action.mjs +0 -78
  134. package/runtime/scripts/hfs/architecture/side-boundary.mjs +0 -13
  135. package/runtime/scripts/hfs/architecture/source-names-shape.mjs +0 -320
  136. package/runtime/scripts/hfs/architecture/source-names.mjs +0 -393
  137. package/runtime/scripts/hfs/architecture/sql-keys.mjs +0 -344
  138. package/runtime/scripts/hfs/architecture/sql-owner.mjs +0 -291
  139. package/runtime/scripts/hfs/architecture/sql-returning.mjs +0 -76
  140. package/runtime/scripts/hfs/architecture/sql-token-forms.mjs +0 -117
  141. package/runtime/scripts/hfs/architecture/sql-tokens.mjs +0 -587
  142. package/runtime/scripts/hfs/architecture/staged-consumers.mjs +0 -42
  143. package/runtime/scripts/hfs/architecture/surface-nesting.mjs +0 -127
  144. package/runtime/scripts/hfs/architecture/surface.mjs +0 -88
  145. package/runtime/scripts/hfs/architecture/symbols.mjs +0 -273
  146. package/runtime/scripts/hfs/architecture/test-world-files.mjs +0 -263
  147. package/runtime/scripts/hfs/architecture/tiers.mjs +0 -256
  148. package/runtime/scripts/hfs/architecture/transport-owner.mjs +0 -248
  149. package/runtime/scripts/hfs/architecture/type-context.mjs +0 -335
  150. package/runtime/scripts/hfs/architecture/typescript.mjs +0 -477
  151. package/runtime/scripts/hfs/architecture/unit-spec-providers.mjs +0 -165
  152. package/runtime/scripts/hfs/declaration-shape.mjs +0 -196
  153. package/runtime/scripts/hfs/declaration-slots.mjs +0 -89
  154. package/runtime/scripts/hfs/edition-slots.mjs +0 -80
  155. package/runtime/scripts/hfs/explicit-surface-rule.mjs +0 -59
  156. package/runtime/scripts/hfs/linear-text.mjs +0 -30
  157. package/runtime/scripts/hfs/manifest-shape.mjs +0 -474
  158. package/runtime/scripts/hfs/param-names.mjs +0 -13
  159. package/runtime/scripts/hfs/path-findings.mjs +0 -167
  160. package/runtime/scripts/hfs/repo-identity.mjs +0 -89
  161. package/runtime/scripts/hfs/rule-catalog.mjs +0 -458
  162. package/runtime/scripts/hfs/rule-params-shape.mjs +0 -103
  163. package/runtime/scripts/hfs/rules/database-constants.mjs +0 -25
  164. package/runtime/scripts/hfs/rules/database-migrations.mjs +0 -684
  165. package/runtime/scripts/hfs/rules/fe-no-tests.mjs +0 -68
  166. package/runtime/scripts/hfs/rules/read.mjs +0 -45
  167. package/runtime/scripts/hfs/rules/secrets.mjs +0 -79
  168. package/runtime/scripts/hfs/rules/spec-placement.mjs +0 -28
  169. package/runtime/scripts/hfs/slot-app-view.mjs +0 -97
  170. package/runtime/scripts/hfs/slot-classify.mjs +0 -69
  171. package/runtime/scripts/hfs/slot-errors.mjs +0 -12
  172. package/runtime/scripts/hfs/slot-imports.mjs +0 -98
  173. package/runtime/scripts/hfs/slot-manifest-shape.mjs +0 -111
  174. package/runtime/scripts/hfs/slot-match.mjs +0 -164
  175. package/runtime/scripts/hfs/slot-path.mjs +0 -6
  176. package/runtime/scripts/hfs/slot-required.mjs +0 -95
  177. package/runtime/scripts/hfs/slot-semantic-problems.mjs +0 -175
  178. package/runtime/scripts/hfs/slot-side-problems.mjs +0 -32
  179. package/runtime/scripts/hfs/slots.mjs +0 -306
  180. package/runtime/scripts/hfs/test-world-slot.mjs +0 -5
  181. package/runtime/scripts/hfs/trailing-slashes.mjs +0 -8
  182. package/runtime/scripts/hfs/typescript-programs.mjs +0 -95
  183. package/runtime/scripts/hfs/view.mjs +0 -180
  184. package/runtime/scripts/lib/declaration-surface.mjs +0 -166
  185. package/runtime/scripts/lib/dockerfile.mjs +0 -164
  186. package/runtime/scripts/lib/env.mjs +0 -18
  187. package/runtime/scripts/lib/event-contract.mjs +0 -102
  188. package/runtime/scripts/lib/git-hooks-dir.mjs +0 -30
  189. package/runtime/scripts/lib/git.mjs +0 -35
  190. package/runtime/scripts/lib/glob.mjs +0 -32
  191. package/runtime/scripts/lib/grammar-lint.mjs +0 -57
  192. package/runtime/scripts/lib/i18n.mjs +0 -82
  193. package/runtime/scripts/lib/in-order.mjs +0 -90
  194. package/runtime/scripts/lib/json-clone.mjs +0 -70
  195. package/runtime/scripts/lib/json.mjs +0 -44
  196. package/runtime/scripts/lib/language.mjs +0 -233
  197. package/runtime/scripts/lib/list.mjs +0 -26
  198. package/runtime/scripts/lib/mutation-fence.mjs +0 -20
  199. package/runtime/scripts/lib/package-at.mjs +0 -62
  200. package/runtime/scripts/lib/path-key.mjs +0 -124
  201. package/runtime/scripts/lib/read-text.mjs +0 -47
  202. package/runtime/scripts/lib/regex.mjs +0 -3
  203. package/runtime/scripts/lib/rule-packs.mjs +0 -243
  204. package/runtime/scripts/lib/same-text.mjs +0 -4
  205. package/runtime/scripts/lib/secret-patterns.mjs +0 -230
  206. package/runtime/scripts/lib/sops-envelope.mjs +0 -212
  207. package/runtime/scripts/lib/stack-services.mjs +0 -191
  208. package/runtime/scripts/lib/ts-analysis.mjs +0 -39
  209. package/runtime/scripts/lib/ts-ast.mjs +0 -63
  210. package/runtime/scripts/lib/walk.mjs +0 -45
  211. package/runtime/scripts/lib/yaml-cached.mjs +0 -14
@@ -1,2783 +0,0 @@
1
- # HFS slot manifest (owner-approved 2026-09-29, decisions 1-10 in the owner decisions record).
2
- # The one place that says what may exist in a StarCi product repository and where. A product is ONE app repository
3
- # (hfs 4, manifest major 3): the app root holds the one package.json, lockfile and node_modules, the hfs.json of kind app,
4
- # the CI, the hooks and .starciwork (slots of profile `app`); `be/` and `fe/` are its two sides, each laid out as a
5
- # standalone repository root (slots of profile be or fe, paths relative to the side folder). Every tracked path of every
6
- # repository must match exactly one slot. Checks, lint factories, the architecture machine, templates and the why
7
- # catalog READ this file through scripts/hfs/slots.mjs; none of them hardcodes a path.
8
- # Shape: modules/schemas/hfs-slots.schema.yaml. The repository side is hfs.json: modules/schemas/hfs-repo.schema.yaml.
9
- schema: starci/hfs-slots@3
10
- version: 3.13.0
11
-
12
- versioning:
13
- # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
14
- patch: wording, why text, examples; no check result can change.
15
- minor: >-
16
- add a slot (always presence optional or opt-in), add an app kind or protocol slot, add a rule at severity warn,
17
- tighten a budget that no pinned repo currently exceeds. A minor never changes an existing slot's path,
18
- presence, imports or tests. Every repo pinned to the same MAJOR stays green without edits.
19
- major: >-
20
- change or remove an existing slot, make an optional slot required, promote a rule warn to error, change the
21
- direction matrix. Needs owner approval and a migration lane per repo. There is no compatibility window: the old
22
- MAJOR is refused the day the new one lands (owner ruling: no backward compatibility).
23
- pins: knowledge/hfs/canon-pins.yaml carries the exact versions of every @starci/* package and framework this MAJOR supports.
24
- # 2.1.0 is such a minor: it ADDS the edition mechanism (the `editions` list, the per-slot `editions`, `litePresence`, `lite`
25
- # overlays and `provider`, and `sides.<side>.reads` of an app-root tree) and the lite slots; an app without `edition` in its
26
- # hfs.json is edition full and every answer for it is unchanged.
27
- # 2.2.0 adds the declaration-only fe.modules.types.ambient owner.
28
- # 3.0.0 is a major (ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4)): lite is the full code structure deployed with Supabase backing services
29
- # and without e2e, and the front end is one standard for both editions (knowledge/hfs/fe-stack.yaml). The
30
- # front-end database slots and the Supabase realtime feature slot are removed (Supabase on the front end is auth only, realtime
31
- # is the socket.io gateway in both editions), fe.route holds pages, layouts and the one health/live route handler, and the slots
32
- # marked `since: 3.0.0` are added: the Apollo, SWR, RHF, zustand and socket.io hooks, redux, modules/auth, modules/toast, the
33
- # providers, be.assets and the migration archive.
34
- # 3.1.0 is a minor (owner ruling 2026-10-14, R245 and R246): every be.app.* slot allows `<app>.env.ts` and the composition groups
35
- # `compose/<area>.ts` and budgets its app files (`app.module.ts` 250, `<app>.options.ts` 200, `<app>.env.ts` 150,
36
- # `compose/<area>.ts` 120, `main.ts` 80); `<app>.env.ts` exports interface <App>Env and read<App>Env(env: EnvSource): <App>Env
37
- # for fail-fast env parsing only, and `<app>.options.ts` holds env-derived options and port bindings only, with no parsing
38
- # or environment reads (BE_APP_OPTIONS_COMPOSITION). Secrets use EnvSource.secret(): <NAME>_FILE first, plain <NAME> only
39
- # when the file key is absent; .starcistacks owns custody. Capability <capability>.config.ts roles stay unchanged.
40
- # 3.3.0 is a minor (alpha.16): it ADDS the optional app.ci-stack-deploy slot, the managed workflow of the starci app stack verbs.
41
- # 3.9.0 (ruling:lite-self-hosted-postgres-passport-minio, 2026-10-29) is a major for lite and changes no full slot but the S3 owner's
42
- # folder: lite leaves Supabase. The app.supabase* and be.integrations.supabase slots and fe.route.callback are removed; app.db (db/, its
43
- # migrations, archive, seed and managed bootstrap), be.integrations.passport and be.integrations.object-storage are added; lite's schemaAuthority is sql.
44
- # 3.4.0 is a minor (alpha.25): it ADDS the opt-in be.contract.mcp-tools slot, the committed MCP tool-catalog snapshot of an app.
45
- # 3.5.0 is a minor (alpha.27): it ADDS the opt-in app.browser-config slot, the managed browser/tsconfig.json that type-checks the browser
46
- # journey (enabled with app.browser by `browser: true`).
47
- # 3.6.0 is a minor (alpha.30): it ADDS the opt-in be.feature.realtime.sse slot, the server-sent-events door of the realtime kind (owner decision
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
- # 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
- # 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).
53
- # 3.11.0 (ruling:lite-official-postgres-image, 2026-10-29) is, like 3.9.0, a change for lite only: it ADDS the managed app.db.image slot
54
- # (db/Dockerfile, written by `starci app sync --execute`), narrows ruleParams.db.extensions to the extensions that image carries, and gives
55
- # @nestjs/schedule and cron one owner, platform/jobs (R335).
56
- # 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
57
- # admits pgmq, the event bus, ruleParams.db.queueOutbox is retired with the pg_cron half of R258, the lite event-bus functions replace
58
- # event_bus_write in ruleParams.be.dbFunctions, and app.db.image moves to .starcistacks/images/db/Dockerfile (db/ keeps schema and data).
59
-
60
- # Field meaning, per slot.
61
- # id stable name, never changes meaning inside a major.
62
- # profiles app (the app root; alone), or be, fe or both: the sides the slot exists in (its path is relative to the side folder).
63
- # path pattern. <name> is one path segment (bound to the variable name), * and ? stay inside a segment,
64
- # ** spans directories, {a,b} alternates. A pattern ending in / is a directory: it owns everything
65
- # below it, except what a more specific slot owns. Otherwise it names files.
66
- # presence required | optional | opt-in (legal only when hfs.json lists it or declares an app of its kind) | forbidden.
67
- # A slot is optional in the sense of the requirements list when its presence is not required.
68
- # tracked tracked (committed) | ignored (may exist, must be gitignored) | external (must not exist in the tree;
69
- # goesTo says where it lives).
70
- # tier node of the import direction matrix (tiers below); none = takes no part in import checks;
71
- # inherit = the tier of the enclosing owner.
72
- # owner true when every directory matching the slot is an owner: the unit cross-owner imports and cycles use.
73
- # entries on a directory slot that sits inside an owner (not an owner itself): the files, besides the owner's index.ts, an importer
74
- # outside the owner may enter through (a client-safe entry of a module whose barrel is server-only). Each is a relative
75
- # path the slot allows. Everything else of the owner is entered through index.ts only (ARCH_OWNER_EXPORT_BYPASS).
76
- # outcomeHome true on a file slot: the one file that declares the repository's Outcome union. A repository holds exactly one such
77
- # file (modules/api/outcome.ts, the api package's outcome.ts, or modules/db/outcome.ts of a lite app),
78
- # and no other file declares an Outcome union (one-outcome-union, FE_TRANSPORT_OWNER).
79
- # role on a file slot: the one part it plays that a rule reads. entity-registry = the lite PRIMARY_ENTITIES list
80
- # (be.platform.database.entities): the one platform file that imports capability <c>Entities, imported by deep path
81
- # only from the files importedBy names (architecture/entity-registry.mjs).
82
- # importedBy on a slot with a role: the side-relative path patterns of the only files that import its file by deep path.
83
- # requires files or directories that must exist inside each instance; <var> is replaced by the bound name,
84
- # a leading / means repository root; a trailing / means directory.
85
- # requiredInstances variable -> names that must exist as instances (config, logging ... of platform).
86
- # minInstances at least this many instances (one feature, one api app).
87
- # requiredWhen connections: required only when hfs.json declares a database connection.
88
- # allows / forbids names inside the instance; the loader exposes them, slot-check enforces them.
89
- # tests unit-beside | e2e | none.
90
- # coverage required | none, on every tracked slot of profile be. A required slot's subtree is measured at 100 per file on every
91
- # ruleParams.be.logicRoles file and on every file a slot of it declares in `logic` (lines, branches, functions,
92
- # statements); a none slot's subtree is never measured and is excluded from Sonar's coverage. scripts/hfs/coverage-scope.mjs
93
- # derives the jest per-file thresholds, Sonar's sonar.coverage.exclusions and the Codecov paths and components from this
94
- # field and `logic` and nowhere else (R204). Orthogonal to the lite `editions`: an edition never changes what a slot measures.
95
- # logic on a coverage-required unit-beside directory slot: the files of the slot that carry logic without a logic-role suffix
96
- # (`<name>.<part>.ts`, relative to the slot path, each one the slot requires or allows, none of a logic role). Each is
97
- # measured at 100 per file like a logic-role file, and its `<name>.<part>.spec.ts` beside it is a legitimate unit spec
98
- # (R47, R48): the slot admits it without listing it. No role name is added to ruleParams.be.logicRoles.
99
- # composedBy the app kinds allowed to compose a transport slot (an app of another kind imports none of its modules); on an
100
- # owner slot (be.cli) the app kinds that list its root module, every folder of the root holding one static module.
101
- # budget size budgets (lines per file, files per slot, exports).
102
- # trigger the trigger kind (triggerKinds) of a feature-tier slot: api, webhooks, realtime, saga, reactors, jobs or cli. A feature of one kind
103
- # never imports a feature of another (BE_KIND_ISOLATION); the two meet only through the event bus.
104
- # pattern the design pattern whose declaration (hfs.json sides.<side>.patterns) enables this opt-in slot; a path in the slot of an
105
- # undeclared pattern is HFS_SLOT_NOT_ENABLED, and a declared pattern's proof scenarios are ruleParams.be.patternScenarios.
106
- # appKind the app kind of hfs.json apps[].kind whose directory this slot describes.
107
- # managedBy the template directory starci app sync renders this slot's files from. The slot path then lists literal files
108
- # only, and each is rendered from templates/<profile or common>/<managedBy>/<path, leading dots dropped>;
109
- # liteManagedBy the template directory starci app sync renders under edition lite (default: managedBy). A slot with only
110
- # liteManagedBy is managed only in lite; its effective lite.path still lists literal files.
111
- # the managed file list lives here and nowhere in code. A difference is HFS_MANAGED_FILE_DRIFT (a
112
- # back end's tsconfig.json: HFS_TS_STRICT when a flag or an option was added).
113
- # rules rule codes from knowledge/hfs/rules.yaml.
114
- # editions the editions (below) the slot exists in; default all of them. A slot outside the declared edition owns
115
- # no path - under lite, what full keeps absent is removed, and what lite forbids is a finding.
116
- # litePresence the presence under edition lite (default: presence): a bare value, or {be, fe} for a both-sides slot.
117
- # A slot forbidden in lite is external there and must name its goesTo. Only infrastructure is forbidden in lite:
118
- # database/broker services, the e2e layer and its workflow, and the browser journey. Lite may have contract specs.
119
- # editionWhy why the slot's presence, shape or adapter differs between lite and full, with the owning ruling citation.
120
- # lite the fields the slot carries under lite only (path, requires, allows, forbids, minInstances,
121
- # requiredInstances, why), each shaped as the same field in the slot body; every other field is the edition's.
122
- # `why` under lite names the adapter behind the slot's ports (pgmq, Postgres locks, in-process socket.io).
123
- # `tests` is never overlaid: a lite slot owes exactly the unit specs its full slot owes.
124
- # provider the hfs.json connections[].provider that enables this opt-in slot (postgres); never an app kind.
125
- # since the manifest version that introduced the slot.
126
- presenceValues: [required, optional, opt-in, forbidden]
127
- trackedValues: [tracked, ignored, external]
128
- testValues: [unit-beside, e2e, none]
129
-
130
- # The editions a repository declares in hfs.json `edition` (absent means full). ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite IS
131
- # the full architecture on its own self-hosted PostgreSQL (ruling:lite-self-hosted-postgres-passport-minio) - the same monorepo, slots, CQRS shape and patterns (queue,
132
- # event bus, saga, reactors, projection, realtime, webhooks, fenced job), declared in hfs.json the same way, and the same unit
133
- # specs (unitRoles, logicRoles, 100 per file, @starci/jest-preset doubles, builders). What differs is ADAPTERS and DELIVERY
134
- # (ruling:R212/case-10): schema authority in db/migrations, the queue port on BullMQ over the Redis hfs.json
135
- # sides.be.backing declares (as in full, fed by the Postgres outbox), event-bus ports on pgmq topics sent in the publisher's
136
- # transaction (ruling:lite-pgmq-bus-bullmq-jobs), cache and locks on Postgres or the declared Redis, schedules as platform/jobs ticks enqueueing through the queue
137
- # outbox (R335), storage on S3-compatible MinIO (integrations/object-storage) and auth through integrations/passport. Realtime uses SSE or the socket.io gateway
138
- # in the api process, which scales horizontally and stateless (memory hub for one replica or tests; the Redis hub and @socket.io/redis-adapter when Redis is declared, else the Postgres hub and @socket.io/postgres-adapter, for N replicas; websocket only, no sticky sessions). Integration and provider sandbox contract specs are optional;
139
- # declared patterns owe their integration proofs (R284). Lite has no e2e world. Production uses declared docker-swarm under
140
- # .starcistacks/production/infra/swarm/ (owner ruling 2026-10-14); lite runs its PostgreSQL as the db service of its
141
- # stack and only the backing services sides.be.backing declares. The front end is full's (R97).
142
- # Lite is this same manifest filtered: a slot whose `editions` lacks lite does not exist for a lite app, `litePresence` replaces
143
- # presence and a `lite` map replaces the fields it names. The edition is chosen once at scaffold; there is no upgrade
144
- # or downgrade between lite and full. Lite contracts are allowed (owner decision 2026-10-14).
145
- editions: [full, lite]
146
-
147
- # The two sides of an app: the folder of each is its profile name (be/, fe/). `reads` lists the only paths of the OTHER side a side
148
- # may read (hfs.json sides.<side>.reads names a subset), or a tree an app-root slot owns; nothing else crosses sides.
149
- sides:
150
- be: {reads: []}
151
- fe: {reads: [be/contracts/]} # be/contracts/: the committed contract snapshots, the input of the front end's codegen
152
-
153
- # The trigger kinds of the back end's features: what starts the work of a feature. A feature slot names its kind in `trigger`; no kind imports another
154
- # (BE_KIND_ISOLATION), every cross-kind call is an event on the bus, and only be/apps/* compose features.
155
- triggerKinds: [api, webhooks, realtime, saga, reactors, jobs, cli]
156
-
157
- appKinds:
158
- be: [api, worker, cli]
159
- fe: [next]
160
-
161
- # RT_SLOT_ID_SHAPE — the slot-id grammar and the suffix vocabulary law, stated once (scripts/checks/check-slot-id-shape.mjs
162
- # reads this block): an id is dot-separated lowercase kebab segments whose first segment is one of `prefixes`;
163
- # `<side>.app.<kind>` names a kind of appKinds.<side>; any other deeper id extends a declared slot id (its `parent`)
164
- # or names `parent` explicitly. The role-suffix vocabulary never shares a word with bannedSuffixes and holds no
165
- # synonym pair beyond `sameConceptPairs` — the one owner-approved pair (step + saga-step: `.saga-step.ts` stays).
166
- # Every pair in `refusedPairs` may never both be live suffixes.
167
- # `glossary` (S9-02): the five names for "handles an incoming thing" are five distinct kinds, not synonyms —
168
- # consumer answers an event, subscription serves realtime, webhook is its own kind, processor runs a job, handler
169
- # is CQRS. That is why appKinds may say worker while bannedSuffixes refuses the worker/job file suffixes.
170
- naming:
171
- prefixes: [app, be, fe, repo]
172
- sameConceptPairs: [[step, saga-step]]
173
- refusedPairs: [[use-case, handler], [listener, subscription], [job, processor], [worker, processor], [dto, input], [repository, mapper]]
174
- glossary: {consumer: event, subscription: realtime, webhook: webhook, processor: job, handler: cqrs}
175
-
176
- # ---------------------------------------------------------------------------------------------------------
177
- # Tiers and the dependency direction matrix (owner granularity; type-only imports count; no cycles anywhere)
178
- # mayImport lists the tiers a file of that tier may import. Importing inside the same owner is always allowed.
179
- # mayImportKinds narrows a permitted tier edge to its named from/to folder kinds; other kind pairs remain forbidden.
180
- # ---------------------------------------------------------------------------------------------------------
181
- tiers:
182
- be:
183
- app: {mayImport: [feature, domain, events, queues, projections, platform, integrations, package]}
184
- feature: {mayImport: [domain, events, queues, projections, platform, integrations, package]} # never another feature
185
- domain: {mayImport: [domain, events, queues, platform, integrations, package], acyclic: true} # a domain service writes the outbox: it publishes events and enqueues queue jobs inside its own transaction
186
- events: {mayImport: [events, platform, package], acyclic: true} # modules/events/<service>: typed event classes (pattern event-bus)
187
- queues: {mayImport: [queues, events, platform, package], acyclic: true} # modules/queues/<queue>: typed producers and schedulers (pattern queue)
188
- projections: {mayImport: [projections, domain, events, platform, integrations, package], acyclic: true} # modules/projections/<name>: read models (pattern projection)
189
- integrations: {mayImport: [platform, package]}
190
- platform: {mayImport: [platform, package], acyclic: true}
191
- e2e: {mayImport: [e2e, app, feature, domain, events, queues, projections, platform, integrations, fixtures, package]}
192
- fixtures: {mayImport: [domain, events, queues, projections, platform, integrations, package]} # public contracts only
193
- package: {mayImport: [package]}
194
- fe:
195
- route: {mayImport: [feature, foundation, modules, transport, package]} # app/** adapters
196
- feature: {mayImport: [feature, components, hooks, foundation, modules, package], mayImportKinds: {feature: {from: [pages, layouts], to: [overlays]}}} # pages and layouts compose overlays and blocks; data goes through hooks/swr
197
- # A component never reaches data: config, routes, i18n and types are foundation; every other module and the api
198
- # transport are reached through a hook (owner decision 2026-09-29).
199
- components: {mayImport: [components, hooks, foundation, package], lowerLayerOnly: true} # blocks, frames, composites, branches, leaves
200
- # Across domains a hook is imported only through the other domain's public index (hooks/<domain>/index.ts), never deep.
201
- hooks: {mayImport: [hooks, foundation, modules, transport, package], mayImportSlots: {transport: {from: [fe.hooks.swr]}}} # only hooks/swr imports an operation
202
- foundation: {mayImport: [foundation, package], acyclic: true} # modules/{config,i18n,routes,types}
203
- modules: {mayImport: [foundation, modules, transport, package], acyclic: true}
204
- transport: {mayImport: [foundation, modules, package]} # modules/api: the one fetch
205
- package: {mayImport: [package]}
206
- crossOwner: every import across owners targets the owner's public entry (index.ts or index.tsx); never export *.
207
- crossApp: apps never import each other; shared code is a packages/<pkg> slot.
208
-
209
- # Parameters the lint factories and checks read per profile (through ruleParams(profile) in scripts/hfs/slots.mjs, which
210
- # merges common under the profile: a side restates a common key only to override it).
211
- ruleParams:
212
- db:
213
- # R259: btree_gist supplies UUID equality for the booking interval exclusion constraint.
214
- # R259: the extensions the db image carries (ruling:lite-official-postgres-image): the official postgres image's contrib set and pgvector
215
- # from PGDG; unaccent serves Vietnamese-content search functions; pgmq is the event bus (ruling:lite-pgmq-bus-bullmq-jobs), installed
216
- # from its pinned release. No pg_cron, pg_net or supabase_vault.
217
- extensions: [pgcrypto, pg_trgm, vector, uuid-ossp, unaccent, btree_gist, pgmq]
218
- common:
219
- # HFS_SIZE_GROWTH: a file above soft may not grow against its parent commit; a new file stays within soft. Slot
220
- # budgets (component.tsx 300, hooks 200, modules 400) are stricter than this cap where they apply.
221
- fileLines: {soft: 500, hardGrowth: true}
222
- functionLines: 80
223
- featureFiles: 250
224
- # R21 HFS_DUPLICATE_CODE: the one threshold of duplicate code of both sides (the architecture machine reads it here;
225
- # no other file states it): a token-normalised block of at least `lines` source lines and `tokens` tokens that appears twice.
226
- duplicateBlock: {lines: 8, tokens: 60}
227
- be:
228
- # R90 BE_INFRA_OWNER: raw infrastructure library (a module specifier or a global reference) -> the platform or
229
- # integration capabilities allowed to import it; [] means nowhere in a back end. A specifier also covers its subpaths.
230
- infraOwners:
231
- fetch: [platform/http]
232
- axios: [platform/http]
233
- got: [platform/http]
234
- undici: [platform/http]
235
- "node:http": [platform/http]
236
- "node:https": [platform/http]
237
- http: [platform/http]
238
- https: [platform/http]
239
- "@aws-sdk/client-s3": [] # the S3 client is a dependency of @starci/object-storage, imported by no app file (R331)
240
- "@aws-sdk/s3-request-presigner": []
241
- "@starci/object-storage": [integrations/object-storage] # the ObjectStorage port: one S3 adapter for MinIO, S3 and Spaces (R331)
242
- minio: [] # storage goes through @starci/object-storage
243
- nodemailer: [] # the SMTP client is a dependency of @starci/mail alone; no app file imports it
244
- "@starci/mail": [integrations/mail] # outgoing mail: the Mailer port, parsed and registered by its one glue
245
- "@supabase": [] # no Supabase client in a back end
246
- "@nestjs/passport": [] # the identity libraries are @starci/auth's dependencies, never an app's (R328)
247
- passport: []
248
- passport-google-oauth20: []
249
- passport-local: []
250
- "@nestjs/jwt": []
251
- jose: []
252
- bcryptjs: []
253
- 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)
254
- jwks-rsa: []
255
- jwt-decode: []
256
- passport-jwt: []
257
- openid-client: []
258
- "@starci/auth": [integrations/passport] # the lite sign-in package: its server entry is reached only through integrations/passport (R328)
259
- "@starci/auth/testing": [integrations/passport] # its test doubles, for the glue's specs
260
- "@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)
261
- "@starci/auth-oidc/testing": [integrations/keycloak] # its fake issuer, for the glue's specs
262
- bcrypt: []
263
- cache-manager: [integrations/cache, integrations/redis]
264
- "@nestjs/cache-manager": [integrations/cache, integrations/redis] # the CACHE_MANAGER token: caching goes through the cache capability
265
- redis: [integrations/cache, integrations/redis]
266
- ioredis: [integrations/cache, integrations/redis, platform/realtime]
267
- "@keyv/redis": [integrations/cache, integrations/redis]
268
- cache-manager-redis-yet: [integrations/cache, integrations/redis]
269
- cache-manager-ioredis-yet: [integrations/cache, integrations/redis] # the Redis hub and the sharded socket.io adapter of platform/realtime
270
- bullmq: [platform/queue] # pattern queue: BullMQ jobs and job schedulers (the relay of the outbox into queues)
271
- "@nestjs/bullmq": [platform/queue]
272
- bull: [platform/queue]
273
- "@nestjs/bull": [platform/queue]
274
- kafkajs: [platform/event-bus] # pattern event-bus: Kafka is the only event transport
275
- "@nestjs/schedule": [platform/jobs] # R335: only the tick scheduler of platform/jobs (jobs.scheduler.ts); elsewhere a schedule is a BullMQ job scheduler of a queue
276
- cron: [platform/jobs] # R335: CronJob of the tick scheduler
277
- eventemitter2: []
278
- setInterval: [platform/retry, platform/event-bus, platform/queue, platform/http, platform/realtime]
279
- setTimeout: [platform/retry, platform/event-bus, platform/queue, platform/http]
280
- "node:timers": [platform/retry, platform/event-bus, platform/queue, platform/http]
281
- "node:timers/promises": [platform/retry, platform/event-bus, platform/queue, platform/http]
282
- winston: [platform/logging]
283
- "node:async_hooks": [platform/logging]
284
- nestjs-cls: []
285
- dayjs: [platform/clock, platform/primitives]
286
- moment: [platform/clock, platform/primitives]
287
- date-fns-tz: [platform/clock, platform/primitives]
288
- "@nestjs/config": []
289
- dotenv: []
290
- "@nestjs/event-emitter": []
291
- "@nestjs/platform-socket.io": [platform/realtime]
292
- socket.io: [platform/realtime]
293
- graphql-subscriptions: [platform/realtime]
294
- graphql-ws: [platform/realtime]
295
- "@socket.io/postgres-adapter": [platform/realtime] # the stateless socket.io adapter of a scaled lite back end without Redis
296
- "@socket.io/redis-adapter": [platform/realtime] # the sharded socket.io adapter of a scaled back end on the declared Redis
297
- pg: [platform/realtime] # the LISTEN connection of the Postgres hub; every other query goes through TypeORM
298
- # BE-AI-1, BE-AI-3: every model call goes through the ai-router gateway. Its custody owner registers @starci/ai-router with the
299
- # provider keys; the one LangChain integration owns @langchain/*; no provider SDK, openai client or agent framework is imported.
300
- "@starci/ai-router": [integrations/ai-gateway]
301
- "@starci/ai-router/testing": [integrations/ai-gateway, integrations/ai] # the fake provider a spec of either side boots the gateway with
302
- "@langchain": [integrations/ai] # a scope key: every @langchain/* package
303
- "@langchain/langgraph": [] # an agent loop runs in the agent runtime, never in code
304
- "@langchain/community": [] # retrieval reads the app's own persistence through its owner
305
- langchain: [] # createAgent is an agent loop
306
- openai: [] # code calls models through @langchain/openai
307
- "@anthropic-ai/sdk": []
308
- "@google/genai": []
309
- "@google/generative-ai": []
310
- "@mistralai/mistralai": []
311
- "@openrouter/ai-sdk-provider": []
312
- "@ai-sdk": []
313
- ai: []
314
- cohere-ai: []
315
- groq-sdk: []
316
- ollama: []
317
- # R87 BE_CQRS_SHAPE no-event-bus: the in-process event vocabulary the rule refuses. `imports` maps a module
318
- # specifier to the member names that are an in-process event; `[]` flags the package itself (its emitter packages
319
- # are the `[]` owners of infraOwners above). `classes` maps a module specifier to the class names that are an
320
- # in-process bus when constructed or extended.
321
- eventBus:
322
- imports:
323
- "@nestjs/cqrs": [EventBus, EventsHandler, IEventHandler]
324
- "@nestjs/event-emitter": []
325
- classes:
326
- events: [EventEmitter]
327
- "node:events": [EventEmitter]
328
- rxjs: [Subject, BehaviorSubject, ReplaySubject, AsyncSubject]
329
- # R48 BE_SPEC_QUALITY spec-infra-double-from-kit: in a `<name>.service.spec.ts` a provider `{ provide: TOKEN, useValue: X }` takes X from
330
- # the kit named here (the package root of `kit`). The token name is normalised to UPPER_SNAKE (`EntityManager` -> ENTITY_MANAGER), the
331
- # FIRST entry whose `token` regex matches decides, and `fallback` decides for every other token. `forms` say what X may be:
332
- # Inbox-like names resolve their token declaration first: genuine platform/inbox aliases keep fakeInbox, while a business service
333
- # or queue producer containing Inbox keeps its collaborator double. An unresolved origin retains the lexical table choice.
334
- # call = `double(...)`, new = `new Double(...)`, curried = `double(...)(...)`, object = a plain object literal (REAL values),
335
- # primitive = a string/number/boolean literal, array = an array literal (multi-providers of doubles). A const bound to such a value counts.
336
- # An entry may add `from`, a regex over the path of the file that DECLARES its port's token: the declaration decides, not the import written
337
- # in the spec. A token declared in another module that ends alike is a different port (`CORRELATION_IDS` of logging is not `IDS` of ids), and
338
- # the owner's token stays that port however it is re-exported or renamed. A token that cannot be resolved is judged by its spelling.
339
- specDoubles:
340
- kit: "@starci/jest-preset"
341
- doubles:
342
- - {token: "(?:^|_)OPTIONS$", double: builder, forms: [curried, object]}
343
- - {token: "(?:^|_)ENTITY_MANAGER$", double: mockEntityManager, forms: [call]}
344
- - {token: "(?:^|_)TRANSACTION(?:_RUNNER)?$", double: fakeTransaction, forms: [call]}
345
- - {token: "(?:^|_)CLOCK$", double: FakeClock, forms: [new]}
346
- - {token: "(?:^|_)EVENT_BUS$", double: recordingEventBus, forms: [call]}
347
- - {token: "(?:^|_)QUEUE_OUTBOX$", double: recordingQueueOutbox, forms: [call]}
348
- - {token: "(?:^|_)INBOX(?:_|$)", double: fakeInbox, forms: [call]}
349
- - {token: "(?:^|_)CACHE(?:_|$)", double: fakeCache, forms: [call]}
350
- - {token: "(?:^|_)(?:LOCK|LEASE|FENCE|HOLD)(?:_|$)", double: fakeLock, forms: [call]}
351
- - {token: "(?:^|_)(?:IDS|ID_GENERATOR|ID_FACTORY)$", from: "/src/modules/platform/ids/", double: fakeIds, forms: [call]}
352
- fallback: {double: mock, forms: [call, primitive, array]}
353
- # R85 BE_RAW_INJECT injected-param-name: the names of the ports every class injects the same way (BE-CONVENTION 1.6: the parameter name
354
- # is the camelCase of the port). An entry matches a constructor parameter that carries an injector and is annotated with a type
355
- # declared outside the owner (a package, platform/* or integrations/*): `type` is the exact declared name, `typeSuffix` the end of
356
- # it. The parameter is named one of `names`, or ends in `nameSuffix` when the entry has one (`orderEntityManager` for a class that
357
- # injects two connections, `paymentOptions` beside `options`). A type no entry names is free to be named for what it is.
358
- paramNames:
359
- - {type: Clock, names: [clock]}
360
- - {type: Logger, names: [logger]}
361
- - {type: Cache, names: [cache]}
362
- - {type: CommandBus, names: [commandBus]}
363
- - {type: QueryBus, names: [queryBus]}
364
- - {type: EntityManager, names: [entityManager], nameSuffix: EntityManager}
365
- - {typeSuffix: Options, names: [options], nameSuffix: Options}
366
- # R89 BE_SOURCE_FORM: the closed role-suffix vocabulary of a source file name (<kebab-name>.<suffix>.ts; BE-CONVENTION 1.15)
367
- # and the suffixes that are never a role. index.ts, main.ts, app.module.ts and the migrations of be.persistence are the
368
- # only names outside it. Typed realtime topic builders use the existing policy role (BE-REALTIME-3 of knowledge/patterns/be/realtime.yaml).
369
- suffixes: [module, module-definition, decorators, options, config, connection, service, schema, command, query, handler, templates, compensation, saga-state, saga-step, saga, contracts, port, resolver, controller, gateway, webhook, subscription, consumer, cli, event, queue, projection, projection-entity, processor, step, input, type, args, request, response, mapper, policy, entity, sql, rows, error, messages, log-events, cache-keys, guard, interceptor, filter, client, adapter, spec, integration-spec, e2e-spec, contract-spec, global-setup, builder]
370
- # R47 BE_CONTRACT_UNGUARDED: the world's shape vocabulary. `helper` names the function a contract spec imports to erase the values of a JSON
371
- # payload (`shapeOf`); a contract spec proves a fake's fixtures by asserting helper(real) equals helper(fixture).
372
- contractShape: {helper: shapeOf}
373
- # THE list of unit-tested roles of a back end whose spec is REQUIRED (the ONE source every consumer reads: the eslint unit-test rules, hfs
374
- # spec-placement and the cli spec check, the architecture machine's unit-spec checks and the unit-run gate). A role's subject is
375
- # `<name>.<role>.ts` (inside `slot` when one is named) and its unit spec `<name>.<spec>.ts` beside it. What the unit run MEASURES is not
376
- # listed here: it is `logicRoles` over the slots whose `coverage` is required (scripts/hfs/coverage-scope.mjs). `exempt` lists the rules
377
- # the role is exempt from: a cli command is an action runner, not a thin transport (R149). A lane that adds a spec-required role adds
378
- # its entry here and nowhere else.
379
- unitRoles:
380
- - {role: service, spec: service.spec}
381
- - {role: cli, spec: cli.spec, slot: be.cli, exempt: [BE_TRANSPORT_SHAPE]}
382
- # R204 HFS_COVERAGE_SCOPE_DRIFT. THE roles that carry logic: a file `<name>.<role>.ts` of one of these roles
383
- # inside a slot whose `coverage` is required is measured at 100 per file on lines, branches, functions and statements (the three
384
- # generated consumers: jest thresholds, sonar.coverage.exclusions, codecov.yml). A role that is not listed here (module, module-definition,
385
- # options, config, command, query, contracts, port, event, queue, entity, sql, rows, messages, log-events, error, decorators, cache-keys,
386
- # projection-entity, connection, and every file with no role: index.ts, main.ts, migrations) is declaration or composition and is never measured.
387
- # A unit spec beside such a file (`<name>.<role>.spec.ts`) is legal but not required: the file owes 100, not a spec of its own.
388
- logicRoles: [service, schema, policy, projection, guard, mapper, client, adapter, filter, interceptor, processor, step, saga, saga-step, compensation, consumer, webhook]
389
- # R281 BE_SPEC_FORM_ALL_ROLES. THE logic roles whose file declares values Nest never constructs (a zod schema): its spec parses the declared
390
- # value directly and builds no testing module; every other logic role is built through `Test.createTestingModule`.
391
- valueRoles: [schema]
392
- # R203 BE_FEATURE_THIN. THE roles a feature-tier file is judged thin by: a file `<name>.<role>.ts` of one of these roles inside a slot of tier
393
- # feature maps parameters and makes ONE delegating call into modules/ (a service, the command or query bus, the event bus, a queue producer): no
394
- # branch, loop, ternary, try or throw, no computation; orchestration (step order, compensation, claim, fencing, retry) lives in platform/*.
395
- thinRoles: [handler, resolver, controller, consumer, processor, step, saga, saga-step, compensation, webhook, gateway, subscription, cli, mapper, service]
396
- # BE_PATTERN_SPEC_MISSING: a declared pattern (hfs.json sides.be.patterns) is proven on the test world. Each id below needs a test titled
397
- # "<pattern>/<id>: ..." in an e2e or integration spec (be/src/tests/e2e, be/src/tests/integration).
398
- patternScenarios:
399
- logging: [correlation-survives-queue]
400
- event-bus: [atomic-with-transaction, relay-only-after-commit, redelivery-then-dead-letter, duplicate-delivery-is-a-noop]
401
- queue: [enqueue-atomic-with-transaction, relay-job-id-is-outbox-id, scheduler-fires-once]
402
- webhooks: [bad-signature-is-refused, replay-is-refused, accepted-delivery-publishes-once]
403
- realtime: [subscriber-receives-push, foreign-topic-is-isolated, disconnect-releases-subscription, push-crosses-replicas, resume-after-reconnect]
404
- fenced-job: [claim-bumps-token, zombie-fenced-out, redispatch-isolated]
405
- projection: [recompute-is-idempotent, replay-rebuilds]
406
- idempotency: [repeat-returns-same-outcome, reused-key-other-body-is-refused]
407
- # BE_KIND_DECLARATION: the patterns an app that uses a trigger kind declares in hfs.json sides.be.patterns; the platform capabilities of those
408
- # patterns (the slots of tier platform that name the pattern) must exist.
409
- kindPatterns:
410
- api: []
411
- webhooks: []
412
- realtime: []
413
- saga: [saga]
414
- reactors: [event-bus]
415
- jobs: [fenced-job, queue]
416
- cli: []
417
- # starci app add <noun> <name>: the pattern topic (knowledge/patterns/be/<topic>.yaml) whose files tree is generated, the path variable of the
418
- # instance, what it registers in hfs.json, the options it needs (--<option>), the other nouns generated with it under the same name (a job is
419
- # the consumer of its queue, so `also: [queue]`) and the defaults of the other variables ("@name" = the name).
420
- addKinds:
421
- job: {topic: jobs, variable: job, trigger: jobs, patterns: [fenced-job, queue], also: [queue], defaults: {step: "@name"}}
422
- reactor: {topic: reactors, variable: reactor, trigger: reactors, patterns: [event-bus], needs: [event, from, service], defaults: {action: "@name"}}
423
- queue: {topic: queues, variable: queue, patterns: [queue]}
424
- webhook: {topic: webhooks, variable: provider, trigger: webhooks, patterns: [webhooks], needs: [service], defaults: {event: "@name"}}
425
- realtime: {topic: realtime, variable: channel, trigger: realtime, patterns: [realtime], needs: [service]}
426
- saga: {topic: saga, variable: saga, trigger: saga, patterns: [saga], needs: [owner, from, failed, done, service], defaults: {step: "@name"}}
427
- projection: {topic: projections, variable: name, patterns: [projection], needs: [connection]}
428
- api: {topic: api, variable: feature, trigger: api, patterns: [], needs: [service], defaults: {action: "@name"}}
429
- cli: {topic: cli, variable: group, trigger: cli, patterns: [], needs: [service], wire: {file: src/features/cli/cli.module.ts, import: "./@@group@@/@@group@@.module", symbol: "@@Group@@Module"}}
430
- bannedSuffixes: [use-case, repository, fixture, factory, store, worker, scheduler, cron, job, listener, dto, util, utils, helper, helpers, rules, types, constants, int-spec, harness-spec, test]
431
- # ruling:R212/case-10 (R212 HFS_BACKING_UNDECLARED / HFS_BACKING_UNUSED, R276 STACKS_LITE_SELFHOSTED_DB): THE backing services a back
432
- # end may declare in hfs.json sides.be.backing. `clients` are the libraries that consume the service: one of them as a dependency
433
- # is its consumer, and under lite none of them may be a dependency while the service is undeclared. `patterns` are the declared
434
- # patterns that need the service. `images` are the image repositories (the last path segment) a stack runs it from.
435
- # `editions` limits admission: owner:lite-vector-is-pgvector keeps vector search on pgvector in lite.
436
- backing:
437
- redis: {clients: [bullmq, "@nestjs/bullmq", bull, "@nestjs/bull", ioredis, redis, "@keyv/redis", cache-manager-redis-yet, cache-manager-ioredis-yet, "@socket.io/redis-adapter"], patterns: [queue, fenced-job], images: [redis, redis-stack, redis-stack-server]}
438
- qdrant: {clients: ["@qdrant/js-client-rest", "@qdrant/qdrant-js"], patterns: [], images: [qdrant], editions: [full]}
439
- # Edition lite (ruleParams(manifest, 'be', 'lite') merges these keys over the base; a map merges one level deep): the schema
440
- # authority is the SQL migration tree (db/migrations/*.sql, forward-only), so a lite back end holds no TypeORM
441
- # migration or entity under be/ (R34/R35 read schemaAuthority; be.persistence's lite overlay allows neither). The unit roles,
442
- # logic roles and spec doubles are full's (owner ruling 2026-10-12 (owner:lite-production-swarm), with the Work boundary amended by ruling:R212/case-4). infraOwners: full's owners,
443
- # bullmq in platform/queue and ioredis/redis in integrations/cache and integrations/redis (ruling:R212/case-10: the queue is
444
- # Redis in both editions; a backing library is legal only when hfs.json sides.be.backing declares its service, which
445
- # HFS_BACKING_UNDECLARED checks), except Kafka, which is owned nowhere (platform/event-bus runs pgmq topics through
446
- # the shared EntityManager); realtime is the same socket.io gateway as full, run inside the api process, scaled horizontally and stateless (hub redis when
447
- # Redis is declared, else hub postgres with @socket.io/postgres-adapter; no sticky sessions).
448
- # R334: the database functions code may call through platform/database's callDbFunction, advisoryXactLock and notify helpers,
449
- # each {name, reason}; a pg built-in is listed bare (called in pg_catalog), every other function schema-qualified (public.job_claim),
450
- # and an app adds its own, schema-qualified, in hfs.json sides.be.dbFunctions.
451
- dbFunctions:
452
- - {name: pg_advisory_xact_lock, reason: "advisoryXactLock: a transaction-scoped lock TypeORM has no API for"}
453
- - {name: hashtextextended, reason: "advisoryXactLock: the 64-bit key of a text lock name"}
454
- - {name: pg_notify, reason: "notify: LISTEN/NOTIFY of the Postgres realtime hub"}
455
- - {name: to_regproc, reason: "callDbFunction: whether an optional database function exists"}
456
- - {name: gen_random_uuid, reason: "callDbFunction: a random uuid from the database (PG13+ core, pg_catalog) where a token is minted in the transaction"}
457
- - {name: public.job_claim, reason: "platform/jobs (add job, lite): the fenced claim upsert of jobs.sql"}
458
- - {name: public.job_advance, reason: "platform/jobs (add job, lite): the token-guarded step write of jobs.sql"}
459
- - {name: public.job_complete, reason: "platform/jobs (add job, lite): the token-guarded completion of jobs.sql"}
460
- - {name: public.job_fail, reason: "platform/jobs (add job, lite): the token-guarded failure of jobs.sql"}
461
- - {name: public.job_park, reason: "platform/jobs (add job, lite): the token-guarded park as failed_awaiting_fix of jobs.sql (BE-RESILIENCE-2)"}
462
- - {name: public.job_resume, reason: "platform/jobs (add job, lite): marks parked jobs resumed by id, build or sweep, jobs.sql (BE-RESILIENCE-2)"}
463
- - {name: public.job_awaiting_fix, reason: "platform/jobs (add job, lite): the parked jobs, the owner's work items, jobs.sql (BE-RESILIENCE-2)"}
464
- - {name: public.job_tick_claim, reason: "platform/jobs (add job, lite): the once-per-minute claim of a scheduler tick, jobs.sql (R335)"}
465
- - {name: public.queue_write, reason: "platform/queue (add queue, lite): the outbox insert of queue-outbox.sql"}
466
- - {name: public.queue_waiting, reason: "platform/queue (add queue, lite): the relay read FOR UPDATE SKIP LOCKED of queue-outbox.sql"}
467
- - {name: public.queue_mark_sent, reason: "platform/queue (add queue, lite): the relay mark of queue-outbox.sql"}
468
- - {name: public.inbox_claim_event, reason: "platform/inbox (add webhook, lite): the conflict-safe delivery claim"}
469
- - {name: public.inbox_claim_client, reason: "platform/inbox (add webhook, lite): the client claim upsert returning its committed outcome"}
470
- - {name: public.inbox_save_client_outcome, reason: "platform/inbox (add webhook, lite): the saved client outcome"}
471
- - {name: public.inbox_sweep_clients, reason: "platform/inbox (add webhook, lite): the bounded retention sweep FOR UPDATE SKIP LOCKED"}
472
- - {name: public.event_bus_send, reason: "platform/event-bus (add webhook, lite): the send of a typed envelope to its pgmq topic in the publisher's transaction"}
473
- - {name: public.event_bus_read, reason: "platform/event-bus (add webhook, lite): a consumer's pgmq read with a visibility timeout"}
474
- - {name: public.event_bus_archive, reason: "platform/event-bus (add webhook, lite): the archive of a handled message"}
475
- - {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"}
476
- - {name: public.event_bus_dead_letters, reason: "platform/event-bus (add webhook, lite): the operator read of a consumer's dead-letter queue"}
477
- - {name: public.event_bus_requeue, reason: "platform/event-bus (add webhook, lite): the operator requeue of one dead letter"}
478
- - {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"}
479
- - {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"}
480
- - {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"}
481
- - {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"}
482
- - {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"}
483
- - {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"}
484
- - {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"}
485
- - {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"}
486
- # R334 (lite): the only `.query(` outside platform/database's composer and the test world is the pass-through of a file listed here
487
- # (or in hfs.json sides.be.sqlPassThrough), whose SQL text is not the app's own. Paths are relative to the side folder.
488
- sqlPassThrough:
489
- - {file: src/modules/platform/database/seed-runner.service.ts, reason: "the tracked seed file's text, run as it is (db/seed.sql); the app writes no SQL there"}
490
-
491
- lite:
492
- schemaAuthority: sql
493
- infraOwners:
494
- kafkajs: []
495
- "@qdrant/js-client-rest": []
496
- "@qdrant/qdrant-js": []
497
-
498
- slots:
499
-
500
- # ----- app root (profile app: the one repository of a product) --------------------------------------------
501
- - id: app.declaration
502
- since: 3.1.0
503
- profiles: [app]
504
- path: hfs.json
505
- presence: required
506
- tracked: tracked
507
- tier: none
508
- tests: none
509
- rules: [HFS_ARCH_CONFIG_UNREAD]
510
- - id: app.readme
511
- since: 3.1.0
512
- profiles: [app]
513
- path: README.md
514
- presence: required
515
- tracked: tracked
516
- tier: none
517
- tests: none
518
- rules: [HFS_README_*]
519
- - id: app.package-manifest
520
- since: 3.1.0
521
- profiles: [app]
522
- editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite manages its database and wiring scripts; full also manages e2e and stack test scripts. Both may run optional contracts."
523
- # The one package.json of the app, at the app root: be's dependencies and every tool, and every script; npm workspaces are
524
- # exactly fe/apps/* and fe/packages/* (HFS_MONO_WORKSPACES), each with its own package.json. be has no package.json of its own.
525
- path: package.json
526
- presence: required
527
- tracked: tracked
528
- tier: none
529
- tests: none
530
- managedBy: package-scripts # the `scripts` block only; the rest of the file is the repository's
531
- liteManagedBy: package-scripts-lite
532
- rules: [HFS_PACKAGE_MANAGER_MIXED, HFS_DEP_VERSION_SKEW, HFS_CANON_PIN_DRIFT, HFS_MANAGED_FILE_DRIFT, HFS_MONO_WORKSPACES, HFS_MONO_WORKSPACE_DEP]
533
- - id: app.task-graph
534
- since: 3.1.0
535
- profiles: [app]
536
- # The turbo task graph of the app (build, dev, lint, typecheck over the fe workspaces; build depends on ^build and caches
537
- # .next and dist): rendered by starci app sync from templates/app/task-graph/turbo.json, judged for drift by starci app check. turbo needs
538
- # it beside the root package.json and lockfile.
539
- path: turbo.json
540
- presence: required
541
- tracked: tracked
542
- tier: none
543
- tests: none
544
- managedBy: task-graph
545
- rules: [HFS_MANAGED_FILE_DRIFT, HFS_MONO_WORKSPACES]
546
- - id: app.lockfile
547
- since: 3.1.0
548
- profiles: [app]
549
- path: package-lock.json
550
- presence: required
551
- tracked: tracked
552
- tier: none
553
- tests: none
554
- rules: [HFS_PACKAGE_MANAGER_MIXED, HFS_DEP_VERSION_SKEW]
555
- - id: app.git-meta
556
- since: 3.1.0
557
- profiles: [app]
558
- path: .gitignore
559
- presence: required
560
- tracked: tracked
561
- tier: none
562
- tests: none
563
- rules: [HFS_GITIGNORE_BLOCK_DRIFT] # the marked block of .gitignore is rendered by starci app sync (templates/app/gitignore)
564
- - id: app.gitattributes
565
- since: 3.2.0
566
- profiles: [app]
567
- path: .gitattributes
568
- presence: required
569
- tracked: tracked
570
- tier: none
571
- tests: none
572
- managedBy: skeleton
573
- liteManagedBy: skeleton-lite
574
- editionWhy: "Lite renders the same managed file from skeleton-lite because the editions share one code structure while their adapters differ (ruling:R212/case-2, with Work amended by ruling:R212/case-4 and hosting by owner:lite-production-swarm)."
575
- rules: [HFS_MANAGED_FILE_DRIFT]
576
- - id: app.tool-config
577
- since: 3.1.0
578
- profiles: [app]
579
- path: "{.editorconfig,.nvmrc}"
580
- presence: required
581
- tracked: tracked
582
- tier: none
583
- tests: none
584
- managedBy: skeleton
585
- liteManagedBy: skeleton-lite
586
- editionWhy: "Lite renders the same managed files from skeleton-lite because the editions share one code structure while their adapters differ (ruling:R212/case-2, with Work amended by ruling:R212/case-4 and hosting by owner:lite-production-swarm)."
587
- rules: [HFS_MANAGED_FILE_DRIFT]
588
- - id: app.format-config
589
- since: 3.1.0
590
- profiles: [app]
591
- editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite additionally ignores the generated database row types when formatting; full has its TypeORM schema authority."
592
- # The one formatter configuration of the app (prettier walks up from every file of both sides to it): .prettierrc names
593
- # @starci/prettier-config, .prettierignore is the template.
594
- path: "{.prettierrc,.prettierignore}"
595
- presence: required
596
- tracked: tracked
597
- tier: none
598
- tests: none
599
- managedBy: tool-config
600
- liteManagedBy: tool-config-lite # the same files as full
601
- rules: [HFS_MANAGED_FILE_DRIFT, HFS_TOOL_CONFIG_LOCAL]
602
- - id: app.tool-config-optional
603
- since: 3.1.0
604
- profiles: [app]
605
- path: "{.npmrc,.npmignore}" # .npmignore: npm reads the nearest ignore file instead of the root files negations, so an app that ships inside another package keeps its sealed credentials out of the tarball here
606
- presence: optional
607
- tracked: tracked
608
- tier: none
609
- tests: none
610
- - id: app.tool-config-local
611
- since: 3.1.0
612
- profiles: [app]
613
- 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*}"
614
- presence: forbidden
615
- tracked: external
616
- tier: none
617
- tests: none
618
- 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)"
619
- rules: [HFS_TOOL_CONFIG_LOCAL]
620
- - id: app.packages-lint
621
- since: 3.17.0
622
- profiles: [app]
623
- # 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
624
- # 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.
625
- path: eslint.config.mjs
626
- presence: optional
627
- tracked: tracked
628
- tier: none
629
- tests: none
630
- rules: [HFS_MANAGED_FILE_DRIFT]
631
- - id: app.quality-config
632
- since: 3.1.0
633
- profiles: [app]
634
- path: "{sonar-project.properties,codecov.yml}"
635
- presence: required
636
- tracked: tracked
637
- tier: none
638
- tests: none
639
- managedBy: quality-config # lite renders the same files: the same coverage scope, Sonar import and Codecov flags as full
640
- rules: [HFS_SONAR_CONFIG, HFS_MANAGED_FILE_DRIFT]
641
- - id: app.hooks
642
- since: 3.1.0
643
- profiles: [app]
644
- path: ".husky/{pre-commit,pre-push}"
645
- presence: required
646
- tracked: tracked
647
- tier: none
648
- tests: none
649
- managedBy: hooks
650
- rules: [HFS_CI_E2E_AUTOMATIC, HFS_MANAGED_FILE_DRIFT]
651
- - id: app.ci
652
- since: 3.1.0
653
- profiles: [app]
654
- editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite CI proves boot through R272 wiring and checks its database artifacts; full also provides its e2e lane."
655
- path: ".github/workflows/ci.yml"
656
- presence: required
657
- tracked: tracked
658
- tier: none
659
- tests: none
660
- managedBy: ci-workflows
661
- liteManagedBy: ci-workflows-lite
662
- rules: [HFS_CI_E2E_AUTOMATIC, HFS_CI_MISSING_CANON, HFS_MANAGED_FILE_DRIFT]
663
- - id: app.ci-e2e
664
- since: 3.1.0
665
- profiles: [app]
666
- editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite has no e2e world; R272 supplies its wiring proof, while optional contracts run separately."
667
- path: ".github/workflows/e2e.yml"
668
- presence: optional # on: workflow_dispatch only
669
- litePresence: forbidden # ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite has no e2e world; unit specs and R272 wiring run in ci.yml
670
- tracked: tracked
671
- tier: none
672
- tests: none
673
- goesTo: "the full edition: a lite app has no e2e world; its unit specs and wiring proof run in .github/workflows/ci.yml; contract specs use test:contract"
674
- managedBy: ci-workflows
675
- rules: [HFS_CI_E2E_AUTOMATIC, HFS_MANAGED_FILE_DRIFT]
676
- - id: app.ci-images
677
- since: 3.1.0
678
- profiles: [app]
679
- editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite renders its image workflow; full renders images for its separately deployed services."
680
- # Builds every image of the app (one matrix entry per declared app, path-filtered), never pushes: rendered by starci app sync.
681
- path: ".github/workflows/images.yml"
682
- presence: required
683
- tracked: tracked
684
- tier: none
685
- tests: none
686
- managedBy: ci-workflows
687
- liteManagedBy: ci-workflows-lite
688
- rules: [HFS_MANAGED_FILE_DRIFT]
689
- - id: app.ci-db
690
- profiles: [app]
691
- exemplifiedBy:
692
- - packages/hfs/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml
693
- - {path: packages/hfs/src/hfs-release-provenance.spec.mjs, edition: full}
694
- editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite manages its database deploy workflow; full owns an optional provider-specific workflow."
695
- # The database deploy workflow: workflow_dispatch only (like app.ci-e2e); starci app sync renders it under the managed ci group.
696
- path: ".github/workflows/db-deploy.yml"
697
- presence: optional
698
- tracked: tracked
699
- tier: none
700
- tests: none
701
- liteManagedBy: ci-workflows-lite
702
- rules: [HFS_MANAGED_FILE_DRIFT]
703
- since: 2.1.0
704
- - id: app.ci-stack-deploy
705
- since: 3.3.0
706
- profiles: [app]
707
- editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): both editions deploy their images to a Docker Swarm stack through the same starci stack verbs; the workflow lists the images the app declares."
708
- # The Swarm stack deploy workflow: workflow_dispatch only (like app.ci-db); a thin file that calls `starci app stack`, rendered by starci app sync.
709
- path: ".github/workflows/stack-deploy.yml"
710
- presence: optional
711
- tracked: tracked
712
- tier: none
713
- tests: none
714
- managedBy: ci-workflows
715
- liteManagedBy: ci-workflows-lite
716
- rules: [HFS_MANAGED_FILE_DRIFT]
717
- - id: app.dockerignore
718
- since: 3.1.0
719
- profiles: [app]
720
- # The one build-context filter of every image (the context is the app root): rendered by starci app sync; it keeps secrets and build output out.
721
- path: .dockerignore
722
- presence: required
723
- tracked: tracked
724
- tier: none
725
- tests: none
726
- managedBy: docker-ignore
727
- rules: [HFS_MANAGED_FILE_DRIFT]
728
- - id: app.deploy
729
- since: 3.1.0
730
- profiles: [app]
731
- # Production delivery tooling for the app's own processes: compose files, Caddyfile, *.env.example and ops shell scripts.
732
- # Lite keeps its encrypted custody in app.starcistacks; R06 scans every file here.
733
- path: "deploy/"
734
- presence: optional
735
- tracked: tracked
736
- tier: none
737
- tests: none
738
- rules: [HFS_PLAINTEXT_SECRET]
739
- - id: app.ci-deploy
740
- since: 3.1.0
741
- profiles: [app]
742
- # Product-owned delivery workflows; the literal app.ci-db path remains the managed database workflow's more specific slot.
743
- path: ".github/workflows/<app>-deploy.yml"
744
- presence: optional
745
- tracked: tracked
746
- tier: none
747
- tests: none
748
- rules: [HFS_PLAINTEXT_SECRET]
749
- - id: app.ci-authorize-deploy-key
750
- since: 3.1.0
751
- profiles: [app]
752
- path: ".github/workflows/authorize-deploy-key.yml"
753
- presence: optional
754
- tracked: tracked
755
- tier: none
756
- tests: none
757
- rules: [HFS_PLAINTEXT_SECRET]
758
- - id: app.browser
759
- since: 3.1.0
760
- profiles: [app]
761
- editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): browser journeys belong to full; lite proves app boot through R272 wiring."
762
- # The browser journey of the product (Playwright, owner ruling: one minimal journey per example app, run manually): the config, its
763
- # journeys and the script that provisions the stack it runs against. It is the product's, never the front end's (FE_NO_TESTS keeps
764
- # refusing any test or test tooling inside fe/). Declared by `browser: true` in hfs.json; the managed script `test:browser` exists only then.
765
- path: "browser/"
766
- presence: opt-in
767
- litePresence: forbidden # a browser journey runs against a provisioned stack: e2e, which lite does not have
768
- goesTo: "the full edition: a lite app has no e2e world, so no browser journey"
769
- tracked: tracked
770
- tier: none
771
- tests: none
772
- requires: [playwright.config.ts, journeys/]
773
- allows: [playwright.config.ts, stack.mjs, "journeys/*.ts"]
774
- - id: app.browser-config
775
- since: 3.5.0
776
- profiles: [app]
777
- editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): browser journeys belong to full; lite proves app boot through R272 wiring."
778
- # The program that type-checks the browser journey: Playwright only transpiles the config and the journeys, so without it nothing
779
- # type-checks them and the op gate finds no tsconfig.json owning a changed journey (GATE_TSC_CONFIG_MISSING). It is managed (rendered
780
- # by starci app sync from templates/app/browser-config, extending @starci/tsconfig/e2e.json), never authored, and enabled with
781
- # app.browser by `browser: true` in hfs.json.
782
- path: browser/tsconfig.json
783
- presence: opt-in
784
- litePresence: forbidden
785
- goesTo: "the full edition: a lite app has no browser journey to type-check"
786
- tracked: tracked
787
- tier: none
788
- tests: none
789
- managedBy: browser-config
790
- rules: [HFS_MANAGED_FILE_DRIFT]
791
- - id: app.github-meta
792
- since: 3.1.0
793
- profiles: [app]
794
- path: ".github/{CODEOWNERS,pull_request_template.md,ISSUE_TEMPLATE/**}"
795
- presence: optional
796
- tracked: tracked
797
- tier: none
798
- tests: none
799
- - id: app.dependabot
800
- since: 3.2.0
801
- profiles: [app]
802
- path: .github/dependabot.yml
803
- presence: required
804
- tracked: tracked
805
- tier: none
806
- tests: none
807
- managedBy: skeleton
808
- liteManagedBy: skeleton-lite
809
- editionWhy: "Lite renders the same managed file from skeleton-lite because the editions share one code structure while their adapters differ (ruling:R212/case-2, with Work amended by ruling:R212/case-4 and hosting by owner:lite-production-swarm)."
810
- rules: [HFS_MANAGED_FILE_DRIFT, HFS_DEPENDABOT_MISSING]
811
- - id: app.scripts
812
- since: 3.1.0
813
- profiles: [app]
814
- exemplifiedBy:
815
- - {path: packages/hfs/templates/app/skeleton/scripts/codegen.mjs, edition: full}
816
- editionWhy: "Lite manages its database-types codegen script; full owns operational scripts through the generic path (ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4))."
817
- # The app's operational scripts only (`*.mjs`, `*.cjs`, `*.ps1`, `*.sh`), or nothing: an empty folder is `scripts/.gitkeep`, which
818
- # `starci app scaffold` writes. A spec or a test (BE_SPEC_PLACEMENT, FE_NO_TESTS), a check or lint source (`check-*`, `eslint-local-rules*`,
819
- # a local eslint plugin: HFS_REPO_LOCAL_CHECK) and anything that re-implements a canon check is not an operational script and has no place here.
820
- path: "scripts/{.gitkeep,*.mjs,*.cjs,*.ps1,*.sh}"
821
- presence: optional
822
- tracked: tracked
823
- tier: none
824
- tests: none
825
- lite:
826
- path: scripts/codegen.mjs
827
- liteManagedBy: codegen-lite
828
- rules: [HFS_SCRIPT_ONE_OFF, BE_SPEC_PLACEMENT, HFS_REPO_LOCAL_CHECK] # one-off codemods and fix-* scripts are agent output, not tooling
829
- - id: app.scripts.delivery
830
- since: 3.1.0
831
- profiles: [app]
832
- editionWhy: "Lite splits product delivery tooling from managed codegen; full owns the same files through app.scripts (ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4))."
833
- editions: [lite]
834
- # Product-owned environment, secret and build tooling, kept apart from lite's managed codegen script.
835
- # Full already owns these files through app.scripts; its generic *.mjs pattern must not compete with build-*.mjs.
836
- path: "scripts/{env-sync.mjs,with-secrets.mjs,set-secrets.ps1,build-*.mjs}"
837
- presence: optional
838
- tracked: tracked
839
- tier: none
840
- tests: none
841
- rules: [HFS_PLAINTEXT_SECRET, HFS_SCRIPT_ONE_OFF, BE_SPEC_PLACEMENT, HFS_REPO_LOCAL_CHECK]
842
- exemplifiedBy:
843
- - {path: packages/hfs/src/hfs-slot-ownership.spec.mjs, edition: lite}
844
- - id: app.scripts.integration
845
- since: 3.7.0
846
- profiles: [app]
847
- editionWhy: "Lite and full share the slot: a product's integration proof that needs a throwaway, unmigrated database has the same need in both editions, and lite's generic scripts path is closed to anything but codegen and delivery tooling."
848
- # Product test-support scripts, run only by the integration harness (the integration suites call them; no package script, workflow, hook
849
- # or deploy step does). A proof that must create a throwaway database that no migration has touched and run DDL on it keeps that work here,
850
- # because the back-end lint refuses runtime DDL and raw query text in test sources. The folder is `integration`, not `test`:
851
- # R252's script scan skips test folders, and a support script that creates databases must stay inside it. A spec or test is not a script
852
- # (BE_SPEC_PLACEMENT), a check or lint source has no place (HFS_REPO_LOCAL_CHECK), and a script that reaches a host other than the private
853
- # test stack is refused by its own connection guard, which the integration spec of the product proves.
854
- path: "scripts/integration/*.mjs"
855
- presence: optional
856
- tracked: tracked
857
- tier: none
858
- tests: none
859
- rules: [HFS_PLAINTEXT_SECRET, HFS_SCRIPT_ONE_OFF, BE_SPEC_PLACEMENT, HFS_REPO_LOCAL_CHECK]
860
- exemplifiedBy:
861
- - {path: packages/hfs/src/hfs-slot-ownership.spec.mjs, editions: [lite, full]}
862
- - id: app.packages
863
- since: 3.17.0
864
- profiles: [app]
865
- editionWhy: Lite and full share the slot; every root workspace package of a product (its agent SDK, a block library, a module package, a reviewed plugin package) is one in both.
866
- # A workspace package of the app ROOT (packages/<name>: the agent SDK, a block library, packages/module-<name>): first-party source that both sides import through its
867
- # package entry points and never past them (ARCH_INTERNAL_IMPORT_OUTSIDE), linted by the root eslint config by subpath.
868
- path: "packages/<name>/"
869
- presence: optional
870
- tracked: tracked
871
- tier: none
872
- requires: [package.json, tsconfig.json, src/index.ts]
873
- tests: unit-beside
874
- rules: [HFS_UNUSED_EXPORT]
875
- - id: app.module-registry
876
- since: 3.17.0
877
- profiles: [app]
878
- editionWhy: Lite and full share the slot; the registry lists the module packages of the app.
879
- path: packages/modules/
880
- presence: optional
881
- tracked: tracked
882
- tier: none
883
- requires: [package.json, src/index.ts]
884
- allows: [package.json, tsconfig.json, tsconfig.build.json, src/index.ts, src/template/index.ts, src/manifest/index.ts]
885
- tests: none
886
- rules: [HFS_MANAGED_FILE_DRIFT]
887
- - id: app.sides
888
- since: 3.1.0
889
- profiles: [app]
890
- # The two sides. Everything below be/ and fe/ is judged by the side's own slots (profiles be and fe) with the side folder as its root;
891
- # this slot answers only for the side folders themselves.
892
- path: "{be,fe}/"
893
- presence: required
894
- tracked: tracked
895
- tier: none
896
- tests: none
897
- - id: app.starciwork
898
- since: 3.1.0
899
- profiles: [app]
900
- exemplifiedBy:
901
- - {path: packages/hfs/templates/app/skeleton/.starciwork/, edition: full}
902
- - {path: packages/hfs/templates/app/skeleton-lite/.starciwork/, edition: lite}
903
- editionWhy: "ruling:R212/case-4: lite optionally keeps .gitignore, workspace.yaml and brand records; full keeps the Work catalog and product summaries."
904
- path: ".starciwork/"
905
- presence: required
906
- tracked: tracked
907
- tier: none
908
- tests: none
909
- requires: [.gitignore, workspace.yaml, index.yaml]
910
- allows: [workspace.yaml, index.yaml, "brand/**", shell/index.yaml, "features/<feature>/index.yaml",
911
- "features/<feature>/<family>/<name>/index.yaml", "features/<feature>/br/<rule>/ac/<name>/index.yaml",
912
- "features/<feature>/ui/<name>/assets/<approved-file>", "features/<feature>/uat/<name>/{index,accounts,fixtures}.yaml",
913
- "features/<feature>/uat/<name>/{seed,cleanup}.sql", "_resources/{identities,environments,fixtures}/<slug>/resource.yaml",
914
- "_derived/{index.yaml,frontier.md,critique.yaml,critique.md}"]
915
- forbids: [evidence/, logs/, reports/, captures/, runs/, "kernel-*/", "*.sqlite*"]
916
- # ruling:R212/case-4: lite keeps workspace.yaml for project identity and repo roles, plus brand drawing records,
917
- # references and assets. No brand means no Work tree is needed; workspace.yaml is legal but optional.
918
- litePresence: optional
919
- lite:
920
- requires: [.gitignore]
921
- allows: [workspace.yaml, "brand/**"]
922
- rules: [HFS_AGENT_DATA_TRACKED, HFS_IDENTITY_CUSTODY]
923
- - id: app.starcistacks
924
- since: 3.1.0
925
- profiles: [app]
926
- editionWhy: "owner:lite-production-swarm: lite requires declared docker-swarm production with its PostgreSQL as a stack service; owner:dev-docker-prod-swarm keeps dependencies in Docker Linux containers in dev and the app and dependencies on Swarm in prod."
927
- exemplifiedBy:
928
- - {path: packages/hfs/templates/app/skeleton/.starcistacks/, edition: full}
929
- - {path: packages/hfs/templates/app/skeleton-lite/.starcistacks/, edition: lite}
930
- # The stack declarations and the sealed custody of the app, at the app root beside be/, fe/ and .starciwork (never under a side).
931
- path: ".starcistacks/"
932
- presence: required
933
- tracked: tracked
934
- tier: none
935
- tests: none
936
- requires: [application-stacks.yaml]
937
- allows: [application-stacks.yaml, "<env>/README.md", "<env>/environment.json", "<env>/infra/{compose,swarm,k8s,terraform}/**", "<env>/infra/metadata.json",
938
- "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.enc", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
939
- forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
940
- # Owner ruling 2026-10-14: lite declares docker-swarm production, app runtime config, sealed custody and seed data.
941
- # The db service supplies the database; schedules are platform/jobs ticks (R335); production has no Compose or host cron.
942
- lite:
943
- requires: [application-stacks.yaml]
944
- allows: [application-stacks.yaml, images/db/Dockerfile, "<env>/README.md", "<env>/environment.json", "<env>/infra/swarm/**", "<env>/infra/metadata.json",
945
- "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.enc", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
946
- forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
947
- rules: [HFS_STACKS_SHAPE, HFS_STACKS_IN_SIDE, HFS_PLAINTEXT_SECRET, HFS_IDENTITY_CUSTODY]
948
- - id: app.sops
949
- since: 3.1.0
950
- profiles: [app]
951
- # The sops custody rule of .starcistacks/<env>/secrets/*.enc, at the app root beside the tree it seals.
952
- path: .sops.yaml
953
- presence: required
954
- tracked: tracked
955
- tier: none
956
- tests: none
957
- - id: app.build-output
958
- since: 3.1.0
959
- profiles: [app]
960
- path: "{**/node_modules/,coverage/,reports/,test-results/,**/*.tsbuildinfo}"
961
- presence: optional
962
- tracked: ignored
963
- tier: none
964
- tests: none
965
- - id: app.tool-cache
966
- since: 3.1.0
967
- profiles: [app]
968
- path: "{.eslintcache,.turbo/,.scannerwork/,.sonar/,.jest-cache/,.cache/,.tools/}"
969
- presence: forbidden
970
- tracked: external
971
- tier: none
972
- tests: none
973
- goesTo: "${STARCI_CACHE_HOME:-%LOCALAPPDATA%/StarCi/cache}/<repo>/<tool>/ (the canon presets set eslint --cache-location, jest cacheDirectory, turbo cacheDir, sonar.working.directory)"
974
- - id: app.agent-output
975
- since: 3.1.0
976
- profiles: [app]
977
- path: "{report*.json,*.tmp.json,%*%,nul,.artifacts/,.tmp-*,*-lint.json,lf.json,lt.json,*.log,design-plans/,.gitmounts/,.dat,vi-flat.txt}"
978
- presence: forbidden
979
- tracked: external
980
- tier: none
981
- tests: none
982
- goesTo: "agent scratchpad or the StarCi blob store (%LOCALAPPDATA%/StarCi/blobs), cited by {name, sha256}"
983
- rules: [HFS_UNTRACKED_ROOT_ENTRY, HFS_AGENT_DATA_TRACKED]
984
- - id: app.worktrees
985
- since: 3.1.0
986
- profiles: [app]
987
- path: "{.worktrees/,worktrees/,.starciwork/worktrees/}"
988
- presence: forbidden
989
- tracked: external
990
- tier: none
991
- tests: none
992
- goesTo: "<lanes root>/<project>/<lane>/ (outside every repository) for a lane; a Kernel workflow's worktree is created and owned by Orca outside the app checkout, never tracked, and removed by the runtime's host-side controller once the workflow's finish marked it release-pending"
993
- - id: app.plaintext-env
994
- since: 3.1.0
995
- profiles: [app]
996
- path: "{.env,.env.*,secrets.env,.secrets/,**/*.pem,**/*.key}"
997
- presence: forbidden
998
- tracked: external
999
- tier: none
1000
- tests: none
1001
- goesTo: ".starcistacks/<env>/secrets/<slug>.enc (at the app root); decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
1002
- rules: [HFS_PLAINTEXT_SECRET]
1003
-
1004
- # ----- app root: the database of a lite app (ruling:lite-self-hosted-postgres-passport-minio): a self-hosted PostgreSQL in the app's
1005
- # stack (the `db` service, built from the managed .starcistacks/images/db/Dockerfile: the official postgres image plus pgvector and pgmq, ruling:lite-db-image-in-stacks), migrated by
1006
- # `starci app db migrate --db-url-env <NAME>`. A full app keeps its TypeORM migrations under be/ and has no such folder.
1007
- - id: app.db
1008
- profiles: [app]
1009
- editions: [lite]
1010
- exemplifiedBy:
1011
- - packages/hfs/templates/app/skeleton-lite/db/
1012
- # The one database directory, at the app root beside be/, fe/ and .starcistacks (never under a side).
1013
- path: "db/"
1014
- presence: required
1015
- tracked: tracked
1016
- tier: none
1017
- tests: none
1018
- since: 3.9.0
1019
- - id: app.db.migrations
1020
- profiles: [app]
1021
- editions: [lite]
1022
- exemplifiedBy:
1023
- - packages/hfs/templates/app/skeleton-lite/db/migrations/__timestamp___baseline.sql
1024
- - {path: packages/hfs/src/db-migration-shape.spec.mjs, edition: lite}
1025
- # The schema authority of a lite app: forward-only SQL migrations named <timestamp14>_<kebab-name>.sql, one file per change,
1026
- # immutable once on origin/main, applied in order by `starci app db migrate` and recorded in the history table.
1027
- path: "db/migrations/<stamp>_<name>.sql"
1028
- presence: required
1029
- minInstances: 1
1030
- tracked: tracked
1031
- tier: none
1032
- tests: none
1033
- since: 3.9.0
1034
- rules: [DB_MIGRATION_SHAPE, LITE_DB_MIGRATION]
1035
- - id: app.db.migrations.archive
1036
- profiles: [app]
1037
- editions: [lite]
1038
- # The migrations an app retired at a baseline cutover: the live schema is dumped into ONE baseline migration, marked applied
1039
- # without a re-run, and the older files move here. `starci app db migrate` never applies this folder and no migration rule judges it.
1040
- path: "db/migrations/archive/"
1041
- presence: optional
1042
- tracked: tracked
1043
- tier: none
1044
- tests: none
1045
- since: 3.9.0
1046
- - id: app.db.seed
1047
- profiles: [app]
1048
- editions: [lite]
1049
- path: "db/seed.sql"
1050
- presence: optional # synthetic dev data only; a lite app seeds nothing it cannot regenerate
1051
- tracked: tracked
1052
- tier: none
1053
- tests: none
1054
- since: 3.9.0
1055
- - id: app.db.image
1056
- profiles: [app]
1057
- editions: [lite]
1058
- # The managed image of the db service (templates/app/db-image, rulings lite-official-postgres-image and lite-db-image-in-stacks): FROM
1059
- # the digest-pinned official postgres image plus postgresql-17-pgvector from PGDG and the sha256-verified pgmq release. It lives with
1060
- # the stacks; the stack's db service, the local db container, the scratch database of `starci app db drift` and the squash replay
1061
- # all build it.
1062
- path: ".starcistacks/images/db/Dockerfile"
1063
- presence: required
1064
- tracked: tracked
1065
- managedBy: db-image
1066
- tier: none
1067
- tests: none
1068
- since: 3.11.0
1069
- rules: [HFS_MANAGED_FILE_DRIFT]
1070
- - id: app.db.bootstrap
1071
- profiles: [app]
1072
- editions: [lite]
1073
- # The managed pre-migration bootstrap (templates/app/db-bootstrap): the auth and storage schemas, auth.users with the GoTrue column
1074
- # set, auth.uid/role/jwt stubs and the NOLOGIN browser roles, so migrations written for a hosted Supabase apply to the db service's
1075
- # official postgres image (nothing else of Supabase: no supabase_admin, extensions schema or realtime publication). `starci app db migrate` applies it before the first migration of an empty database.
1076
- path: "db/bootstrap.sql"
1077
- presence: required
1078
- tracked: tracked
1079
- managedBy: db-bootstrap
1080
- tier: none
1081
- tests: none
1082
- since: 3.9.0
1083
- rules: [HFS_MANAGED_FILE_DRIFT]
1084
-
1085
-
1086
- # ----- side root (both sides): what a standalone repository root holds, less the app-root files ----------
1087
- - id: repo.side-root-forbidden
1088
- since: 3.1.0
1089
- profiles: [be, fe]
1090
- path: "{package.json,package-lock.json,hfs.json,README.md,.gitignore,.gitattributes,.husky/,.github/,.starciwork/,.starcistacks/,db/,.sops.yaml,sonar-project.properties,codecov.yml,.prettierrc,.prettierignore,scripts/}"
1091
- presence: forbidden
1092
- tracked: external
1093
- tier: none
1094
- tests: none
1095
- goesTo: "the app root: one package.json, lockfile, hfs.json, README, git and CI files, hooks, formatter, Sonar and Codecov configuration, scripts/, .starciwork, .starcistacks and .sops.yaml per app"
1096
- - id: be.tool-config
1097
- since: 3.1.0
1098
- profiles: [be]
1099
- # Managed files (starci app sync renders them, starci app check compares them): the whole tool configuration of a back end. Each is
1100
- # a reference to a canon package, never a configuration: tsconfig.json extends @starci/tsconfig/be.json and adds the
1101
- # three path aliases and excludes the world, integration, e2e and contract trees (fixtures stay in the root program: unit
1102
- # specs import them); tsconfig.build.json puts an overlay preset after it and adds only the path-relative options a
1103
- # preset cannot hold; the tests' own src/tests/tsconfig.json (the nearest config of a world, integration, e2e or contract
1104
- # file, so typed lint and typecheck:tests both find it) extends it with the e2e preset; eslint.config.mjs is the
1105
- # one-line starciBeConfig call; jest.config.js calls the @starci/jest-preset factory (the root scripts run it with
1106
- # --config be/jest.config.js). The formatter configuration is the app's (app.format-config); every preset resolves from the
1107
- # app root node_modules.
1108
- path: "{tsconfig.json,tsconfig.build.json,src/tests/tsconfig.json,eslint.config.mjs,jest.config.js}"
1109
- presence: required
1110
- tracked: tracked
1111
- tier: none
1112
- tests: none
1113
- # Lite renders the same files (owner ruling 2026-10-12 (owner:lite-production-swarm), with the Work boundary amended by ruling:R212/case-4): the unit run and its coverage are full's.
1114
- coverage: none
1115
- managedBy: tool-config
1116
- rules: [HFS_MANAGED_FILE_DRIFT, HFS_TOOL_CONFIG_LOCAL, HFS_TS_STRICT]
1117
- - id: be.nest-cli
1118
- since: 3.1.0
1119
- profiles: [be]
1120
- # The Nest monorepo of the back end: `monorepo: true` and one project per declared be app (apps/<app>, even for one service).
1121
- path: nest-cli.json
1122
- presence: required
1123
- tracked: tracked
1124
- tier: none
1125
- tests: none
1126
- coverage: none
1127
- rules: [HFS_MONO_NEST_PROJECTS]
1128
- - id: be.tool-config-local
1129
- since: 3.1.0
1130
- profiles: [be]
1131
- path: "{.eslintrc,.eslintrc.*,.eslintignore,eslint.config.js,eslint.config.cjs,eslint.config.ts,eslint.config.mts,eslint.config.cts,.prettierrc.*,prettier.config.*,jest.config.ts,jest.config.mjs,jest.config.cjs,jest.config.json,jest.config.e2e.js}"
1132
- presence: forbidden
1133
- tracked: external
1134
- tier: none
1135
- tests: none
1136
- goesTo: "nowhere: a back end has exactly the managed tool configuration (be.tool-config); a change to a rule or a flag is proposed in the .claude runtime"
1137
- rules: [HFS_TOOL_CONFIG_LOCAL]
1138
- - id: fe.tool-config
1139
- since: 3.1.0
1140
- profiles: [fe]
1141
- # Managed files (starci app sync renders them, starci app check compares them): the tool configuration of a front end. Each is a
1142
- # reference to a canon package, never a configuration: tsconfig.json extends @starci/tsconfig/next.json and only
1143
- # names the preset and nothing else (each app's own tsconfig.json, in fe.app.next, carries its aliases and include; there is
1144
- # no test tsconfig: a front end has no tests, FE_NO_TESTS); eslint.config.mjs is the one-line starciFeConfig call;
1145
- # stylelint.config.mjs is the one-line starciStylelintConfig call. The formatter configuration is the app's (app.format-config).
1146
- # A front end has no test configuration at all (FE_NO_TESTS).
1147
- path: "{tsconfig.json,eslint.config.mjs,stylelint.config.mjs}"
1148
- presence: required
1149
- tracked: tracked
1150
- tier: none
1151
- tests: none
1152
- managedBy: tool-config
1153
- rules: [HFS_MANAGED_FILE_DRIFT, HFS_TOOL_CONFIG_LOCAL, HFS_RULE_OFF_WITHOUT_REPLACEMENT, HFS_TS_STRICT]
1154
- - id: fe.tool-config-local
1155
- since: 3.1.0
1156
- profiles: [fe]
1157
- path: "{.eslintrc,.eslintrc.*,.eslintignore,eslint.config.js,eslint.config.cjs,eslint.config.ts,eslint.config.mts,eslint.config.cts,.stylelintrc,.stylelintrc.*,.stylelintignore,stylelint.config.js,stylelint.config.cjs,stylelint.config.ts,stylelint.config.json,prettier.config.*,.prettierrc.*,lint-staged.config.*,.lintstagedrc*,turbo.json}"
1158
- presence: forbidden
1159
- tracked: external
1160
- tier: none
1161
- tests: none
1162
- goesTo: "nowhere: a front end has exactly the managed tool configuration (fe.tool-config); the task graph is the app root's turbo.json (app.task-graph); a change to a rule or a flag is proposed in the .claude runtime"
1163
- rules: [HFS_TOOL_CONFIG_LOCAL]
1164
- - id: repo.docs
1165
- since: 3.1.0
1166
- profiles: [be, fe]
1167
- path: "docs/{adr,runbooks,guides}/**/*.md"
1168
- presence: opt-in
1169
- tracked: tracked
1170
- tier: none
1171
- tests: none
1172
- coverage: none
1173
- rules: [HFS_ROOT_MARKDOWN_FORBIDDEN]
1174
- - id: repo.docs-media
1175
- since: 3.1.0
1176
- profiles: [be, fe]
1177
- path: "docs/**/*.{png,svg,webp}"
1178
- presence: opt-in
1179
- tracked: tracked
1180
- tier: none
1181
- tests: none
1182
- coverage: none
1183
- budget: {bytes: 512000}
1184
- - id: repo.i18n-dynamic-keys
1185
- since: 3.3.0
1186
- profiles: [be, fe]
1187
- # The side's authored ledger of catalog keys the R280 detector cannot see (fe/i18n-dynamic-keys.yaml, be/i18n-dynamic-keys.yaml:
1188
- # each side owns its own catalogs). A key it names counts as read; an entry matching no catalog key, or a malformed file, is itself an R280 finding.
1189
- path: i18n-dynamic-keys.yaml
1190
- presence: opt-in
1191
- tracked: tracked
1192
- tier: none
1193
- tests: none
1194
- coverage: none
1195
- rules: [HFS_UNUSED_SYMBOL]
1196
- exemplifiedBy:
1197
- - {path: packages/hfs/src/hfs-unused-symbol-ledger.spec.mjs, editions: [lite, full]}
1198
- - id: repo.packages
1199
- since: 3.1.0
1200
- profiles: [be, fe]
1201
- path: "packages/<pkg>/"
1202
- presence: opt-in
1203
- tracked: tracked
1204
- tier: package
1205
- owner: true
1206
- requires: [package.json, src/index.ts, tsconfig.json]
1207
- tests: unit-beside
1208
- coverage: none
1209
- rules: [FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT]
1210
- - id: repo.app-image
1211
- since: 3.1.0
1212
- profiles: [be, fe]
1213
- exemplifiedBy:
1214
- - packages/hfs/templates/be/image/api/Dockerfile
1215
- - packages/hfs/templates/be/image/cli/Dockerfile
1216
- - {path: packages/hfs/templates/be/image/worker/Dockerfile, edition: full}
1217
- - packages/hfs/templates/fe/image/next/Dockerfile
1218
- editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite may host Next without its own image; back-end images stay required in both editions."
1219
- # One image per app: every declared app has its own Dockerfile (apps/<app>/Dockerfile), built from the APP ROOT (the folder with
1220
- # the one package.json). It is app-owned (starci app scaffold writes it once from templates/<side>/image) and judged by the docker rules.
1221
- # A Dockerfile anywhere else is owned by no slot.
1222
- path: "apps/<app>/Dockerfile"
1223
- presence: required
1224
- litePresence: {fe: optional} # lite: a Next app may be built by its host (Netlify, Vercel); a be image stays required
1225
- tracked: tracked
1226
- tier: none
1227
- tests: none
1228
- coverage: none
1229
- rules: [HFS_DOCKER_BUILD_CONTEXT, HFS_DOCKER_STAGES, HFS_DOCKER_ENTRY, HFS_DOCKER_BASE_PIN, HFS_DOCKER_SECRETS]
1230
-
1231
- # ----- never tracked: build output the tools need in place ---------------------------------------------
1232
- - id: repo.build-output
1233
- since: 3.1.0
1234
- profiles: [be, fe]
1235
- path: "{**/node_modules/,dist/,apps/*/dist/,packages/*/dist/,.next/,apps/*/.next/,coverage/,reports/,test-results/,**/next-env.d.ts,**/*.tsbuildinfo}"
1236
- presence: optional
1237
- tracked: ignored
1238
- tier: none
1239
- tests: none
1240
- - id: repo.generated
1241
- since: 3.1.0
1242
- profiles: [be, fe]
1243
- path: "{**/__generated__/,apps/*/src/schema.gql}"
1244
- presence: optional
1245
- tracked: ignored
1246
- tier: none
1247
- tests: none
1248
- why: produced by `npm run codegen` (prebuild and pretypecheck); never committed
1249
-
1250
- # ----- never in the working tree: caches, scratch, agent output ----------------------------------------
1251
- - id: repo.tool-cache
1252
- since: 3.1.0
1253
- profiles: [be, fe]
1254
- path: "{.eslintcache,.turbo/,.scannerwork/,.sonar/,.jest-cache/,.cache/,.tools/}"
1255
- presence: forbidden
1256
- tracked: external
1257
- tier: none
1258
- tests: none
1259
- goesTo: "${STARCI_CACHE_HOME:-%LOCALAPPDATA%/StarCi/cache}/<repo>/<tool>/ (the canon presets set eslint --cache-location, jest cacheDirectory, turbo cacheDir, sonar.working.directory)"
1260
- - id: repo.agent-output
1261
- since: 3.1.0
1262
- profiles: [be, fe]
1263
- path: "{report*.json,*.tmp.json,%*%,nul,.artifacts/,.tmp-*,*-lint.json,lf.json,lt.json,*.log,design-plans/,.gitmounts/,.dat,vi-flat.txt}"
1264
- presence: forbidden
1265
- tracked: external
1266
- tier: none
1267
- tests: none
1268
- goesTo: "agent scratchpad or the StarCi blob store (%LOCALAPPDATA%/StarCi/blobs), cited by {name, sha256}"
1269
- rules: [HFS_UNTRACKED_ROOT_ENTRY, HFS_AGENT_DATA_TRACKED]
1270
- - id: repo.worktrees
1271
- since: 3.1.0
1272
- profiles: [be, fe]
1273
- path: "{.worktrees/,worktrees/,.starciwork/worktrees/}"
1274
- presence: forbidden
1275
- tracked: external
1276
- tier: none
1277
- tests: none
1278
- goesTo: "<lanes root>/<project>/<lane>/ (outside every repository)"
1279
- - id: repo.plaintext-env
1280
- since: 3.1.0
1281
- profiles: [be, fe]
1282
- path: "{.env,.env.*,.secrets/,**/*.pem,**/*.key}"
1283
- presence: forbidden
1284
- tracked: external
1285
- tier: none
1286
- tests: none
1287
- goesTo: ".starcistacks/<env>/secrets/<slug>.enc (at the app root); decrypted values only in memory or under %LOCALAPPDATA%/StarCi/secrets/<project>/<env>/ via *_FILE"
1288
- rules: [HFS_PLAINTEXT_SECRET]
1289
- - id: be.root-e2e
1290
- since: 3.1.0
1291
- profiles: [be]
1292
- path: "e2e/"
1293
- presence: forbidden
1294
- tracked: external
1295
- tier: none
1296
- tests: none
1297
- goesTo: "src/tests/e2e/ for specs; operational probes move to scripts/ or are deleted"
1298
-
1299
- # ----- contract snapshots (the committed machine-emitted files, because they are a cross-repo interface) --
1300
- - id: be.contract.graphql
1301
- since: 3.1.0
1302
- profiles: [be]
1303
- path: "contracts/<app>/schema.graphql"
1304
- presence: opt-in
1305
- tracked: tracked
1306
- tier: none
1307
- tests: none
1308
- coverage: none
1309
- why: emitted by `npm run contract:emit` (`starci app emit`, never written by hand); CI fails when the emitted file differs (a contract, not a build artefact)
1310
- rules: [HFS_CONTRACT_SNAPSHOT_DRIFT]
1311
- - id: be.contract.openapi
1312
- since: 3.1.0
1313
- profiles: [be]
1314
- path: "contracts/<app>/openapi.json"
1315
- presence: opt-in
1316
- tracked: tracked
1317
- tier: none
1318
- tests: none
1319
- coverage: none
1320
- why: emitted by `npm run contract:emit` (`starci app emit`, never written by hand) from the app's typed operation table `apps/<app>/src/operations.ts` (canon BE-OPERATIONS-1); CI fails when the emitted file differs
1321
- rules: [HFS_CONTRACT_SNAPSHOT_DRIFT]
1322
- - id: be.contract.events
1323
- since: 3.1.0
1324
- profiles: [be]
1325
- path: "contracts/<app>/events.json"
1326
- presence: opt-in
1327
- tracked: tracked
1328
- tier: none
1329
- tests: none
1330
- coverage: none
1331
- why: the async contract of a service (`starci/event-contract@1`), emitted by `npm run contract:emit` (`starci app emit`, never written by hand) from the typed event classes of `src/modules/events/<service>/`; the consumers of its events rely on it (R166 HFS_EVENT_CONTRACT)
1332
- rules: [HFS_EVENT_CONTRACT]
1333
- - id: be.contract.events.pin
1334
- since: 3.1.0
1335
- profiles: [be]
1336
- path: "contracts/<app>/events.pin.json"
1337
- presence: opt-in
1338
- tracked: tracked
1339
- tier: none
1340
- tests: none
1341
- coverage: none
1342
- why: the previously published event contract of a service, the same format as its events.json (copied over when the contract is published, never edited); the current events.json may only extend it additively, a breaking change is a new `<event>.v2` key (R177 BE_CONTRACT_BREAKING)
1343
- rules: [BE_CONTRACT_BREAKING]
1344
-
1345
- - id: be.contract.mcp-tools
1346
- since: 3.4.0
1347
- profiles: [be]
1348
- path: "contracts/<app>/<contract>.tools.json"
1349
- presence: opt-in
1350
- tracked: tracked
1351
- tier: none
1352
- tests: none
1353
- coverage: none
1354
- why: the MCP tool catalog an app's MCP server publishes at one contract major (`<server>@<major>`), the `tools/list` result its clients rely on, committed as a cross-repo interface; the canon emits no MCP catalog, so its shape is judged (R302 HFS_MCP_TOOLS_SNAPSHOT)
1355
- rules: [HFS_MCP_TOOLS_SNAPSHOT]
1356
- exemplifiedBy:
1357
- - {path: packages/hfs/src/mcp-tools-snapshot.spec.mjs, editions: [lite, full]}
1358
-
1359
- # ----- BE: apps (one slot per app kind; a new kind = a new slot, minor bump) ---------------------------
1360
- # The files of every app (owner ruling 2026-10-14, R245 and R246, since 3.1.0), each with a line budget (lines excluding
1361
- # import declarations, multi-line imports included) that BE_APP_COMPOSITION_BUDGET holds absolutely (not a ratchet):
1362
- # main.ts the entry: builds EnvSource once, imports and calls read<App>Env from <app>.env.ts, builds options and boots.
1363
- # <app>.env.ts exports interface <App>Env and read<App>Env(env: EnvSource): <App>Env (for example ApiEnv/readApiEnv);
1364
- # fail-fast environment parsing only, via EnvSource and unchanged capability parse helpers; no localhost
1365
- # or default host fallback, logic, module composition, business code or feature imports. Only main.ts
1366
- # and this app file may read process.env or EnvSource. The interface declares its own readonly parsed
1367
- # members with parser-derived types, structurally compatible with the app's options;
1368
- # the role name stays <app>.env.ts, never env.ts. Secrets use EnvSource.secret(): <NAME>_FILE first
1369
- # for .starcistacks custody, plain <NAME> only when the file key is absent. A declared file supplies
1370
- # exact contents; an empty or unreadable path stops boot without fallback.
1371
- # <app>.options.ts the options: env-derived options plus port bindings (provider maps such as { approvalGate: X }) only;
1372
- # no environment parsing or process.env/EnvSource reads; module, queue or scheduler composition here or in <app>.env.ts is
1373
- # BE_APP_OPTIONS_COMPOSITION.
1374
- # compose/<area>.ts a composition group: exports the module list of one area (an imports array, and the providers of the
1375
- # area's global ports when it has any); composition only, no business logic or process.env/EnvSource read.
1376
- # app.module.ts the composition root: imports the groups and spreads them, binds the app-wide guards and filter.
1377
- - id: be.app.api
1378
- since: 3.1.0
1379
- profiles: [be]
1380
- path: "apps/<app>/src/"
1381
- appKind: api
1382
- presence: required # at least one api app
1383
- tracked: tracked
1384
- tier: app
1385
- owner: true
1386
- minInstances: 1
1387
- requires: [main.ts, app.module.ts, "<app>.env.ts"]
1388
- allows: [main.ts, app.module.ts, "<app>.env.ts", "<app>.options.ts", "compose/<area>.ts", operations.ts]
1389
- tests: none # full app boot is proven by useTestWorld({ apps }); lite by starci app check --wiring (R272)
1390
- coverage: none
1391
- budget: {app.module.ts: 250, main.ts: 80, "<app>.env.ts": 150, "<app>.options.ts": 200, "compose/<area>.ts": 120}
1392
- rules: [BE_APP_COMPOSITION_ONLY, BE_APP_BUSINESS_ROLE, BE_APP_OPTIONS_COMPOSITION, BE_APP_COMPOSITION_BUDGET, BE_DEFAULT_DENY, BE_ERROR_MASKED, BE_FEATURE_NOT_COMPOSED, BE_CONTEXT_OWNER, BE_APP_ENV_REQUIRED]
1393
- - id: be.app.worker
1394
- since: 3.1.0
1395
- profiles: [be]
1396
- path: "apps/<app>/src/"
1397
- appKind: worker # composes transport/message modules and job processors only (an api app may compose them too: a worker app is for separate scaling)
1398
- presence: opt-in
1399
- tracked: tracked
1400
- tier: app
1401
- owner: true
1402
- requires: [main.ts, app.module.ts, "<app>.env.ts"]
1403
- allows: [main.ts, app.module.ts, "<app>.env.ts", "<app>.options.ts", "compose/<area>.ts"]
1404
- tests: none # full app boot is proven by useTestWorld({ apps }); lite by starci app check --wiring (R272)
1405
- coverage: none
1406
- budget: {app.module.ts: 250, main.ts: 80, "<app>.env.ts": 150, "<app>.options.ts": 200, "compose/<area>.ts": 120}
1407
- rules: [BE_APP_COMPOSITION_ONLY, BE_APP_OPTIONS_COMPOSITION, BE_APP_COMPOSITION_BUDGET, BE_BACKGROUND_UNOWNED, BE_CONTEXT_OWNER, BE_APP_ENV_REQUIRED]
1408
- - id: be.app.cli
1409
- since: 3.1.0
1410
- profiles: [be]
1411
- editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): `starci app db migrate` owns lite migrations; a lite cli app is optional for declared operator commands."
1412
- # The ONE app of every one-off action (migrate, seed, sync, backup, any operator command): be/apps/cli, on nest-commander.
1413
- # main.ts boots with CommandFactory.run (BE_CLI_BOOTSTRAP); app.module.ts composes the platform and the cli feature root
1414
- # (src/features/cli/cli.module.ts); cli.env.ts exports CliEnv and readCliEnv(env: EnvSource): CliEnv, and cli.options.ts carries the env-derived values,
1415
- # the connections it migrates among them (the test world migrates through the same list). It is required as soon as the
1416
- # back end declares a connection or tracks a command, with its image apps/cli/Dockerfile (BE_CLI_REQUIRED): one image,
1417
- # run as `cli <group> <command>`.
1418
- path: "apps/<app>/src/"
1419
- appKind: cli
1420
- presence: opt-in
1421
- litePresence: optional # lite: schema migration is `starci app db migrate`'s job; a cli app exists only when the app declares one
1422
- tracked: tracked
1423
- tier: app
1424
- owner: true
1425
- requires: [main.ts, app.module.ts, "<app>.env.ts"]
1426
- allows: [main.ts, app.module.ts, "<app>.env.ts", "<app>.options.ts", "compose/<area>.ts"]
1427
- tests: none # full app boot is proven by useTestWorld({ apps }); lite by starci app check --wiring (R272)
1428
- coverage: none
1429
- budget: {app.module.ts: 250, main.ts: 80, "<app>.env.ts": 150, "<app>.options.ts": 200, "compose/<area>.ts": 120}
1430
- rules: [BE_CLI_REQUIRED, BE_CLI_BOOTSTRAP, BE_CLI_OWNER, BE_SCHEMA_AUTHORITY, BE_APP_OPTIONS_COMPOSITION, BE_APP_COMPOSITION_BUDGET, BE_APP_ENV_REQUIRED]
1431
-
1432
- # ----- BE: features ------------------------------------------------------------------------------------
1433
- # src/features/ is grouped by TRIGGER KIND (owner decision 2026-10-02): features/api/<feature>/ (a request: application/ and
1434
- # transport/<protocol>/, composed by the api apps), features/cli/ (a one-off action: the cli feature root, compiled only into
1435
- # apps/cli). Every kind imports only downward into modules/*; no kind imports another.
1436
- - id: be.feature
1437
- since: 3.1.0
1438
- profiles: [be]
1439
- path: "src/features/api/<feature>/"
1440
- presence: required
1441
- trigger: api # a request-driven feature (graphql, http); the other trigger kinds have their own roots below
1442
- tracked: tracked
1443
- tier: feature
1444
- owner: true
1445
- minInstances: 1
1446
- requires: [index.ts, "<feature>.module.ts", application/]
1447
- allows: [index.ts, "<feature>.module.ts", "<feature>.module-definition.ts", "<feature>.options.ts", application/, transport/, messages/] # nothing else at feature root
1448
- tests: none
1449
- coverage: none
1450
- budget: {files: 250, indexExports: 60} # a feature above 250 source files must be split by product capability
1451
- rules: [BE_FEATURE_SHAPE, BE_FEATURE_IMPORTS_FEATURE, BE_PUBLIC_SURFACE, BE_FEATURE_NOT_COMPOSED]
1452
- - id: be.feature.application
1453
- since: 3.1.0
1454
- profiles: [be]
1455
- path: "src/features/{api/,jobs/,reactors/,saga/}<feature>/application/" # inside a trigger kind (jobs, reactors, saga) the feature folder is one level down
1456
- presence: required
1457
- tracked: tracked
1458
- tier: feature
1459
- allows: ["<action>.{command,query,handler,contracts}.ts"]
1460
- forbids: [graphql/, http/, message/, schedule/, transport/] # no protocol names under application/
1461
- tests: none
1462
- coverage: none
1463
- rules: [BE_APPLICATION_IMPORTS_TRANSPORT, BE_APPLICATION_TRANSPORT_FRAMEWORK, BE_ENTITY_IN_CONTRACT, BE_CQRS_SHAPE]
1464
- - id: be.feature.saga
1465
- since: 3.1.0
1466
- profiles: [be]
1467
- path: "src/features/saga/<saga>/"
1468
- pattern: saga # enabled by `patterns: ["saga"]` in hfs.json sides.be (R169 to R173); an undeclared saga folder is HFS_SLOT_NOT_ENABLED
1469
- presence: opt-in # a saga: the orchestrator of a business flow that crosses services, started and advanced only by events (knowledge/patterns/be/saga.yaml)
1470
- trigger: saga
1471
- tracked: tracked
1472
- tier: feature
1473
- owner: true
1474
- requires: [index.ts, "<saga>.module.ts", "<saga>.saga.service.ts", "<saga>.saga-state.ts", steps/, compensations/, transport/]
1475
- allows: [index.ts, "<saga>.module.ts", "<saga>.module-definition.ts", "<saga>.options.ts", "<saga>.saga.service.ts", "<saga>.saga.service.spec.ts", "<saga>.saga-state.ts", "<saga>.saga.log-events.ts", application/, steps/, compensations/, transport/] # the orchestrator is a `*.service.ts` because a handler injects only services; unit-tested beside it
1476
- tests: unit-beside # <saga>.saga.service.spec.ts beside the orchestrator; the state machine and its fence are platform/saga's service; each compensation path has an e2e spec
1477
- coverage: none
1478
- rules: [BE_KIND_ISOLATION, BE_FEATURE_IMPORTS_FEATURE, BE_FEATURE_NOT_COMPOSED, BE_SAGA_STEP_COMPENSATION, BE_SAGA_STATE_VERSIONED, BE_SAGA_EVENT_CONTRACT, BE_SAGA_E2E_MISSING]
1479
- - id: be.feature.saga.steps
1480
- since: 3.1.0
1481
- profiles: [be]
1482
- path: "src/features/saga/<saga>/steps/"
1483
- pattern: saga
1484
- presence: opt-in
1485
- tracked: tracked
1486
- tier: feature
1487
- allows: ["<step>.saga-step.ts"] # one step of the flow: its name and the event it puts on the wire (the contract); its work is done by the domain, not by the step
1488
- tests: none
1489
- coverage: none
1490
- rules: [BE_SAGA_STEP_COMPENSATION, BE_SAGA_EVENT_CONTRACT]
1491
- - id: be.feature.saga.compensations
1492
- since: 3.1.0
1493
- profiles: [be]
1494
- path: "src/features/saga/<saga>/compensations/"
1495
- pattern: saga
1496
- presence: opt-in
1497
- tracked: tracked
1498
- tier: feature
1499
- allows: ["<step>.compensation.ts"] # REQUIRED for every step: the command that undoes it, naming the failure event that triggers it
1500
- tests: none
1501
- coverage: none
1502
- rules: [BE_SAGA_STEP_COMPENSATION, BE_SAGA_EVENT_CONTRACT, BE_SAGA_E2E_MISSING]
1503
- - id: be.feature.application.support
1504
- profiles: [be]
1505
- path: "src/features/{api/,jobs/,reactors/,saga/}<feature>/application/support/"
1506
- presence: optional # helpers and types local to ONE feature; same tier as application, never a shared home
1507
- tracked: tracked
1508
- tier: feature # feature tier: another feature cannot import it (features never import features)
1509
- allows: ["<name>.<role>.ts"] # <role> from ruleParams.be.suffixes; no <name>.types.ts
1510
- forbids: [graphql/, http/, message/, schedule/, transport/]
1511
- tests: none
1512
- coverage: none
1513
- rules: [BE_APPLICATION_IMPORTS_TRANSPORT, BE_APPLICATION_TRANSPORT_FRAMEWORK, BE_FEATURE_IMPORTS_FEATURE]
1514
- since: 1.0.0
1515
- - id: be.transport.http
1516
- since: 3.1.0
1517
- profiles: [be]
1518
- path: "src/features/api/<feature>/transport/http/"
1519
- presence: optional
1520
- tracked: tracked
1521
- tier: feature
1522
- requires: ["<feature>-http.module.ts"]
1523
- allows: ["<action>.controller.ts", "dto/<action>.{request,response}.ts", "<action>.mapper.ts", "<feature>-http.module-definition.ts", "<feature>-http.options.ts"]
1524
- tests: none
1525
- coverage: none
1526
- composedBy: [api]
1527
- rules: [BE_DEFAULT_DENY, BE_INPUT_BOUNDED, BE_TRANSPORT_SHAPE]
1528
- - id: be.transport.graphql
1529
- since: 3.1.0
1530
- profiles: [be]
1531
- path: "src/features/api/<feature>/transport/graphql/"
1532
- presence: optional
1533
- tracked: tracked
1534
- tier: feature
1535
- requires: ["<feature>-graphql.module.ts"]
1536
- allows: ["<action>.resolver.ts", "dto/<action>.{input,type,args}.ts", "<action>.mapper.ts", "<feature>-graphql.module-definition.ts", "<feature>-graphql.options.ts"]
1537
- tests: none
1538
- coverage: none
1539
- composedBy: [api]
1540
- rules: [BE_DEFAULT_DENY, BE_INPUT_BOUNDED, BE_TRANSPORT_SHAPE]
1541
- - id: be.transport.message
1542
- since: 3.1.0
1543
- profiles: [be]
1544
- path: "src/features/{api/,reactors/,saga/}<feature>/transport/message/"
1545
- presence: opt-in # queue consumer: composed by the service that owns it (an api app) or by a worker app scaled apart
1546
- pattern: event-bus # a consumer reads the event bus; declaring the pattern enables the slot
1547
- tracked: tracked
1548
- tier: feature
1549
- requires: ["<feature>-message.module.ts"]
1550
- allows: ["<event>.consumer.ts", "<feature>-message.module-definition.ts", "<feature>-message.options.ts"] # BE-CONVENTION 1.6: transport/message holds only consumers; a .message.ts is outside the closed suffix list
1551
- tests: none
1552
- coverage: none
1553
- composedBy: [api, worker]
1554
- rules: [BE_BACKGROUND_UNOWNED, BE_SAGA_CONSUMER_DEDUPE]
1555
- # ----- BE: feature kinds that are not an api: a webhook door and a realtime door. Each kind is a folder of src/features/ named by
1556
- # the kind and holds one folder per provider or channel; a kind imports only modules/* (never another kind) and only an
1557
- # api-kind app composes it. Their doors answer to the same door laws as every transport (default deny, bounded input,
1558
- # no envelope), plus the kind laws of knowledge/patterns/be/webhooks.yaml and realtime.yaml.
1559
- - id: be.feature.webhooks
1560
- profiles: [be]
1561
- path: "src/features/webhooks/<provider>/"
1562
- presence: opt-in # a provider webhook intake: verifies the signature and replay window, then hands the delivery to ONE domain intake method
1563
- pattern: webhooks # declaring the pattern (hfs.json sides.be.patterns) enables the kind (knowledge/patterns/be/webhooks.yaml)
1564
- trigger: webhooks
1565
- tracked: tracked
1566
- tier: feature
1567
- owner: true
1568
- requires: [index.ts, transport/]
1569
- allows: [index.ts, transport/]
1570
- tests: none
1571
- coverage: none
1572
- rules: [BE_KIND_ISOLATION, BE_FEATURE_IMPORTS_FEATURE, BE_FEATURE_NOT_COMPOSED]
1573
- since: 1.0.0
1574
- - id: be.feature.webhooks.http
1575
- profiles: [be]
1576
- path: "src/features/webhooks/<provider>/transport/http/"
1577
- presence: opt-in # the one door of the provider: its module, the signed webhook and the door's own spec
1578
- pattern: webhooks
1579
- tracked: tracked
1580
- tier: feature
1581
- requires: ["<provider>-http.module.ts", "<provider>.webhook.ts", "<provider>.webhook.spec.ts"]
1582
- allows: ["<provider>-http.module.ts", "<provider>-http.module-definition.ts", "<provider>-http.options.ts", "<provider>.webhook.ts", "<provider>.webhook.spec.ts", dto/]
1583
- tests: unit-beside # the door's own spec (<provider>.webhook.spec.ts) beside the door: the one non-service unit spec of this kind
1584
- coverage: none
1585
- composedBy: [api]
1586
- rules: [BE_WEBHOOK_SHAPE, BE_WEBHOOK_UNVERIFIED, BE_DEFAULT_DENY, BE_INPUT_BOUNDED]
1587
- since: 1.0.0
1588
- - id: be.feature.webhooks.dto
1589
- profiles: [be]
1590
- path: "src/features/webhooks/<provider>/transport/http/dto/"
1591
- presence: opt-in
1592
- pattern: webhooks
1593
- tracked: tracked
1594
- tier: feature
1595
- allows: ["<event>.request.ts"] # the typed provider payload, validated and bounded (BE_INPUT_BOUNDED)
1596
- tests: none
1597
- coverage: none
1598
- composedBy: [api]
1599
- rules: [BE_INPUT_BOUNDED]
1600
- since: 1.0.0
1601
- - id: be.feature.realtime
1602
- profiles: [be]
1603
- editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4) and ruling:R212/case-5 (owner decision 2026-10-24): both editions serve server-sent events (the default door for one-way push), the socket.io gateway (two-way) and the restricted GraphQL subscription (ruling:R212/case-7) from the api process (owner:lite-graphql-subscription-door), and scale on the hub of their declared infrastructure (BE-REALTIME-7)."
1604
- path: "src/features/realtime/<channel>/"
1605
- presence: opt-in # a push channel: reads and pushes only (an SSE controller, a socket gateway or a GraphQL subscription), no domain write
1606
- pattern: realtime # declaring the pattern (hfs.json sides.be.patterns) enables the kind (knowledge/patterns/be/realtime.yaml)
1607
- trigger: realtime
1608
- tracked: tracked
1609
- tier: feature
1610
- owner: true
1611
- requires: [index.ts, transport/]
1612
- allows: [index.ts, transport/]
1613
- tests: none
1614
- lite:
1615
- why: >-
1616
- a push channel with the three doors of both editions: server-sent events (be.feature.realtime.sse, the default for one-way push, owner decision 2026-10-24), the socket.io gateway (two-way, owner ruling 2026-10-13) and the restricted GraphQL subscription (ruling:R212/case-7); all run inside the be api process, which scales horizontally and stateless
1617
- on the hub of its declared infrastructure; the front end listens through a useSubscribe<Channel>Swr hook over modules/api/sse, or hooks/socketio (knowledge/patterns/be/realtime.yaml, liteAdapter)
1618
- coverage: none
1619
- rules: [BE_KIND_ISOLATION, BE_FEATURE_IMPORTS_FEATURE, BE_FEATURE_NOT_COMPOSED]
1620
- since: 1.0.0
1621
- exemplifiedBy:
1622
- - {path: packages/hfs/src/hfs-stacks-swarm.spec.mjs, edition: lite}
1623
- - id: be.feature.realtime.graphql
1624
- profiles: [be]
1625
- path: "src/features/realtime/<channel>/transport/graphql/"
1626
- presence: opt-in # a GraphQL subscription over graphql-ws, served in both editions (ruling:R212/case-7) and restricted: only when the client already uses GraphQL and needs the typed schema payload (knowledge/patterns/be/realtime.yaml)
1627
- pattern: realtime
1628
- tracked: tracked
1629
- tier: feature
1630
- requires: ["<channel>-graphql.module.ts", "<channel>.subscription.ts", "<channel>.subscription.spec.ts"]
1631
- allows: ["<channel>-graphql.module.ts", "<channel>-graphql.module-definition.ts", "<channel>-graphql.options.ts", "<channel>.subscription.ts", "<channel>.subscription.spec.ts", dto/]
1632
- tests: unit-beside # the door's own spec beside the door (a subscription has no service of its own)
1633
- coverage: none
1634
- composedBy: [api]
1635
- rules: [BE_REALTIME_SHAPE, BE_REALTIME_WRITES, BE_REALTIME_TOPIC_SCOPE, BE_DEFAULT_DENY]
1636
- since: 1.0.0
1637
- - id: be.feature.realtime.dto
1638
- profiles: [be]
1639
- path: "src/features/realtime/<channel>/transport/graphql/dto/"
1640
- presence: opt-in
1641
- pattern: realtime
1642
- tracked: tracked
1643
- tier: feature
1644
- allows: ["<name>.{input,type,args}.ts"]
1645
- tests: none
1646
- coverage: none
1647
- composedBy: [api]
1648
- rules: [BE_INPUT_BOUNDED]
1649
- since: 1.0.0
1650
- - id: be.feature.realtime.websocket
1651
- profiles: [be]
1652
- path: "src/features/realtime/<channel>/transport/websocket/"
1653
- presence: opt-in # a socket.io gateway; lite runs it in the api process (owner ruling 2026-10-13)
1654
- pattern: realtime
1655
- tracked: tracked
1656
- tier: feature
1657
- requires: ["<channel>-websocket.module.ts", "<channel>.gateway.ts", "<channel>.gateway.spec.ts"]
1658
- allows: ["<channel>-websocket.module.ts", "<channel>-websocket.module-definition.ts", "<channel>-websocket.options.ts", "<channel>.gateway.ts", "<channel>.gateway.spec.ts"]
1659
- tests: unit-beside # the door's own spec beside the door (a gateway has no service of its own)
1660
- coverage: none
1661
- composedBy: [api]
1662
- rules: [BE_REALTIME_SHAPE, BE_REALTIME_WRITES, BE_REALTIME_TOPIC_SCOPE, BE_DEFAULT_DENY]
1663
- since: 1.0.0
1664
- - id: be.feature.realtime.sse
1665
- since: 3.6.0
1666
- profiles: [be]
1667
- path: "src/features/realtime/<channel>/transport/sse/"
1668
- presence: opt-in # a server-sent-events door: one @Sse method, the default door for one-way push (owner decision 2026-10-24), served in both editions
1669
- pattern: realtime
1670
- tracked: tracked
1671
- tier: feature
1672
- requires: ["<channel>-sse.module.ts", "<channel>.controller.ts", "<channel>.controller.spec.ts"]
1673
- allows: ["<channel>-sse.module.ts", "<channel>-sse.module-definition.ts", "<channel>-sse.options.ts", "<channel>.controller.ts", "<channel>.controller.spec.ts"]
1674
- tests: unit-beside # the door's own spec beside the door (an SSE controller has no service of its own)
1675
- coverage: none
1676
- composedBy: [api]
1677
- rules: [BE_REALTIME_SHAPE, BE_REALTIME_WRITES, BE_REALTIME_TOPIC_SCOPE, BE_DEFAULT_DENY, BE_REST_DOOR_EVIDENCE]
1678
- exemplifiedBy:
1679
- - {path: packages/eslint/be/webhooks-realtime-coverage.spec.mjs, editions: [lite, full]}
1680
- - id: be.cli
1681
- since: 3.1.0
1682
- profiles: [be]
1683
- # The cli feature root: every one-off action of the back end, compiled only into apps/cli. A group is a nest-commander
1684
- # @Command (<group>/<group>.cli.ts) whose sub-commands are @SubCommand classes extending CommandRunner
1685
- # (<group>/subs/<name>.cli.ts), each with its unit spec beside it (<name>.cli.spec.ts): a command is an action runner, not a
1686
- # thin transport (BE_CLI_COMMAND_SHAPE). `.cli.ts` because `.command.ts` is the CQRS message (HFS delta 3). Every module of
1687
- # the root has a module definition beside it (ruling:module-definition-everywhere) and no register override: cli.module.ts imports each
1688
- # group module as <Group>Module.register({}), a group module provides its commands, and a command takes its inputs from a platform capability (the connections and their opener
1689
- # from platform/database) or from a command-line @Option.
1690
- path: "src/features/cli/"
1691
- presence: optional
1692
- trigger: cli # the one cli feature root: a one-off action never imports a feature of another kind (BE_KIND_ISOLATION)
1693
- tracked: tracked
1694
- tier: feature
1695
- owner: true
1696
- requires: [index.ts, cli.module.ts]
1697
- # A composed root: an app of kind cli lists cli.module.ts, never a group module (BE_MODULE_SHAPE).
1698
- composedBy: [cli]
1699
- allows: [index.ts, cli.module.ts, "cli.module-definition.ts", "cli.options.ts", "<group>/<group>.cli.ts", "<group>/<group>.cli.spec.ts", "<group>/<group>.module.ts", "<group>/<group>.module-definition.ts", "<group>/<group>.options.ts", "<group>/subs/<name>.cli.ts", "<group>/subs/<name>.cli.spec.ts"]
1700
- tests: unit-beside
1701
- coverage: none
1702
- rules: [BE_CLI_COMMAND_SHAPE, BE_CLI_OWNER, BE_CLI_REQUIRED, BE_MODULE_SHAPE, BE_SCHEMA_AUTHORITY]
1703
-
1704
- - id: be.assets
1705
- profiles: [be]
1706
- # Small binary assets bundled with the build (fonts a renderer embeds, a watermark): one folder per kind (owner ruling
1707
- # 2026-10-13, HFS assets policy). Large or user media (music, video, uploads) live in object storage and are fetched at runtime;
1708
- # templates and copy are TS constants in the owning capability (*.templates.ts). There is no be/resources/.
1709
- path: "src/assets/<kind>/"
1710
- presence: optional
1711
- tracked: tracked
1712
- tier: none
1713
- tests: none
1714
- coverage: none
1715
- since: 3.0.0
1716
- rules: [HFS_ASSET_OVERSIZE, HFS_ASSET_KIND]
1717
-
1718
- # ----- BE: modules (three tiers, closed set) -----------------------------------------------------------
1719
- - id: be.domain
1720
- since: 3.1.0
1721
- profiles: [be]
1722
- path: "src/modules/domain/<capability>/"
1723
- presence: optional
1724
- tracked: tracked
1725
- tier: domain
1726
- owner: true
1727
- requires: [index.ts]
1728
- # <name>.templates.ts holds the capability's static templates, copy and presets as TS constants (owner ruling 2026-10-13);
1729
- # user-editable ones are seed rows, large or user media live in object storage.
1730
- allows: ["<capability>.module.ts", "<capability>.module-definition.ts", "<capability>.config.ts", "<capability>.options.ts", errors/, messages/, persistence/, policies/, "*.service.ts", "*.service.spec.ts", "*.contracts.ts", "*.templates.ts", "*.schema.ts", "*.schema.spec.ts", "*.policy.ts", "*.policy.spec.ts"]
1731
- forbids: [testing/, exceptions/, utils/, helpers/, shared/]
1732
- tests: unit-beside # <name>.service.spec.ts beside each <name>.service.ts, nothing else
1733
- coverage: required
1734
- budget: {indexExports: 60}
1735
- rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_PUBLIC_SURFACE, BE_ERROR_HOME, BE_CONFIG_OWNER, BE_CONTEXT_COUPLING, BE_CONTEXT_TRANSACTION]
1736
- - id: be.errors
1737
- since: 3.1.0
1738
- profiles: [be]
1739
- path: "src/modules/{domain,integrations}/<capability>/errors/"
1740
- presence: optional
1741
- tracked: tracked
1742
- tier: inherit
1743
- allows: ["<capability>.error.ts", "<name>.error.ts"] # one family per capability, extends platform/errors DomainError
1744
- tests: none
1745
- coverage: none
1746
- rules: [BE_ERROR_HOME]
1747
- - id: be.domain.messages
1748
- profiles: [be]
1749
- path: "src/modules/{domain,platform,integrations}/<capability>/messages/"
1750
- presence: optional # a capability (any tier) that raises no user-facing text carries none
1751
- tracked: tracked
1752
- tier: inherit
1753
- allows: ["<capability>.messages.ts"] # one keyed catalog per capability, vi and en, read through the platform/i18n MessageCatalog port
1754
- tests: none
1755
- coverage: none
1756
- rules: [BE_USER_COPY_LITERAL]
1757
- since: 1.0.0
1758
- - id: be.feature.messages
1759
- profiles: [be]
1760
- path: "src/features/api/<feature>/messages/"
1761
- presence: optional
1762
- tracked: tracked
1763
- tier: feature
1764
- allows: ["<feature>.messages.ts"] # one keyed catalog per feature, vi and en, read through the platform/i18n MessageCatalog port
1765
- tests: none
1766
- coverage: none
1767
- rules: [BE_USER_COPY_LITERAL]
1768
- since: 1.0.0
1769
- - id: be.persistence
1770
- since: 3.1.0
1771
- profiles: [be]
1772
- editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): db/migrations own lite tables and both editions map them with TypeORM entities here (ruling:lite-persistence-typeorm-entities); full also keeps its TypeORM migrations here."
1773
- path: "src/modules/{domain,platform,projections}/<capability>/persistence/"
1774
- # R178: the platform capabilities whose tables exist on EVERY connection that uses them (the event-bus outbox, the inbox of every service, the job table); their arrays may be
1775
- # registered on several declared connections. Any other capability registers its arrays on exactly one (BE_SCHEMA_OWNER).
1776
- perConnection: [event-bus, inbox, jobs]
1777
- presence: optional
1778
- tracked: tracked
1779
- tier: inherit
1780
- requires: [connection.ts] # the capability's <c>Entities / <c>Migrations arrays (the owner index re-exports the two arrays by name); no CONNECTION alias: the connection is the one the apps register the arrays on
1781
- allows: ["entities/<table>.entity.ts", "migrations/<epochMs13>-<kebab-name>.ts", "<name>.sql.ts", "<name>.rows.ts", connection.ts]
1782
- forbids: [index.ts, "<name>.repository.ts"]
1783
- # Lite maps its tables with the same TypeORM entities as full (ruling:lite-persistence-typeorm-entities): each capability's
1784
- # persistence/entities/<table>.entity.ts and an entities/index.ts exporting its <c>Entities array, which platform/database
1785
- # lists by name; the schema authority stays db/migrations (ruleParams.be.lite.schemaAuthority), so no be migration and no
1786
- # raw SQL file (R334 BE_PERSISTENCE_NO_RAW_SQL).
1787
- lite:
1788
- requires: []
1789
- allows: ["entities/<table>.entity.ts", entities/index.ts, connection.ts]
1790
- forbids: [index.ts, "<name>.repository.ts", migrations/, "<name>.sql.ts", "<name>.rows.ts"]
1791
- tests: none
1792
- coverage: none
1793
- rules: [BE_SCHEMA_OWNER, BE_SCHEMA_AUTHORITY, BE_SQL_OUTSIDE_PERSISTENCE, BE_PERSISTENCE_NO_RAW_SQL, BE_SQL_TABLE_OWNER, BE_SQL_RETURNING_SHAPE, BE_CONTEXT_COUPLING, BE_CONTEXT_PLATFORM_TABLES]
1794
- - id: be.platform
1795
- since: 3.1.0
1796
- profiles: [be]
1797
- path: "src/modules/platform/<capability>/"
1798
- presence: required
1799
- tracked: tracked
1800
- tier: platform
1801
- owner: true
1802
- # config = EnvSource reader only; logging = LoggerPort + adapter; errors = DomainError base + one filter + GraphQL
1803
- # formatError with masking; primitives = isRecord, hashing, ids, cookies; clock = the injected Clock port
1804
- # (now()), with a FakeClock test double from @starci/jest-preset; i18n = the MessageCatalog port, a keyed
1805
- # lookup with named interpolation over the vi/en catalogs a capability or feature carries in its messages/,
1806
- # resolved through the RequestLocale provider (request: stored user preference, else Accept-Language, else
1807
- # vi; non-request: recipient's stored preference, else vi - see knowledge/patterns/be/messages.yaml);
1808
- # database when a connection exists.
1809
- requiredInstances: {capability: [config, errors, primitives, clock, i18n]}
1810
- requires: [index.ts]
1811
- forbids: [common/, utils/, shared/, testing/] # primitives live in platform/primitives
1812
- tests: unit-beside # <name>.service.spec.ts beside each <name>.service.ts, nothing else
1813
- coverage: required
1814
- budget: {indexExports: 60}
1815
- rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE]
1816
- - id: be.platform.database.entities
1817
- since: 3.10.0
1818
- profiles: [be]
1819
- editions: [lite]
1820
- 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."
1821
- path: "src/modules/platform/database/entities.ts"
1822
- presence: optional
1823
- tracked: tracked
1824
- tier: inherit
1825
- role: entity-registry
1826
- importedBy: ["apps/*/src/compose/*.ts", "apps/*/src/app.module.ts", "src/tests/world/**"]
1827
- tests: none
1828
- coverage: none
1829
- 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"
1830
- rules: [BE_TIER_DIRECTION, BE_PUBLIC_SURFACE, BE_SCHEMA_OWNER]
1831
- - id: be.platform.logging
1832
- since: 3.5.0
1833
- profiles: [be]
1834
- path: "src/modules/platform/logging/"
1835
- presence: required
1836
- pattern: logging
1837
- tracked: tracked
1838
- tier: platform
1839
- owner: true
1840
- requires: [index.ts]
1841
- forbids: [common/, utils/, shared/, testing/]
1842
- tests: unit-beside
1843
- coverage: required
1844
- budget: {indexExports: 60}
1845
- rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE]
1846
- # ----- BE: pattern slots (opt-in; enabled by hfs.json sides.be.patterns). A path under one is HFS_SLOT_NOT_ENABLED unless its pattern is declared.
1847
- - id: be.platform.event-bus
1848
- since: 3.1.0
1849
- profiles: [be]
1850
- editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite implements the event ports on pgmq (ruling:lite-pgmq-bus-bullmq-jobs); full uses its Kafka adapter."
1851
- path: "src/modules/platform/event-bus/"
1852
- presence: opt-in
1853
- pattern: event-bus # the ONE durable event transport: transactional outbox, relay, Kafka, inbox, retry and dead letter (knowledge/patterns/be/event-bus.yaml)
1854
- tracked: tracked
1855
- tier: platform
1856
- owner: true
1857
- lite:
1858
- why: >-
1859
- the EventBus and EventConsumer ports on pgmq (ruling:lite-pgmq-bus-bullmq-jobs): publish sends the envelope to its
1860
- topic in the publisher's transaction, so no outbox or relay runs; each consumer group reads its own queue bound to the
1861
- event's name with a visibility timeout, archives a handled message, lets a failed one reappear and buries one past its
1862
- maxDeliveries in its __dead queue (BE-EVENT-BUS-6). Jobs stay on BullMQ (platform/queue). No Kafka (knowledge/patterns/be/event-bus.yaml liteAdapter)
1863
- requires: [index.ts, event-bus.module.ts, event-bus.port.ts, event-bus.contracts.ts, event-bus.service.ts, event-bus.service.spec.ts]
1864
- tests: unit-beside
1865
- coverage: required
1866
- budget: {indexExports: 60}
1867
- rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE, BE_INFRA_OWNER]
1868
- exemplifiedBy:
1869
- - {path: packages/eslint/be/webhook-handoff-inbox.spec.mjs, edition: lite}
1870
- - id: be.platform.queue
1871
- since: 3.1.0
1872
- profiles: [be]
1873
- editionWhy: "ruling:R212/case-10: both editions implement the queue ports with BullMQ on Redis; lite declares its Redis in hfs.json sides.be.backing and keeps the outbox table in a db migration."
1874
- path: "src/modules/platform/queue/"
1875
- presence: opt-in
1876
- pattern: queue # the ONE BullMQ owner: the outbox relay into queues (jobId = outbox id) and job schedulers (knowledge/patterns/be/queues.yaml)
1877
- tracked: tracked
1878
- tier: platform
1879
- owner: true
1880
- lite:
1881
- why: >-
1882
- the same QueueOutbox and QueueWorkerRegistry ports and full's BullMQ adapter on the declared Redis (backing: [redis]): the
1883
- relay adds each committed outbox row with the outbox id as the job id, workers retry with exponential backoff and keep a
1884
- job that exhausts its attempts as failed (the dead letter); the outbox table comes from a db migration, and a
1885
- schedule is a BullMQ job scheduler or a platform/jobs tick that writes one outbox row, R335 (knowledge/patterns/be/queues.yaml liteAdapter)
1886
- requires: [index.ts, queue.module.ts, queue.port.ts, queue.contracts.ts, queue-outbox.service.ts, queue-outbox.service.spec.ts]
1887
- tests: unit-beside
1888
- coverage: required
1889
- budget: {indexExports: 60}
1890
- rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE, BE_INFRA_OWNER]
1891
- - id: be.events
1892
- since: 3.1.0
1893
- profiles: [be]
1894
- path: "src/modules/events/<service>/"
1895
- presence: opt-in
1896
- pattern: event-bus # typed event classes of one service; each equals an entry of be/contracts/<service>/events.json
1897
- tracked: tracked
1898
- tier: events
1899
- owner: true
1900
- requires: [index.ts]
1901
- allows: ["<event>.event.ts", index.ts]
1902
- tests: none
1903
- coverage: none
1904
- rules: [BE_EVENT_CLASS_CONTRACT, BE_TIER_DIRECTION]
1905
- - id: be.queues
1906
- since: 3.1.0
1907
- profiles: [be]
1908
- path: "src/modules/queues/<queue>/"
1909
- presence: opt-in
1910
- pattern: queue # a typed producer of one queue: enqueueX(payload, tx) writes the outbox; its schedulers live beside it
1911
- tracked: tracked
1912
- tier: queues
1913
- owner: true
1914
- requires: [index.ts, "<queue>.queue.ts"] # the module exists when a domain module imports the producer; a scheduler-only queue has none
1915
- allows: ["<queue>.queue.ts", "<queue>.module.ts", "<queue>.module-definition.ts", "<queue>.options.ts", "<queue>.contracts.ts", index.ts]
1916
- tests: none
1917
- coverage: none
1918
- rules: [BE_OUTBOX_WRITE_TX, BE_TIER_DIRECTION]
1919
- - id: be.feature.reactors
1920
- since: 3.1.0
1921
- profiles: [be]
1922
- path: "src/features/reactors/<reactor>/"
1923
- presence: opt-in
1924
- pattern: event-bus # a reactor consumes events of another context and keeps a local copy or triggers a projection
1925
- trigger: reactors
1926
- tracked: tracked
1927
- tier: feature
1928
- owner: true
1929
- requires: [index.ts, "<reactor>.module.ts", transport/]
1930
- allows: [index.ts, "<reactor>.module.ts", "<reactor>.module-definition.ts", "<reactor>.options.ts", application/, transport/]
1931
- tests: none
1932
- coverage: none
1933
- rules: [BE_KIND_ISOLATION, BE_FEATURE_IMPORTS_FEATURE, BE_FEATURE_NOT_COMPOSED]
1934
- - id: be.feature.jobs
1935
- since: 3.1.0
1936
- profiles: [be]
1937
- path: "src/features/jobs/<job>/"
1938
- presence: opt-in
1939
- pattern: fenced-job # a background job: a processor with a fenced claim, steps and the application it dispatches to
1940
- trigger: jobs
1941
- tracked: tracked
1942
- tier: feature
1943
- owner: true
1944
- requires: [index.ts, "<job>.module.ts", steps/, transport/]
1945
- allows: [index.ts, "<job>.module.ts", "<job>.module-definition.ts", "<job>.options.ts", application/, steps/, transport/]
1946
- tests: none
1947
- coverage: none
1948
- rules: [BE_KIND_ISOLATION, BE_FEATURE_IMPORTS_FEATURE, BE_FEATURE_NOT_COMPOSED]
1949
- - id: be.feature.jobs.queue
1950
- since: 3.1.0
1951
- profiles: [be]
1952
- path: "src/features/jobs/<job>/transport/queue/"
1953
- presence: opt-in # the queue transport of the job: its module and the processor the job runner hands the fenced claim to
1954
- pattern: fenced-job
1955
- tracked: tracked
1956
- tier: feature
1957
- requires: ["<job>-queue.module.ts", "<job>.processor.ts"]
1958
- allows: ["<job>-queue.module.ts", "<job>-queue.module-definition.ts", "<job>-queue.options.ts", "<job>.processor.ts"]
1959
- tests: none
1960
- coverage: none
1961
- composedBy: [api, worker]
1962
- rules: [BE_BACKGROUND_UNOWNED]
1963
- - id: be.feature.jobs.steps
1964
- since: 3.1.0
1965
- profiles: [be]
1966
- path: "src/features/jobs/<job>/steps/"
1967
- presence: opt-in
1968
- pattern: fenced-job # one external effect per step; it takes the claimed job and writes through the guarded methods
1969
- tracked: tracked
1970
- tier: feature
1971
- allows: ["<step>.step.ts"]
1972
- tests: none
1973
- coverage: none
1974
- rules: [BE_JOB_SHAPE, BE_JOB_RUN_KEY]
1975
- - id: be.platform.jobs
1976
- since: 3.1.0
1977
- profiles: [be]
1978
- editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite persists fenced claims in db migrations and dispatches through the BullMQ queue on its declared Redis (ruling:R212/case-10); full uses TypeORM schema authority and the same queue adapter."
1979
- path: "src/modules/platform/jobs/"
1980
- presence: opt-in
1981
- pattern: fenced-job # the ONE fencing primitive: the job entity, the claim that bumps the token, guarded writes (knowledge/patterns/be/jobs.yaml)
1982
- tracked: tracked
1983
- tier: platform
1984
- owner: true
1985
- requires: [index.ts, jobs.module.ts, jobs.port.ts, jobs.contracts.ts, job-claim.service.ts, job-claim.service.spec.ts, fenced.processor.ts]
1986
- tests: unit-beside
1987
- coverage: required
1988
- budget: {indexExports: 60}
1989
- rules: [BE_TIER_DIRECTION, ARCH_OWNER_CYCLE, BE_MODULE_SHAPE, BE_JOB_WRITE_OUTSIDE_OWNER, BE_JOB_FENCE_REQUIRED]
1990
- - id: be.projections
1991
- since: 3.1.0
1992
- profiles: [be]
1993
- editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite projection tables live in db migrations; full keeps the TypeORM projection entity beside its projection."
1994
- path: "src/modules/projections/<name>/"
1995
- presence: opt-in
1996
- pattern: projection # a read model: only its projection writes its table; recompute is idempotent and replayable; readers use get*
1997
- tracked: tracked
1998
- tier: projections
1999
- owner: true
2000
- requires: [index.ts, "<name>.module.ts", "<name>.projection.ts", "<name>.projection-entity.ts"]
2001
- allows: [index.ts, "<name>.module.ts", "<name>.module-definition.ts", "<name>.options.ts", "<name>.projection.ts", "<name>.projection-entity.ts", "<name>.contracts.ts", persistence/]
2002
- lite: # the read model's table is a db migration (lite's schema authority) mapped by its entity under persistence/entities/ (R334)
2003
- requires: [index.ts, "<name>.module.ts", "<name>.projection.ts"]
2004
- allows: [index.ts, "<name>.module.ts", "<name>.module-definition.ts", "<name>.options.ts", "<name>.projection.ts", "<name>.contracts.ts", persistence/]
2005
- tests: unit-beside # a measured slot: <name>.projection.spec.ts beside its projection is legal (the file owes 100 per file; a spec of its own is optional)
2006
- coverage: required
2007
- rules: [BE_PROJECTION_WRITE_OWNER, BE_PROJECTION_SHAPE, BE_TIER_DIRECTION, BE_CONTEXT_COUPLING]
2008
- exemplifiedBy:
2009
- - {path: packages/eslint/be/jobs-projections-coverage.spec.mjs, edition: lite}
2010
- - id: be.integrations
2011
- since: 3.1.0
2012
- profiles: [be]
2013
- path: "src/modules/integrations/<provider>/"
2014
- presence: optional
2015
- tracked: tracked
2016
- tier: integrations
2017
- owner: true
2018
- requires: [index.ts, "<provider>.config.ts"]
2019
- tests: unit-beside # <name>.service.spec.ts beside each <name>.service.ts; plus src/tests/integration/<provider>/ (R112)
2020
- coverage: required
2021
- budget: {indexExports: 80} # a provider's port surface includes clients, config, options, tokens and errors
2022
- rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING, BE_AI_KEY_CUSTODY, BE_AI_GATEWAY_CLIENT, BE_AI_VIRTUAL_KEY]
2023
- - id: be.integrations.model
2024
- since: 3.1.0
2025
- profiles: [be]
2026
- path: "src/modules/integrations/<provider>/model/"
2027
- presence: opt-in
2028
- tracked: tracked
2029
- tier: integrations
2030
- tests: none
2031
- coverage: required
2032
- why: a self-hosted ML model client is an integration; weights and datasets are never in git, and a language model is called through the ai-router gateway by the integrations/ai LangChain client (BE-AI-1, BE-AI-3)
2033
- rules: [BE_TIER_DIRECTION, BE_INFRA_OWNER, BE_INTEGRATION_SPEC_MISSING]
2034
-
2035
- - id: be.integrations.passport
2036
- profiles: [be]
2037
- editions: [lite]
2038
- exemplifiedBy:
2039
- - packages/hfs/templates/be/skeleton-lite/src/modules/integrations/passport/
2040
- # The glue of @starci/auth, the lite sign-in package (Google OAuth with state and PKCE, email and password, EdDSA access tokens with
2041
- # their JWKS, rotating refresh sessions): the one importer of the package (ruleParams.be.infraOwners), which owns the identity
2042
- # libraries (@nestjs/passport, passport, passport-google-oauth20, passport-local, @nestjs/jwt, jose, bcryptjs) that no app imports.
2043
- # It parses the typed options, builds the verifier and names the injectors; domain/identity verifies a token through the kit and
2044
- # builds the principal (contexts/code/be/api-auth.md).
2045
- path: "src/modules/integrations/passport/"
2046
- presence: required
2047
- tracked: tracked
2048
- tier: integrations
2049
- owner: true
2050
- requires: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.module-definition.ts, passport.module.ts] # Secrets, no defaults (R44); options and named injectors (R83); the kit and the module over @starci/auth
2051
- allows: [index.ts, passport.config.ts, passport.options.ts, passport.decorators.ts, passport.kit.ts, passport.module-definition.ts, passport.module.ts, errors/]
2052
- logic: [passport.kit.ts] # the verifier mapping over the package: measured at 100 per file
2053
- tests: unit-beside
2054
- rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_AUTH_PASSPORT_OWNER, BE_AUTH_JWT_OWN_JWKS, BE_AUTH_REFRESH_COOKIE]
2055
- coverage: required
2056
- since: 3.9.0
2057
- - id: be.identity.sign-in
2058
- since: 3.16.0
2059
- profiles: [be]
2060
- editions: [lite]
2061
- 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."
2062
- # 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.
2063
- 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}"
2064
- presence: optional
2065
- tracked: tracked
2066
- tier: inherit
2067
- tests: unit-beside
2068
- coverage: none
2069
- managedBy: auth-lite
2070
- managedOnly: true # lists files sync renders; the slot owning the path judges them
2071
- rules: [HFS_MANAGED_FILE_DRIFT]
2072
- - id: be.feature.auth
2073
- since: 3.16.0
2074
- profiles: [be]
2075
- editions: [lite]
2076
- 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."
2077
- # 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.
2078
- 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}"
2079
- presence: optional
2080
- tracked: tracked
2081
- tier: inherit
2082
- tests: none
2083
- coverage: none
2084
- managedBy: auth-lite
2085
- managedOnly: true # lists files sync renders; the slot owning the path judges them
2086
- rules: [HFS_MANAGED_FILE_DRIFT]
2087
- - id: be.integrations.mail
2088
- profiles: [be]
2089
- editions: [lite]
2090
- exemplifiedBy:
2091
- - packages/hfs/templates/be/skeleton-lite/src/modules/integrations/mail/
2092
- # The glue of @starci/mail, the owner of the SMTP client (nodemailer): this folder parses the settings (the server, the sender and the
2093
- # link lifetimes of the confirmation and reset mails), registers the module and names the injectors; no app file imports nodemailer,
2094
- # and no other module imports the package. The words and layout of each mail belong to the domain that sends it.
2095
- path: "src/modules/integrations/mail/"
2096
- presence: required
2097
- tracked: tracked
2098
- tier: integrations
2099
- owner: true
2100
- requires: [index.ts, mail.config.ts, mail.options.ts, mail.decorators.ts, mail.module-definition.ts, mail.module.ts]
2101
- allows: [index.ts, mail.config.ts, mail.options.ts, mail.decorators.ts, mail.module-definition.ts, mail.module.ts, errors/]
2102
- tests: unit-beside
2103
- rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER]
2104
- coverage: required
2105
- since: 5.3.0
2106
- - id: be.integrations.object-storage
2107
- profiles: [be]
2108
- exemplifiedBy:
2109
- - packages/hfs/templates/be/skeleton-lite/src/modules/integrations/object-storage/
2110
- # The glue of @starci/object-storage, the owner of the S3 client (@aws-sdk/client-s3 and @aws-sdk/s3-request-presigner) over
2111
- # S3-compatible storage (MinIO in lite): this folder keeps the bucket, parses the settings and registers the module; no app
2112
- # file imports an S3 SDK or minio, and no other module imports the package.
2113
- path: "src/modules/integrations/object-storage/"
2114
- presence: optional
2115
- litePresence: required
2116
- tracked: tracked
2117
- tier: integrations
2118
- owner: true
2119
- requires: [index.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.module-definition.ts, object-storage.module.ts]
2120
- allows: [index.ts, object-storage.config.ts, object-storage.options.ts, object-storage.decorators.ts, object-storage.module-definition.ts, object-storage.module.ts, errors/]
2121
- tests: unit-beside
2122
- rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_STORAGE_OWNER]
2123
- coverage: required
2124
- since: 3.9.0
2125
- - id: be.integrations.keycloak
2126
- profiles: [be]
2127
- editions: [full]
2128
- # The glue of @starci/auth-oidc, the OIDC client of the full edition's identity provider (Keycloak): discovery, the provider's JWKS,
2129
- # algorithm-pinned token checks and the authorization code flow with PKCE and nonce behind the PrincipalVerifier of @starci/auth.
2130
- # This folder parses the typed options, hands the package the app's bounded HTTP client and clock, and names the injectors;
2131
- # no app file imports jose, and no other module imports the package (ruleParams.be.infraOwners).
2132
- path: "src/modules/integrations/keycloak/"
2133
- presence: optional
2134
- tracked: tracked
2135
- tier: integrations
2136
- owner: true
2137
- requires: [index.ts, keycloak.config.ts, keycloak.options.ts, keycloak.decorators.ts, keycloak.registration.ts]
2138
- allows: [index.ts, keycloak.config.ts, keycloak.options.ts, keycloak.decorators.ts, keycloak.registration.ts, errors/, messages/]
2139
- tests: unit-beside
2140
- rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INFRA_OWNER, BE_AUTH_PASSPORT_OWNER, BE_INTEGRATION_SPEC_MISSING]
2141
- coverage: required
2142
- since: 3.17.0
2143
-
2144
-
2145
- # ----- BE: tests (owner test layout 2026-09-30). Unit specs are <name>.service.spec.ts beside their service and nothing else; everything else
2146
- # lives under src/tests/, one folder per kind, and the folder and the file suffix always agree (a file whose suffix does
2147
- # not match its folder matches no slot: HFS_SLOT_UNDECLARED).
2148
- - id: be.tests.world
2149
- since: 3.1.0
2150
- profiles: [be]
2151
- editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite integration proofs use the local db service and network fakes; full also boots apps and self-hosted services."
2152
- path: "src/tests/world/"
2153
- presence: optional
2154
- tracked: tracked
2155
- tier: e2e
2156
- lite:
2157
- why: >-
2158
- the world of the optional integration specs of a lite app: global-setup.ts connects to the local db service
2159
- (`npm run db:start`, with the migrations applied by `npm run db:push`) and starts no container, no toxiproxy and no stack of its
2160
- own; use-test-world.ts exports useTestWorld({ modules: [...] }) -> world.db.<connection> (the shared EntityManager) and
2161
- world.fake.<provider> (a network-edge fake of an external SaaS). There is no world.apps (no e2e) and no world.infra
2162
- (no self-hosted service to cut)
2163
- allows: [global-setup.ts, global-teardown.ts, use-test-world.ts, "fakes/<provider>/server.ts", fakes/, "<name>.sql.ts"] # jest globalSetup/globalTeardown default-export (Jest API); fakes/<provider>/server.ts is the fake server of a provider, a literal file name BE_SOURCE_FORM reads as its role; plus root files with a role suffix (test-world-files, R47)
2164
- tests: none
2165
- coverage: none
2166
- why: >-
2167
- the ONLY test infrastructure location, shared by integration and e2e: global-setup.ts starts the shared
2168
- infrastructure (containers) and runs the migrations once over the cli app's connections; use-test-world.ts exports
2169
- useTestWorld({ apps: { <name>: { module, listen? } } } | { modules: [...] }) -> world.apps.<name>.api,
2170
- world.db.<connection> (the shared EntityManager), world.infra.<service> (latency/cut/restore on a REAL service of the repository's
2171
- own stack, the app root's `.starcistacks/<env>`, each behind toxiproxy), world.fake.<provider> (a network-edge fake of an external SaaS started by the world, with
2172
- failNext/replayWebhook/delay), world.waitFor; fakes/<provider>/ holds the fake servers and payload fixtures, kit/ the inlined test helpers, and the world root may hold role-suffixed helpers (<name>.client.ts, <name>.contracts.ts, ...). Nothing is
2173
- overridden in the DI container. It is the only test location that may import typeorm's DataSource or testcontainers,
2174
- call migrate/runMigrations/synchronize, or write process.env.
2175
- rules: [BE_TEST_TOPOLOGY, BE_TEST_CONSTRAINTS_ON]
2176
-
2177
- - id: be.tests.world.kit
2178
- since: 3.1.0
2179
- profiles: [be]
2180
- path: "src/tests/world/kit/"
2181
- presence: optional
2182
- tracked: tracked
2183
- tier: e2e
2184
- allows: ["<name>.ts"] # plain kebab names, like platform/primitives (BE-CONVENTION 1.11 names primitives/time.ts): the world's inlined test helpers (poll, free-ports)
2185
- tests: none
2186
- coverage: none
2187
- why: the helpers the test world needs (polling, free ports, transports), inlined so the world imports no other repository; a bare <name>.ts entry in allows is what admits a plain name in BE_SOURCE_FORM
2188
- - id: be.tests.fixtures
2189
- since: 3.1.0
2190
- profiles: [be]
2191
- path: "src/tests/fixtures/"
2192
- presence: optional
2193
- tracked: tracked
2194
- tier: fixtures
2195
- allows: [i18n/] # i18n/ is the one folder that may carry localized text
2196
- tests: none
2197
- coverage: none
2198
- why: payload fixtures with a role suffix (the doubles come from @starci/jest-preset, not from here); the test data builders live in its builders/ slot; importable by unit specs, integration and e2e; never imports a feature
2199
- - id: be.tests.fixtures.builders
2200
- since: 3.1.0
2201
- profiles: [be]
2202
- path: "src/tests/fixtures/builders/*.builder.ts"
2203
- presence: optional
2204
- tracked: tracked
2205
- tier: fixtures
2206
- tests: none
2207
- coverage: none
2208
- why: >-
2209
- the ONLY home of test data builders, one <area>.builder.ts per area, shared by every spec of that area: pure object builders
2210
- (commissionRow(overrides), accrueInput(overrides)) for unit specs and persisting builders (orderBuilder(world.db.primary).pending().build(overrides))
2211
- for integration and e2e; arrange only, constraints on, deterministic defaults. A .builder.ts anywhere else, and a *.repository.ts,
2212
- *.fixture.ts or *.factory.ts anywhere, is a BE_SOURCE_FORM finding
2213
- rules: [BE_SOURCE_FORM]
2214
- - id: be.tests.fixtures.i18n
2215
- since: 3.1.0
2216
- profiles: [be]
2217
- path: "src/tests/fixtures/i18n/"
2218
- presence: optional
2219
- tracked: tracked
2220
- tier: fixtures
2221
- allows: ["<name>.<role>.ts"] # data files that deliberately carry localized text (a real Vietnamese string a parser or formatter must accept); no specs here
2222
- tests: none
2223
- coverage: none
2224
- why: the ONLY test-fixture location where Vietnamese or another language may appear in source (LANG_NOT_ENGLISH); placement is the marker, there is no comment pragma
2225
- - id: be.tests.integration
2226
- since: 3.1.0
2227
- profiles: [be]
2228
- editionWhy: "Lite integration specs use the local db service without containers or toxiproxy (ruling:R212/case-1, amended by ruling:R212/case-2 (owner:lite-production-swarm) and ruling:R212/case-4, with contracts allowed by owner:lite-contract-specs); R284 requires declared-pattern proofs there. Full additionally proves infrastructure outages through its world (R112)."
2229
- path: "src/tests/integration/<capability>/*.integration-spec.ts"
2230
- presence: optional
2231
- tracked: tracked
2232
- tier: e2e
2233
- tests: e2e
2234
- coverage: none
2235
- lite:
2236
- why: >-
2237
- optional under lite: one capability module through useTestWorld({ modules }) against the local db service
2238
- (`npm run db:start`), run by test:integration; no container, no toxiproxy and no outage through the world (R112 is full's)
2239
- why: one capability module through useTestWorld({ modules }), no HTTP door of ours (SQL, transactions, concurrency, inbox claims on the real database; and every integration client, `<capability>` being its provider folder, against our real infra, a real peer app or the library fake at the network edge, with its success, its ErrorCode refusal mapping and an outage through the world, R112); run by test:integration
2240
- rules: [BE_TEST_TOPOLOGY, BE_INTEGRATION_SPEC_MISSING]
2241
- - id: be.tests.e2e
2242
- since: 3.1.0
2243
- profiles: [be]
2244
- editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): full proves app flows through its e2e world; lite uses the R272 wiring proof and unit/integration specs."
2245
- path: "src/tests/e2e/<area>/*.e2e-spec.ts"
2246
- presence: optional
2247
- litePresence: forbidden # ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite has no e2e world
2248
- tracked: tracked
2249
- tier: e2e
2250
- tests: e2e
2251
- goesTo: "the full edition: a lite app has no e2e world; its logic is proven by unit specs and its database by optional integration specs on `npm run db:start`"
2252
- coverage: none
2253
- why: flow e2e through useTestWorld({ apps }); external services are the world's network fakes; run by test:e2e
2254
- rules: [HFS_CI_E2E_AUTOMATIC, BE_TEST_TOPOLOGY, BE_E2E_FLOW]
2255
- - id: be.tests.contract
2256
- since: 3.1.0
2257
- profiles: [be]
2258
- path: "src/tests/contract/<provider>/*.contract-spec.ts"
2259
- presence: optional
2260
- litePresence: optional # owner decision 2026-10-14: lite may run provider sandbox contracts
2261
- tracked: tracked
2262
- tier: e2e
2263
- tests: e2e
2264
- goesTo: "src/tests/contract/<provider>/*.contract-spec.ts in either edition: optional provider sandbox specs via test:contract; e2e stays full-only"
2265
- coverage: none
2266
- why: provider sandbox contracts, skipped without sandbox config; run only by test:contract, never part of test or test:e2e
2267
- rules: [BE_TEST_TOPOLOGY]
2268
- - id: be.tests.e2e-world-dir
2269
- since: 3.1.0
2270
- profiles: [be]
2271
- path: "src/tests/e2e/world/"
2272
- presence: forbidden
2273
- tracked: external
2274
- tier: none
2275
- tests: none
2276
- goesTo: "src/tests/world/ (the only test infrastructure location; e2e/<area>/ holds only *.e2e-spec.ts)"
2277
-
2278
- # ----- FE: apps ----------------------------------------------------------------------------------------
2279
- - id: fe.app.next
2280
- since: 3.1.0
2281
- profiles: [fe]
2282
- # Each fe app is an npm workspace: its package.json is @<project>/<app> with its own runtime dependencies and the fixed
2283
- # workspace scripts (HFS_MONO_FE_WORKSPACE); turbo runs them.
2284
- path: "apps/<app>/{package.json,next.config.ts,tsconfig.json,postcss.config.mjs}"
2285
- appKind: next
2286
- presence: required
2287
- tracked: tracked
2288
- tier: none
2289
- minInstances: 1
2290
- requires: [package.json, next.config.ts, tsconfig.json, postcss.config.mjs, src/app/, src/modules/i18n/,
2291
- "src/app/global-error.tsx", "src/app/[locale]/layout.tsx", "src/app/[locale]/error.tsx", "src/app/[locale]/not-found.tsx", "src/app/[locale]/loading.tsx"]
2292
- tests: none
2293
- rules: [FE_APP_ISOLATION, FE_ERROR_BOUNDARY_MISSING, FE_NEXT_CONVENTIONS, HFS_MONO_FE_WORKSPACE, HFS_MONO_WORKSPACE_DEP]
2294
- - id: fe.app-optional
2295
- since: 3.1.0
2296
- profiles: [fe]
2297
- path: "apps/<app>/public/"
2298
- presence: optional
2299
- tracked: tracked
2300
- tier: none
2301
- tests: none
2302
- - id: fe.route
2303
- since: 3.1.0
2304
- profiles: [fe]
2305
- path: "apps/<app>/src/app/"
2306
- presence: required
2307
- tracked: tracked
2308
- tier: route
2309
- # ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4) (lite = full): routes are thin and the front end serves no API - health/live is the one
2310
- # route handler of this slot, the OAuth callback is a back-end door, and no file holds a Server Action
2311
- # (FE_ROUTE_HANDLER_FORBIDDEN, FE_SERVER_ACTION_FORBIDDEN).
2312
- allows: ["[locale]/**/{page,layout,template,loading,error,not-found,default}.tsx", "[locale]/providers.tsx",
2313
- global-error.tsx, page.tsx, # the root page.tsx only redirects (FE_ROUTE_FILES_THIN)
2314
- not-found.tsx, layout.tsx, # next-intl: a request outside every locale renders the root not-found inside a root layout
2315
- health/live/route.ts, "_*/**", providers.tsx, globals.css,
2316
- "{icon,favicon,apple-icon,opengraph-image,twitter-image}.*", robots.ts, sitemap.ts, manifest.ts]
2317
- # providers.tsx (root or [locale]) is the client wrapper the server layout renders around its children to host context providers.
2318
- roles: {page: page.tsx, layout: layout.tsx, template: template.tsx, loading: loading.tsx, error: error.tsx, not-found: not-found.tsx, default: default.tsx, route: route.ts, global-error: global-error.tsx, providers: providers.tsx}
2319
- tests: none
2320
- rules: [FE_ROUTE_FILES_THIN, FE_CLIENT_BOUNDARY, FE_OWNER_REACHABLE, FE_ROUTE_HANDLER_FORBIDDEN, FE_SERVER_ACTION_FORBIDDEN]
2321
- - id: fe.source-root-pinned
2322
- since: 3.1.0
2323
- profiles: [fe]
2324
- path: "apps/<app>/src/{proxy.ts,instrumentation.ts,instrumentation-client.ts,sentry.server.config.ts,sentry.edge.config.ts}"
2325
- presence: optional
2326
- tracked: tracked
2327
- tier: route
2328
- roles: {proxy: proxy.ts, instrumentation: instrumentation.ts, instrumentation-client: instrumentation-client.ts, sentry: "sentry.*.config.ts"}
2329
- tests: none
2330
- rules: [FE_NEXT_CONVENTIONS] # middleware.ts is refused on Next >= 16 (fe.source-root-middleware)
2331
- - id: fe.source-root-middleware
2332
- since: 3.1.0
2333
- profiles: [fe]
2334
- path: "apps/<app>/src/{middleware.ts,middleware.js}"
2335
- presence: forbidden
2336
- tracked: external
2337
- tier: none
2338
- tests: none
2339
- goesTo: "apps/<app>/src/proxy.ts: Next >= 16 reads proxy.ts and refuses middleware.ts"
2340
- rules: [FE_NEXT_CONVENTIONS]
2341
- - id: fe.feature
2342
- since: 3.1.0
2343
- profiles: [fe]
2344
- path: "apps/<app>/src/features/{pages,layouts,overlays}/<name>/"
2345
- presence: required
2346
- tracked: tracked
2347
- tier: feature
2348
- owner: true
2349
- kinds: [pages, layouts, overlays]
2350
- requires: [index.tsx]
2351
- allows: [index.tsx, component.tsx, classNames.ts]
2352
- roles: {entry: index.tsx, drawing: component.tsx, styles: classNames.ts} # the connected entry, the pure drawing half and the styling declarations of a component owner
2353
- tests: none
2354
- budget: {component.tsx: 300, index.tsx: 200, dataHooks: 6, useState: 6}
2355
- rules: [FE_SIZE_BUDGET, FE_OWNER_REACHABLE, FE_I18N_LITERAL]
2356
- - id: fe.components
2357
- since: 3.1.0
2358
- profiles: [fe]
2359
- path: "apps/<app>/src/components/{blocks,frames,composites,branches,leaves}/<name>/"
2360
- presence: optional
2361
- tracked: tracked
2362
- tier: components
2363
- owner: true
2364
- layers: [blocks, frames, composites, branches, leaves] # a layer imports only the layers after it
2365
- requires: [index.tsx]
2366
- allows: [index.tsx, component.tsx, classNames.ts]
2367
- roles: {entry: index.tsx, drawing: component.tsx, styles: classNames.ts} # the connected entry, the pure drawing half and the styling declarations of a component owner
2368
- tests: none
2369
- budget: {component.tsx: 300, index.tsx: 200, dataHooks: 6, useState: 6}
2370
- rules: [FE_CONNECTED_BLOCK_RENDER_PAIR, FE_I18N_LITERAL, FE_NATIVE_FORM_CONTROL, FE_CLIENT_BOUNDARY]
2371
- - id: fe.components.providers
2372
- profiles: [fe]
2373
- # The client providers the root layout mounts once (owner ruling 2026-10-13, fe-stack theme/state-global/data): the redux store,
2374
- # the SWR configuration, the theme (next-themes), the HeroUI toast region and the side-effect components (SwrSideEffects,
2375
- # SocketIoSideEffects). A provider wires state, so it sits at the feature tier, above components.
2376
- path: "apps/<app>/src/components/providers/<name>/"
2377
- presence: optional
2378
- tracked: tracked
2379
- tier: feature
2380
- owner: true
2381
- requires: [index.tsx]
2382
- allows: [index.tsx]
2383
- roles: {entry: index.tsx}
2384
- tests: none
2385
- since: 3.0.0
2386
- rules: [FE_CLIENT_BOUNDARY]
2387
- - id: fe.hooks
2388
- since: 3.1.0
2389
- profiles: [fe]
2390
- path: "apps/<app>/src/hooks/<domain>/"
2391
- presence: optional
2392
- tracked: tracked
2393
- tier: hooks
2394
- owner: true # a domain is an owner: other domains import it through index.ts only
2395
- requires: [index.ts]
2396
- allows: [index.ts, "use<name>.ts", "<domain>.shared.ts"] # React hooks only; <domain>.shared.ts = sanctioned non-hook helpers
2397
- roles: {entry: index.ts, shared: "<domain>.shared.ts"}
2398
- tests: none
2399
- budget: {file: 200, barrel: 400, dataHooks: 6, useState: 6} # barrel: index.ts containing only export ... from statements
2400
- rules: [FE_HOOKS_ARE_HOOKS, FE_DATA_FRESHNESS]
2401
- - id: fe.hooks.swr
2402
- profiles: [fe]
2403
- # The data hooks (fe-stack data, FE-DATA-SWR): one useSWR / useSWRMutation / useSWRSubscription wrapper per modules/api operation, keyed
2404
- # QUERY_<X>_SWR_KEY / MUTATE_<X>_SWR_KEY / SUBSCRIBE_<X>_SWR_KEY plus the identity of the request; SwrSideEffects.tsx runs the app-wide hooks once.
2405
- path: "apps/<app>/src/hooks/swr/"
2406
- presence: optional
2407
- tracked: tracked
2408
- tier: hooks
2409
- owner: true
2410
- requires: [index.ts]
2411
- allows: [index.ts, SwrSideEffects.tsx, api/index.ts, "api/{graphql,rest}/index.ts", "api/{graphql,rest}/{queries,mutations}/index.ts",
2412
- "api/graphql/queries/useQuery*Swr.ts", "api/graphql/mutations/useMutate*Swr.ts",
2413
- "api/rest/queries/useGet*Swr.ts", "api/rest/mutations/use{Post,Put,Patch,Delete}*Swr.ts",
2414
- "api/graphql/subscriptions/index.ts", "api/graphql/subscriptions/useSubscribe*Swr.ts",
2415
- "api/sse/index.ts", "api/sse/subscriptions/index.ts", "api/sse/subscriptions/useSubscribe*Swr.ts"]
2416
- roles: {entry: index.ts, effects: SwrSideEffects.tsx}
2417
- tests: none
2418
- budget: {file: 200, barrel: 400}
2419
- since: 3.0.0
2420
- rules: [FE_HOOKS_ARE_HOOKS, FE_DATA_FRESHNESS]
2421
- - id: fe.hooks.rhf
2422
- profiles: [fe]
2423
- # The forms (fe-stack forms, FE-FORM): react-hook-form with the zod resolver; the schema carries next-intl messages and the
2424
- # submit runs an SWR mutation through modules/toast.
2425
- path: "apps/<app>/src/hooks/rhf/"
2426
- presence: optional
2427
- tracked: tracked
2428
- tier: hooks
2429
- owner: true
2430
- requires: [index.ts]
2431
- allows: [index.ts, "use*Form.ts"]
2432
- roles: {entry: index.ts}
2433
- tests: none
2434
- budget: {file: 200, barrel: 400}
2435
- since: 3.0.0
2436
- rules: [FE_HOOKS_ARE_HOOKS]
2437
- - id: fe.hooks.zustand
2438
- profiles: [fe]
2439
- # Feature-local client state (fe-stack state-local, FE-STATE-ZUSTAND): one store per folder.
2440
- path: "apps/<app>/src/hooks/zustand/<store>/"
2441
- presence: optional
2442
- tracked: tracked
2443
- tier: hooks
2444
- owner: true
2445
- requires: [index.ts, store.ts]
2446
- allows: [index.ts, store.ts, "use*.ts"]
2447
- roles: {entry: index.ts, store: store.ts}
2448
- tests: none
2449
- budget: {file: 200, barrel: 400}
2450
- since: 3.0.0
2451
- rules: [FE_HOOKS_ARE_HOOKS]
2452
- - id: fe.hooks.socketio
2453
- profiles: [fe]
2454
- # Realtime (fe-stack realtime, FE-REALTIME): one socket.io-client singleton per namespace in sockets.ts and one side-effect
2455
- # component that wires the listeners to redux and SWR.
2456
- path: "apps/<app>/src/hooks/socketio/"
2457
- presence: optional
2458
- tracked: tracked
2459
- tier: hooks
2460
- owner: true
2461
- requires: [index.ts, sockets.ts, SocketIoSideEffects.tsx]
2462
- allows: [index.ts, sockets.ts, SocketIoSideEffects.tsx, connectionStore.ts, "enums/*.ts", "types/*.ts", "use*.ts"]
2463
- roles: {entry: index.ts, effects: SocketIoSideEffects.tsx}
2464
- tests: none
2465
- budget: {file: 200, barrel: 400}
2466
- since: 3.0.0
2467
- rules: [FE_HOOKS_ARE_HOOKS]
2468
- - id: fe.hooks.effects
2469
- profiles: [fe]
2470
- # App-wide side effects (route params synced into redux, the auth bootstrap): use<X>.ts hooks and the <X>SideEffect(s).tsx
2471
- # components that run them once; a provider in components/providers mounts those components (a route never imports hooks).
2472
- path: "apps/<app>/src/hooks/effects/"
2473
- presence: optional
2474
- tracked: tracked
2475
- tier: hooks
2476
- owner: true
2477
- requires: [index.ts]
2478
- allows: [index.ts, "use*.ts", "*SideEffect.tsx", "*SideEffects.tsx"]
2479
- roles: {entry: index.ts, effects: "*SideEffect.tsx"}
2480
- tests: none
2481
- budget: {file: 200, barrel: 400}
2482
- since: 3.0.0
2483
- rules: [FE_HOOKS_ARE_HOOKS]
2484
- - id: fe.hooks.reuseables
2485
- profiles: [fe]
2486
- # Reusable generic hooks (fe-stack utils): no domain, no data.
2487
- path: "apps/<app>/src/hooks/reuseables/"
2488
- presence: optional
2489
- tracked: tracked
2490
- tier: hooks
2491
- owner: true
2492
- requires: [index.ts]
2493
- allows: [index.ts, "use*.ts"]
2494
- roles: {entry: index.ts}
2495
- tests: none
2496
- budget: {file: 200, barrel: 400}
2497
- since: 3.0.0
2498
- rules: [FE_HOOKS_ARE_HOOKS]
2499
- - id: fe.redux
2500
- profiles: [fe]
2501
- # App-wide shared state (fe-stack state-global, FE-STATE-REDUX): the store, its typed hooks, the provider and one file per slice.
2502
- path: "apps/<app>/src/redux/"
2503
- presence: optional
2504
- tracked: tracked
2505
- tier: modules
2506
- owner: true
2507
- requires: [index.ts, store.ts, hooks.ts]
2508
- allows: [index.ts, store.ts, hooks.ts, ReduxProvider.tsx, "slices/*.ts"]
2509
- roles: {entry: index.ts, store: store.ts, hooks: hooks.ts} # hooks.ts: the typed useAppDispatch/useAppSelector of the store
2510
- tests: none
2511
- budget: {file: 400}
2512
- since: 3.0.0
2513
- rules: [FE_SOURCE_FORM, FE_HOOKS_ARE_HOOKS, FE_OWNER_REACHABLE]
2514
-
2515
- - id: fe.modules
2516
- since: 3.1.0
2517
- profiles: [fe]
2518
- path: "apps/<app>/src/modules/<capability>/"
2519
- presence: required
2520
- tracked: tracked
2521
- tier: modules
2522
- owner: true
2523
- requiredInstances: {capability: [config, i18n, routes]}
2524
- # A populated fe.modules instance with no .ts or .tsx files (CSS/assets only) needs no index.ts.
2525
- requires: [index.ts]
2526
- tests: none
2527
- budget: {file: 400}
2528
- rules: [FE_ENV_OWNER, FE_TRANSPORT_OWNER]
2529
- - id: fe.modules.api
2530
- since: 3.1.0
2531
- profiles: [fe]
2532
- path: "apps/<app>/src/modules/api/"
2533
- presence: optional
2534
- tracked: tracked
2535
- tier: transport
2536
- # The browser's calls to the back end (owner ruling 2026-10-13, fe-stack graphql/rest/codegen, FE-API-GRAPHQL): the auth and
2537
- # no-auth Apollo clients with their link chain (graphql/clients), one file per operation (graphql/queries/query-<x>.ts,
2538
- # graphql/mutations/mutation-<x>.ts and graphql/subscriptions/subscription-<x>.ts, each with its gql document map and typed request/response in types/), the generated wire types
2539
- # (graphql/__generated__), the axios calls (rest/<area>/*.ts) for uploads, presigned URLs and auth endpoints and the
2540
- # server-sent-events streams (sse/<area>/stream-<channel>.ts, one operation per stream, run on the app's @starci/event-stream instance in sse/clients). A repository has
2541
- # exactly ONE client folder and ONE GraphQLResponse union: the app's (fe.transport.client/outcome) when one app calls the back end,
2542
- # or the api package's (fe.package.api.client/outcome) when several do (FE_TRANSPORT_OWNER, machine).
2543
- requires: [index.ts]
2544
- allows: [index.ts, graphql/index.ts, graphql/types.ts, "graphql/clients/**", "graphql/queries/query-*.ts", "graphql/queries/types/*.ts",
2545
- "graphql/mutations/mutation-*.ts", "graphql/mutations/types/*.ts", "graphql/subscriptions/subscription-*.ts", "graphql/subscriptions/types/*.ts",
2546
- "graphql/__generated__/**", "rest/index.ts", "rest/<area>/*.ts",
2547
- "sse/clients/**", "sse/*/stream-*.ts"]
2548
- roles: {entry: index.ts, query: "query-*.ts", mutation: "mutation-*.ts"}
2549
- # A hook imports its one operation file directly (one file per operation, FE-API-GRAPHQL), never through a barrel of every operation.
2550
- entries: ["graphql/queries/query-*.ts", "graphql/queries/types/*.ts", "graphql/mutations/mutation-*.ts", "graphql/mutations/types/*.ts", "graphql/subscriptions/subscription-*.ts", "graphql/subscriptions/types/*.ts", "sse/*/stream-*.ts"]
2551
- tests: none
2552
- rules: [FE_TRANSPORT_OWNER, FE_HTTP_STATUS_COLLAPSE, FE_WIRE_GENERATED]
2553
- - id: fe.transport.generated
2554
- since: 3.2.0
2555
- profiles: [fe]
2556
- path: "apps/<app>/src/modules/api/graphql/__generated__/"
2557
- presence: optional
2558
- tracked: ignored
2559
- tier: transport
2560
- tests: none
2561
- why: the canonical GraphQL client output of codegen is local and never committed; this specific slot overrides the tracked API parent
2562
- rules: [FE_WIRE_GENERATED]
2563
- exemplifiedBy:
2564
- - {path: packages/eslint/fe/r52-wire-generated.spec.mjs, editions: [lite, full]}
2565
- - id: fe.transport.client
2566
- since: 3.1.0
2567
- profiles: [fe]
2568
- path: "apps/<app>/src/modules/api/graphql/clients/"
2569
- presence: optional
2570
- tracked: tracked
2571
- tier: transport
2572
- tests: none
2573
- why: the auth and no-auth Apollo clients and their link chain (retry, error, timeout, token refresh, attach access token, http) of the one app that calls the back end; when several apps do, the shared client is fe.package.api.client
2574
- rules: [FE_TRANSPORT_OWNER]
2575
- - id: fe.transport.stream
2576
- since: 3.7.0
2577
- profiles: [fe]
2578
- path: "apps/<app>/src/modules/api/sse/clients/"
2579
- presence: optional
2580
- tracked: tracked
2581
- tier: transport
2582
- allows: ["*.ts"]
2583
- tests: none
2584
- why: "the event-stream client of the one app that calls the back end, the stream half of the transport client layer (FE-REALTIME): event-stream.ts creates the app's one @starci/event-stream instance (createEventStream with the bearer access token source, which opens the stream with fetch, parses the events and reopens it with Last-Event-ID after a capped, doubling wait); a stream operation (sse/<area>/stream-<channel>.ts) follows on it and a useSubscribe hook of hooks/swr reads that operation; no hand-written reader lives here (owner:event-stream-package) and only a stream operation imports this folder (FE_TRANSPORT_OWNER); a repository where several apps stream keeps one instance in each of them"
2585
- rules: [FE_TRANSPORT_OWNER]
2586
- exemplifiedBy:
2587
- - {path: packages/eslint/fe/r50-transport-owner-coverage.spec.mjs, editions: [lite, full]}
2588
- - id: fe.transport.outcome
2589
- since: 3.1.0
2590
- profiles: [fe]
2591
- path: "apps/<app>/src/modules/api/graphql/types.ts"
2592
- presence: optional
2593
- tracked: tracked
2594
- tier: transport
2595
- outcomeHome: true
2596
- tests: none
2597
- why: the one GraphQLResponse union ({success, message, error, data}) of the one app that calls the back end; when several apps do, the shared union is fe.package.api.outcome
2598
- rules: [FE_HTTP_STATUS_COLLAPSE]
2599
- - id: fe.modules.config
2600
- since: 3.1.0
2601
- profiles: [fe]
2602
- path: "apps/<app>/src/modules/config/"
2603
- presence: required
2604
- tracked: tracked
2605
- tier: foundation
2606
- tests: none
2607
- why: the only reader of process.env and NEXT_PUBLIC_*; fails fast, no localhost fallback
2608
- rules: [FE_ENV_OWNER]
2609
-
2610
- - id: fe.modules.i18n
2611
- since: 3.1.0
2612
- profiles: [fe]
2613
- path: "apps/<app>/src/modules/i18n/"
2614
- presence: required
2615
- tracked: tracked
2616
- tier: foundation
2617
- # The app's description of its languages (defineI18n of @starci/next-i18n), its request config and catalogs, or its adapter to the
2618
- # shared i18n workspace package. A single app builds its navigation (createI18nNavigation) in fe.modules.routes, keeping this
2619
- # public entry safe for its proxy. A description shared by several apps belongs to fe.package.i18n.
2620
- requires: [index.ts]
2621
- tests: none
2622
- rules: [FE_I18N_PLACEMENT, FE_I18N_CATALOG]
2623
- - id: fe.modules.brand
2624
- since: 3.1.0
2625
- profiles: [fe]
2626
- path: "apps/<app>/src/modules/brand/brand.css"
2627
- presence: optional
2628
- tracked: tracked
2629
- tier: none
2630
- tests: none
2631
- why: the ONLY app file that may hold colour values; sets grammar brand tokens only, light and dark
2632
- rules: [FE_STYLE_TOKEN_ONLY]
2633
- - id: fe.modules.routes
2634
- since: 3.1.0
2635
- profiles: [fe]
2636
- path: "apps/<app>/src/modules/routes/"
2637
- presence: required
2638
- tracked: tracked
2639
- tier: foundation
2640
- tests: none
2641
- why: every href builder; FE_HREF_RESOLVES checks each against app/
2642
- rules: [FE_HREF_RESOLVES, FE_ROUTE_HARDCODED]
2643
-
2644
- - id: fe.modules.types
2645
- since: 3.1.0
2646
- profiles: [fe]
2647
- path: "apps/<app>/src/modules/types/"
2648
- presence: optional
2649
- tracked: tracked
2650
- tier: foundation
2651
- tests: none
2652
- why: shared types with no runtime behaviour; a component may import them
2653
- rules: [FE_TYPE_ESCAPE, HFS_TS_STRICT]
2654
-
2655
- - id: fe.modules.types.ambient
2656
- parent: fe.modules.types
2657
- profiles: [fe]
2658
- path: "apps/<app>/src/modules/types/ambient/"
2659
- presence: optional
2660
- tracked: tracked
2661
- tier: foundation
2662
- owner: true
2663
- allows: ["*.d.ts"]
2664
- tests: none
2665
- since: 2.2.0
2666
- why: global ambient declarations loaded by the app compiler; this owner exposes no runtime API
2667
- rules: [FE_TYPE_ESCAPE, HFS_TS_STRICT]
2668
-
2669
- - id: fe.modules.auth
2670
- profiles: [fe]
2671
- # The identity-provider client (fe-stack auth, FE-AUTH): the session, the access token the Apollo link attaches and the
2672
- # sign-in/sign-out calls. It talks only to the app's own back-end auth doors and holds no credential: the refresh token lives in
2673
- # the back end's httpOnly cookie and the access token in the memory of the one @starci/auth client (ruling:lite-self-hosted-postgres-passport-minio).
2674
- path: "apps/<app>/src/modules/auth/"
2675
- presence: optional
2676
- tracked: tracked
2677
- tier: modules
2678
- owner: true
2679
- requires: [index.ts]
2680
- tests: none
2681
- since: 3.0.0
2682
- rules: [FE_STACK_FORBIDDEN]
2683
- - id: fe.modules.auth.client
2684
- since: 3.16.0
2685
- profiles: [fe]
2686
- editions: [lite]
2687
- 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."
2688
- # The AuthClient every edition shares, implemented by one @starci/auth/client instance over the app's own back-end auth doors.
2689
- path: "apps/web/src/modules/auth/{client.ts,email-doors.ts,index.ts}"
2690
- presence: optional
2691
- tracked: tracked
2692
- tier: inherit
2693
- tests: none
2694
- managedBy: auth-lite
2695
- managedOnly: true # lists files sync renders; the slot owning the path judges them
2696
- rules: [HFS_MANAGED_FILE_DRIFT]
2697
- - id: fe.modules.toast
2698
- profiles: [fe]
2699
- # Mutation feedback (fe-stack toast, FE-TOAST): the HeroUI toast wrapper, showGraphQLToast over a GraphQLResponse and the
2700
- # use*WithToast hooks with next-intl labels.
2701
- path: "apps/<app>/src/modules/toast/"
2702
- presence: optional
2703
- tracked: tracked
2704
- tier: modules
2705
- owner: true
2706
- requires: [index.ts, toast.tsx, api.ts, hooks.ts]
2707
- allows: [index.ts, toast.tsx, api.ts, hooks.ts]
2708
- roles: {entry: index.ts, hooks: hooks.ts} # hooks.ts: the use*WithToast hooks of the toast module
2709
- tests: none
2710
- since: 3.0.0
2711
- rules: [FE_I18N_LITERAL, FE_HOOKS_ARE_HOOKS, FE_HTTP_STATUS_COLLAPSE]
2712
-
2713
- - id: fe.package.ui
2714
- since: 3.1.0
2715
- profiles: [fe]
2716
- path: "packages/<family>-ui/"
2717
- presence: opt-in
2718
- tracked: tracked
2719
- tier: package
2720
- owner: true
2721
- kinds: [frames, composites, branches, leaves] # the layer folders under src/ (a package owns no blocks)
2722
- roles: {entry: index.tsx, drawing: component.tsx, styles: classNames.ts}
2723
- requires: [package.json, src/index.ts, tsconfig.json]
2724
- tests: none
2725
- budget: {component.tsx: 300, index.tsx: 200, dataHooks: 6, useState: 6}
2726
- why: built to dist with explicit named exports; only frames, composites, branches and leaves; no unused export; no colour literal
2727
- rules: [FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT, FE_STYLE_TOKEN_ONLY]
2728
- - id: fe.package.api
2729
- since: 3.1.0
2730
- profiles: [fe]
2731
- path: "packages/<family>-api/"
2732
- presence: opt-in
2733
- tracked: tracked
2734
- tier: package
2735
- owner: true
2736
- requires: [package.json, src/index.ts, src/graphql/clients/index.ts, src/graphql/types.ts, tsconfig.json]
2737
- tests: none
2738
- why: the one transport client and the one Outcome union shared by every app of the repository; no app keeps its own
2739
- rules: [FE_TRANSPORT_OWNER, FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT]
2740
- - id: fe.package.api.client
2741
- since: 3.1.0
2742
- profiles: [fe]
2743
- path: "packages/<family>-api/src/graphql/clients/"
2744
- presence: optional # enabled with its package (fe.package.api is the opt-in)
2745
- tracked: tracked
2746
- tier: package
2747
- tests: none
2748
- why: the repository's one pair of Apollo clients and their link chain
2749
- rules: [FE_TRANSPORT_OWNER]
2750
- - id: fe.package.api.outcome
2751
- since: 3.1.0
2752
- profiles: [fe]
2753
- path: "packages/<family>-api/src/graphql/types.ts"
2754
- presence: optional # enabled with its package (fe.package.api is the opt-in)
2755
- tracked: tracked
2756
- tier: package
2757
- outcomeHome: true
2758
- tests: none
2759
- why: the repository's one GraphQLResponse union
2760
- rules: [FE_HTTP_STATUS_COLLAPSE]
2761
- - id: fe.package.i18n
2762
- since: 3.1.0
2763
- profiles: [fe]
2764
- path: "packages/<family>-i18n/"
2765
- presence: opt-in
2766
- tracked: tracked
2767
- tier: package
2768
- owner: true
2769
- requires: [package.json, src/index.ts, tsconfig.json]
2770
- tests: none
2771
- 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
2772
- rules: [FE_I18N_PLACEMENT, FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT]
2773
-
2774
- # Checks that read this manifest (all ship from .claude; none keeps its own path list)
2775
- consumers:
2776
- - scripts/hfs/slots.mjs # the loader every consumer below goes through
2777
- - scripts/hfs/check.mjs # starci app check: HFS_SLOT_* / tracked / external, the side view per side
2778
- - scripts/hfs/architecture.mjs # tiers, direction matrix, cycles, reachability
2779
- - packages/eslint/be starciBeConfig({hfs}) # file globs for rules come from slots
2780
- - packages/eslint/fe starciFeConfig({hfs})
2781
- - packages/stylelint # @starci/stylelint-canon: colour and brand allowances from fe.modules.brand
2782
- - packages/hfs/sync # renders managedBy templates (starci app sync) and judges them (starci app check)
2783
- - modules/kernel/failure-codes.yaml # every rule id listed above has a Vietnamese why