@starci/eslint-grammar-offset-pop 0.22.0 → 0.23.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +8 -0
- package/package.json +6 -5
- package/runtime/bundle.json +2 -51
- package/runtime/engine/by-code-unit.mjs +0 -12
- package/runtime/engine/config.mjs +0 -461
- package/runtime/engine/invalid-config.mjs +0 -15
- package/runtime/engine/model-config.mjs +0 -112
- package/runtime/engine/orca-config.mjs +0 -34
- package/runtime/engine/plain-object.mjs +0 -5
- package/runtime/engine/release-config.mjs +0 -32
- package/runtime/engine/removed-vocabulary.mjs +0 -27
- package/runtime/engine/resources-config.mjs +0 -59
- package/runtime/engine/runtime-root.mjs +0 -138
- package/runtime/engine/secrets.mjs +0 -202
- package/runtime/engine/sonar-config.mjs +0 -24
- package/runtime/engine/yaml.mjs +0 -161
- package/runtime/knowledge/hfs/canon-pins.yaml +0 -720
- package/runtime/knowledge/hfs/slots.yaml +0 -2783
- package/runtime/modules/kernel/removed-vocabulary.yaml +0 -458
- package/runtime/modules/models/registry.yaml +0 -221
- package/runtime/modules/models/runtimes.yaml +0 -556
- package/runtime/modules/models/tiers.yaml +0 -66
- package/runtime/scripts/hfs/allows.mjs +0 -77
- package/runtime/scripts/hfs/architecture/root-packages.mjs +0 -78
- package/runtime/scripts/hfs/declaration-shape.mjs +0 -196
- package/runtime/scripts/hfs/declaration-slots.mjs +0 -89
- package/runtime/scripts/hfs/edition-slots.mjs +0 -80
- package/runtime/scripts/hfs/manifest-shape.mjs +0 -474
- package/runtime/scripts/hfs/param-names.mjs +0 -13
- package/runtime/scripts/hfs/rule-catalog.mjs +0 -458
- package/runtime/scripts/hfs/rule-params-shape.mjs +0 -103
- package/runtime/scripts/hfs/slot-app-view.mjs +0 -97
- package/runtime/scripts/hfs/slot-classify.mjs +0 -69
- package/runtime/scripts/hfs/slot-errors.mjs +0 -12
- package/runtime/scripts/hfs/slot-imports.mjs +0 -98
- package/runtime/scripts/hfs/slot-manifest-shape.mjs +0 -111
- package/runtime/scripts/hfs/slot-match.mjs +0 -164
- package/runtime/scripts/hfs/slot-path.mjs +0 -6
- package/runtime/scripts/hfs/slot-required.mjs +0 -95
- package/runtime/scripts/hfs/slot-semantic-problems.mjs +0 -175
- package/runtime/scripts/hfs/slot-side-problems.mjs +0 -32
- package/runtime/scripts/hfs/slots.mjs +0 -306
- package/runtime/scripts/hfs/view.mjs +0 -180
- package/runtime/scripts/lib/glob.mjs +0 -32
- package/runtime/scripts/lib/i18n.mjs +0 -82
- package/runtime/scripts/lib/json-clone.mjs +0 -70
- package/runtime/scripts/lib/list.mjs +0 -26
- package/runtime/scripts/lib/path-key.mjs +0 -124
- package/runtime/scripts/lib/regex.mjs +0 -3
- 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
|