@starci/hfs 4.0.7 → 4.0.9

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## Unreleased
+
+- Breaking (runtime alpha.4 CLI unification): remove the `hfs` bin and expose `main(argv, io)` for the sole `starci app ...` grammar; the app flags `--repo` and `--root` are replaced by the global `--cwd` flag.
+- Changed (contract change `coverage-modules-logic`): the coverage scope is derived once from the slot manifest (`coverage: required|none` on every tracked be slot, `ruleParams.be.logicRoles`; `scripts/hfs/coverage-scope.mjs`). `hfs sync` renders it into `be/jest.config.js` (`starciJestConfig({ coverage })`), `sonar.coverage.exclusions` and `codecov.yml` (the measured roots, plus one Codecov component per service app and one `platform`, each at 100); `coverageScope`, `coverageExclusions` and `HFS_SYNC_COVERAGE_SCOPE` are gone. New R204 `HFS_COVERAGE_SCOPE_DRIFT`: a hand edit of any of the three coverage statements is drift. `hfs scaffold app` renders with the source it just wrote.
+- Added (contract change `lite-edition`): the lite edition. `hfs.json` `edition: lite` (and an optional `supabase` block); `hfs scaffold app <name> --edition lite` writes the lite shape and generates `supabase/types/database.types.ts` by starting the app's own local Supabase stack (`HFS_SCAFFOLD_TYPES_FAILED` removes the app when it cannot); `hfs upgrade --edition full [--plan]` (additions only, new `upgrade/**` in the package files) and `hfs check --edition full`; `hfs add table <name> [--fe] [--no-types]`, `hfs add app <name>` and the lite bootstrap of `hfs add cli`; `add` and `new` refuse the nouns lite lacks (`<verb> <noun>: full edition only`); `hfs emit-contracts` also writes the Supabase types; `hfs check` runs the database rules (R213 to R216) and the lite rules (R212, R217 to R220) with the bundled runtime. New dependencies `libpg-query` and `smol-toml`.
+- Added: lite-edition `hfs sync` renders its managed scripts, hooks, CI/database workflows, image matrix and Sonar configuration from edition-aware slot templates, without Jest, tests, Codecov or coverage conditions; full renders remain byte-identical.
+- Added (contract change `patterns-hfs-add`): `hfs add <job|reactor|queue|projection> <name>` generates exactly one kind's file tree from the `files:` tree of its pattern topic (knowledge/patterns/be/<topic>.yaml, carried by the bundled runtime) with the one template body of each entry (templates/be/patterns), adds the platform capabilities the kind needs when they are missing, and registers the patterns and the trigger kind in hfs.json (`sides.be.patterns`, `sides.be.kinds`). `hfs.json` gains `sides.be.kinds`, required for every trigger kind in use (rules BE_KIND_DECLARATION, BE_KIND_EMPTY).
+- New (microservice policy, R163 to R167): `hfs check` judges a product with more than one service: `HFS_SERVICE_PLACEMENT`, `HFS_IMAGE_UNPINNED`, `HFS_SERVICE_STACK_DECLARATION`, `HFS_EVENT_CONTRACT` and `BE_ASYNC_SPEC_MISSING`; `hfs emit-contracts` writes `be/contracts/<service>/events.json` from the literal `EVENTS` table of `apps/<service>/src/events.ts`. New slot `be.contract.events`.
+- Changed: `hfs scaffold app` writes the final front end: two Next apps, `fe/apps/landing` and `fe/apps/app`, over the shared workspace packages `fe/packages/<name>-ui` (`@<name>/ui`: the brand shell, the locale shell and the boundary notices both apps mount) and `fe/packages/<name>-i18n` (`@<name>/i18n`: the next-intl stack written once, `createAppI18n` plus the `./proxy` and `./routing` subpaths; R59). hfs.json declares `fe.package.ui` and `fe.package.i18n`; each workspace's package.json declares exactly what its source imports; the request config still reads the locale through `next/root-params` (FE-I18N-1), now in the package. Template path variables: an fe `apps/<name>/` folder is the skeleton of that app alone (`__app__` is gone from the fe side), `__project__` is the project name.
+- New: `hfs secret list|show|set|gen` (alpha.5 item 6.4), the canon command over the sealed secrets of `.starcistacks/<env>/secrets/<slug>.enc`, on the runtime's sops api (a new `seal` call: the value travels on stdin, never on an argument list). Replaces the plain `sops` commands of runbooks and KEYS.md files.
+- Changed: HFS_REQUIRED_FILE_MISSING now also carries what BE_REQUIRED_MODULE_MISSING reported, and BE_TEST_TOPOLOGY what HFS_TEST_KIND_RETIRED reported (one code per obligation); the bundled architecture machine follows `APP_GUARD` and `APP_FILTER` providers built by a helper outside the app root file.
+- Changed: the managed fe scripts (`dev:fe`, `start:<app>`, `build:fe`) run `next` from the app directory (`cd fe/apps/<app> && next ...`) so next-intl finds its request config; the fe skeleton reads the request locale through `next/root-params` (`experimental.rootParams`), pins the workspace root three levels above the app and uses the `.*[.].*` proxy matcher; the bundled runtime carries the `&&`/`||`-aware FE_SWR_KEY_IDENTITY check.
+## Unreleased (C0 batch)
+
+- Fixed (contract change `sonar-coverage-exclusions`): SonarQube has no `sonar.coverage.inclusions` property, so Sonar ignored it and counted every executable be/ file at 0% (overall coverage 65.8% and 45.2% on the examples, although every service was at 100). The managed `sonar-project.properties` now renders `sonar.coverage.exclusions` as the complement of the services. `coverageExclusions(presets, manifest)` in `sync/index.mjs` derives it from the preset's `COVERAGE_SOURCES` and the slot manifest, and lists:
+  - every be role of the R89 suffix vocabulary other than `service`;
+  - the be file names a slot declares outside it (`main.ts`, `index.ts`, `connection.ts`, the migrations, the test world's files);
+  - `fe/**`.
+
+  A coverage source whose complement Sonar's globs cannot write is refused (`HFS_SYNC_COVERAGE_SCOPE`). `sonar.coverage.inclusions` is deleted.
+- Fixed: the fe skeleton's `[locale]/error.tsx` exports `ErrorBoundary` (Sonar S2137: `Error` shadowed the global).
+
 ## 4.0.7 - 2026-10-01
 
 - Changed: the runtime layer check (scripts/api/<system>, a pure scripts/lib) in its bundled runtime.

package/README.md

@@ -1,38 +1,70 @@
 # @starci/hfs
 
-The HFS command line of a StarCi app: the one repository of a product, `<app>/` with its root (the one `package.json`, lockfile and `node_modules`, `hfs.json` of kind `app`, CI, hooks, `.starciwork`) and its two sides `be/` and `fe/`. It is installed from the npm registry at the exact version in `knowledge/hfs/canon-pins.yaml` (see [`packages/README.md`](../README.md)),
+The HFS command line of a StarCi app: the one repository of a product, `<app>/` with its root (the `app.*` slots: the one `package.json`, lockfile and `node_modules`, the `hfs.json` declaration of kind `app`, CI, hooks, the `app.starciwork` work area) and its two sides `be/` and `fe/` (slot `app.sides`). It is installed from the npm registry at the exact version in `knowledge/hfs/canon-pins.yaml` (see [`packages/README.md`](../README.md)),
 and it is self-contained: `runtime/` carries the slot manifest, the canon pins, the Vietnamese why
 catalog slice, the loader and the architecture machine with every file it imports, so it runs where there is no runtime
 checkout. The machine loads `typescript` from the app it checks (never its own copy), so run `npm ci` first.
 
-Every command runs at the app root. A side is judged with its folder as the root it was when products were split in two repositories (the "side view" of `scripts/lib/hfs-slots.mjs`): the root slots (`app.*`) are judged once, the `be.*` slots under `be/` and the `fe.*` slots under `fe/`, and nothing crosses sides except `sides.fe.reads` (`be/contracts/`, the input of the front end's codegen). Every finding path is app-relative (`be/src/...`, `fe/apps/...`).
+Every command runs at the app root. A side is judged with its folder as the root it was when products were split in two repositories (the "side view" of `scripts/hfs/slots.mjs`): the root slots (`app.*`) are judged once, the `be.*` slots under `be/` and the `fe.*` slots under `fe/`, and nothing crosses sides except `sides.fe.reads` (the `be.contract.*` slots, the input of the front end's codegen). Every finding path is app-relative (`be/...`, `fe/...`).
 
 ```sh
-npx hfs lint    [--repo <dir>] [--changed <file>...] [--fix] [--format text|json] [--sonar <file>] [--stylelint <glob>]   # THE lint entry (`npm run lint`): ESLint over be/ with the BE canon and over fe/ with the FE canon, stylelint over fe/, the hfs checks; exit 0 clean, 1 findings, 2 a tool could not run
-npx hfs check   [--repo <dir>] [--json] [--fast] [--base <ref>]   # the repository pass alone (what `hfs lint` runs for the findings that have no TypeScript file); exit 1 on any error-level finding
-npx hfs scaffold app <name> [--into <dir>]   # a new app <dir>/<name>/: the root, be/ and fe/ skeletons and the app hfs.json; refuses an existing directory
-npx hfs emit-contracts [--repo <dir>]         # write be/contracts/<app>/schema.graphql of every api app that serves GraphQL and be/contracts/<app>/openapi.json of every api app with a typed operation table (the managed script contract:emit)
-npx hfs explain <path> [--repo <dir>] [--json]
-npx hfs sync (--check | --write) [--root <dir>]   # generated files: the managedBy slots of slots.yaml, the .gitignore block (sync/, templates/)
-npx hfs work-hygiene                              # pre-commit guard: staged .starciwork / .starcistacks paths, and the secrets guard over every staged file (read from the index)
-npx hfs new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--repo <dir>]   # a back-end service and its unit spec skeleton
-npx hfs new spec <file>.service.ts [--repo <dir>]                                                              # the spec skeleton of an existing service
+starci app scaffold <name> [--into <dir>] [--edition full|lite] [--cwd <dir>]
+starci app add <api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app> <name> [--fe] [--no-types] [options] [--cwd <dir>]
+starci app lint [--cwd <dir>] [--changed <file>...] [--workspace <dir>] [--fix] [--format text|json] [--sonar <file>]
+starci app sync (--check | --write) [--cwd <dir>]
+starci app check [--cwd <dir>] [--json] [--fast] [--base <ref>] [--edition full] [--db-types]
+starci app upgrade [--edition full] [--plan]
+starci app stack <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--cwd <dir>]
+starci app explain <path> [--cwd <dir>] [--json]
+starci app emit [--cwd <dir>]
+starci app new service <dir> <name> [--inject <binding>...] [--cwd <dir>]
+starci app new spec <file>.service.ts [--cwd <dir>]
+starci app new image [--cwd <dir>]
+starci app secret list|show|set|gen ... [--cwd <dir>]
+starci app hygiene [--cwd <dir>]
 ```
 
+## Lite edition
+
+Lite is the smaller edition of the same HFS standard, not another profile or engine. The declaration sets `edition` to `lite`;
+the same slot manifest, rule catalog, lint canons, grammar, security rules and Docker rules apply, while edition fields filter
+out the test world and event machinery.
+
+`starci app scaffold <name> --edition lite` creates the minimum single-api, single-Next-app Supabase product. It generates the
+`app.supabase.types` artifact from the app's local Supabase stack; if that generation cannot run, scaffolding fails and removes
+the app it began instead of leaving a partial tree.
+
+The lite additions are deliberately narrow:
+
+- `starci app add table <name> [--fe] [--no-types]` adds the migration and matching back-end capability. `--fe` also adds typed readers
+  and writers through the front-end database owner; types regenerate by default, while `--no-types` is the explicit opt-out.
+- `starci app add cli <group>` creates the optional cli app on first use, including its built-in migration and seed groups, then adds
+  the requested group without full-edition specs.
+- `starci app add app <name>` refuses in lite because lite has exactly one front-end app. Upgrade before adding another.
+- An `add` or `new` whose target slot is unavailable in lite stops before writing with `<verb> <noun>: full edition only`.
+
+`starci app emit` continues to emit the enabled back-end snapshots and also writes `supabase/types/database.types.ts` when
+the `app.supabase.types` slot is enabled. The local Supabase stack must be running for generation.
+
+Plan the transition with `starci app upgrade --edition full --plan`, then use `starci app check --edition full [--db-types]` to judge the
+unchanged lite tree through the full-edition view. The check is read-only; `--db-types` includes a fresh generated-types
+comparison when the local stack is available. Applying `starci app upgrade --edition full` adds the full-only managed configuration,
+test layers and cli requirements without rewriting product code. Downgrade to lite is not supported.
+
 ## Creating a service
 
-Only `*.service.ts` files are unit-tested (unit test standard), each with exactly one colocated `<name>.service.spec.ts`. `hfs new` is the one way they come into being together:
+Every file of a spec-required role of `ruleParams.be.unitRoles` — a `*.service.ts`, a `*.cli.ts` of the cli feature root — owes exactly one colocated `<name>.<role>.spec.ts` (unit test standard), and any other file of a `ruleParams.be.logicRoles` role inside a `coverage: required` slot may carry one beside it. `starci app new` is the one way a service and its spec come into being together:
 
-- `hfs new service src/modules/domain/commission commission --inject InjectPrimaryEntityManager=@modules/platform/database:EntityManager --inject InjectClock=@modules/platform/clock:Clock` writes `commission.service.ts` (the class, `@Injectable()`, the constructor with the given `@Inject*()` parameters) and `commission.service.spec.ts`. `--inject` is `<Decorator>=<module>:<Type>` for a custom `@Inject*()` decorator (its token is the UPPER_SNAKE of the name, `PRIMARY_ENTITY_MANAGER`, exported from the same module) or `<Class>=<module>` for a class-typed dependency. The directory must belong to a slot of the manifest that owns the file (a service lives in `src/modules/{domain,platform,integrations}/<capability>/`), and `hfs new` never overwrites.
-- `hfs new spec src/modules/domain/member/member-profile.service.ts` writes only the spec of a service you wrote by hand. It reads the constructor with the repository's own TypeScript compiler API, so `npm ci` comes first.
+- `starci app new service src/modules/domain/commission commission --inject InjectPrimaryEntityManager=@modules/platform/database:EntityManager --inject InjectClock=@modules/platform/clock:Clock` writes `commission.service.ts` (the class, `@Injectable()`, the constructor with the given `@Inject*()` parameters) and `commission.service.spec.ts`. `--inject` is `<Decorator>=<module>:<Type>` for a custom `@Inject*()` decorator (its token is the UPPER_SNAKE of the name, `PRIMARY_ENTITY_MANAGER`, exported from the same module) or `<Class>=<module>` for a class-typed dependency. The directory must belong to a slot of the manifest that owns the file (a service lives in `src/modules/{domain,platform,integrations}/<capability>/`), and `starci app new` never overwrites.
+- `starci app new spec src/modules/domain/member/member-profile.service.ts` writes only the spec of a service you wrote by hand. It reads the constructor with the repository's own TypeScript compiler API, so `npm ci` comes first.
 
-The spec skeleton is `Test.createTestingModule({ providers: [Service, { provide: TOKEN, useValue: double }, ...] }).compile()` and `moduleRef.get(Service)`, with one provider per constructor dependency and nothing else, every double imported from `@starci/jest-preset` (the root), and one placeholder `it` per public method. The double of a token comes from `ruleParams.be.specDoubles` of the slot manifest, the table the lint law `spec-infra-double-from-kit` holds a spec to (`*_ENTITY_MANAGER` -> `mockEntityManager()`, `CLOCK` -> `new FakeClock(...)`, `OUTBOX` -> `recordingOutbox()`, `CACHE` -> `fakeCache(clock)`, lock, lease, fence and hold -> `fakeLock(clock)`, ids -> `fakeIds()`, `*_OPTIONS` -> a literal to fill in, everything else and every class -> `mock<T>()`), so the skeleton satisfies the law by construction: no cast, no `new` of the service, no ambient clock. A back end only (a front end has no services); the files are written for prettier (print width 120).
+The spec skeleton is `Test.createTestingModule({ providers: [Service, { provide: TOKEN, useValue: double }, ...] }).compile()` and `moduleRef.get(Service)`, with one provider per constructor dependency and nothing else, every double imported from `@starci/jest-preset` (the root), and one placeholder `it` per public method. The double of a token comes from `ruleParams.be.specDoubles` of the slot manifest, the table the lint law `spec-infra-double-from-kit` holds a spec to (`*_ENTITY_MANAGER` -> `mockEntityManager()`, `CLOCK` -> `new FakeClock(...)`, `EVENT_BUS` -> `recordingEventBus()`, `QUEUE_OUTBOX` -> `recordingQueueOutbox()`, `CACHE` -> `fakeCache(clock)`, lock, lease, fence and hold -> `fakeLock(clock)`, ids -> `fakeIds()`, `*_OPTIONS` -> a literal to fill in, everything else and every class -> `mock<T>()`), so the skeleton satisfies the law by construction: no cast, no `new` of the service, no ambient clock. A back end only (a front end has no services); the files are written for prettier (print width 120).
 
-`hfs check` reads the app's `hfs.json` and the tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and then runs the
+`starci app check` reads the app's `hfs.json` and the tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and then runs the
 whole architecture machine over each side folder. Every finding carries a why code and its Vietnamese text
 (`modules/kernel/failure-codes.yaml`).
 
-Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rendered-file checks (`sync/managed.mjs`) and the prettier check (`sync/format.mjs`) live in `sync/` because they read the templates and the repository's own install, and reach `hfs check` as `extraFindings`; the jest / vitest preset the coverage exclusions come from and prettier are read from the repository's `node_modules`, so run `npm ci` first):
+Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file checks (`sync/managed.mjs`) and the prettier check (`sync/format.mjs`) live in `sync/` because they read the templates and the repository's own install, and reach `starci app check` as `extraFindings`; the jest / vitest preset the coverage exclusions come from and prettier are read from the repository's `node_modules`, so run `npm ci` first):
 
 | Code | Level | Meaning |
 |---|---|---|
@@ -45,7 +77,7 @@ Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rende
 | `HFS_MIN_INSTANCES` | error | fewer instances of a slot than `minInstances` |
 | `HFS_CANON_PIN_DRIFT` | error | a dependency not at the exact version of `knowledge/hfs/canon-pins.yaml` |
 | `HFS_SIZE_SOFT_BACKLOG` | info | a source file over `ruleParams.fileLines.soft`; report only, never fails |
-| `HFS_MANAGED_FILE_DRIFT` | error | a managed file that exists but differs from its render (hooks, workflows, sonar, `tsconfig.build.json`, `src/tests/tsconfig.json` (back end), `jest.config.js` (back end), `.prettierrc`, `.prettierignore`, the `scripts` block of `package.json`, compared as parsed JSON) |
+| `HFS_MANAGED_FILE_DRIFT` | error | a managed file that exists but differs from its render (the `managedBy` slots: hooks, workflows, sonar, the back-end `be.tool-config` files, `app.format-config`, the `scripts` block of `app.package-manifest`, compared as parsed JSON) |
 | `HFS_RULE_OFF_WITHOUT_REPLACEMENT` | error | `eslint.config.mjs`, or a front end's `stylelint.config.mjs`, differs from its one-line render, so a rule could be off, warned or redefined in it |
 | `HFS_TOOL_CONFIG_LOCAL` | error | a repository holds a tool config outside the managed set (`.eslintrc*`, `.eslintignore`, a second `eslint.config.*` or `stylelint.config.*`, another prettier or lint-staged config, or a jest config in a back end that is not the one root file), a file that defines an ESLint rule or a stylelint plugin, a tool configuration key in a `package.json` (`eslintConfig`, `stylelint`, `prettier`, `lint-staged`, `jest`), or a script that runs eslint, stylelint or prettier with a flag that swaps the configuration |
 | `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render (no host URL; the ESLint report and HFS import paths), or the stack declaration names another quality gate than the one of `knowledge/sonar-gate.yaml` |
@@ -55,60 +87,71 @@ Its own checks (`scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-rules/`; the rende
 | `HFS_UNTRACKED_ROOT_ENTRY` | error | an entry git neither tracks nor ignores (`git ls-files -o --exclude-standard`), outside an `ignored` slot |
 | `HFS_PLAINTEXT_SECRET` | error | a tracked plaintext secret: an env, key or credentials file, a value the push scan refuses (never printed), or an `.enc` that is no sops envelope (R06) |
 | `HFS_STACKS_SHAPE` | error | a `.starcistacks` path outside the standard shape (a sealed file outside `<env>/secrets/`, `runtime/files/`, root `DESIGN.md` or `k8s/`), a local Sonar not owned by the host, a service still rooted at `.stacks` (R10) |
-| `HFS_CI_MISSING_CANON` | error | `ci.yml` without a `run:` step of `hfs lint` (`npm run lint`, or `npx hfs lint` at the pinned version), or `.husky/pre-push` without `npm run typecheck` and `npm run lint` (R13) |
+| `HFS_CI_MISSING_CANON` | error | `ci.yml` without a `run:` step of `starci app lint` (`npm run lint`, or `npx starci app lint` at the pinned version) (R13) |
 | `HFS_DEP_VERSION_SKEW` | error | a dependency at two specs across the root and workspace `package.json` files, a dependency declared at another version than the root `overrides` pin, or a nested copy of a declared dependency in `package-lock.json` (R14) |
 | `HFS_CONTRACT_SNAPSHOT_DRIFT` | error | a back-end api app serving GraphQL without `be/contracts/<app>/schema.graphql` (R23); the front end reads that snapshot in place, so there is no copy to drift |
-| `BE_TEST_TOPOLOGY` | error | a `*.test.*` file, a `testing/` folder, a second jest configuration or a `jest` key in `package.json` (R47; `int-spec`, `harness-spec` and the retired test folders are the machine's `HFS_TEST_KIND_RETIRED`) |
+| `BE_TEST_TOPOLOGY` | error | a `*.test.*` file, a `testing/` folder, a second jest configuration or a `jest` key in `package.json` (R47; `int-spec`, `harness-spec`, the retired test folders and a per-lane test config are the machine's, under the same code) |
 | `BE_SPEC_PLACEMENT` | error | a `*.spec.*`, `*.test.*` or `*-spec.*` file outside the four test layers, `scripts/` and `tools/` included (R102) |
 | `HFS_REPO_LOCAL_CHECK` | error | a `check-*` file in `scripts/` or `tools/`, an `eslint-local-rules*` file or local eslint plugin, or a script that runs a local check (R103) |
 | `HFS_LINT_SUPPRESSION_FILE` | error | an `eslint.suppressions*` file, a `lint:suppressions` script, an eslint suppress flag or a suppressions config (R104) |
 | `HFS_PROOF_COMMAND_FILE_MISSING` | error | a `.starciwork` `requiresProof.<kind>.command` that runs a file the repository does not hold (R105) |
+| `FE_GRAPHQL_CONTRACT` | error | a front-end `.graphql` document that the back end's contract snapshot (`be/contracts/<service>/schema.graphql`) does not serve: an unknown field, argument or input field, a missing required argument, a variable of another type, or a selection that does not fit (R113) |
+| `HFS_SERVICE_PLACEMENT` | error | a folder outside `be/apps/<service>/` with a `Dockerfile` or a `package.json` of its own (R163): a back-end service is a Nest app of the one repository |
+| `HFS_IMAGE_UNPINNED` | error | in a product with more than one service, a stack component whose `image` has no tag, `latest`, a branch word or a major or minor-only tag instead of a digest or an exact version (R164) |
+| `HFS_SERVICE_STACK_DECLARATION` | error | an api or worker app of a multi-service product that is not a `role: service` component of `application-stacks.yaml` (R165) |
+| `HFS_EVENT_CONTRACT` | error | the vendored async contract: a missing or stale `be/contracts/<service>/events.json`, a `consumes.ts` entry the provider's snapshot does not declare at that version, a `compensates` naming no declared event, or a consumer queue no consumes table lists (R166) |
+| `BE_ASYNC_SPEC_MISSING` | error | a consumed event no e2e spec through `useTestWorld` names, or a saga step whose spec does not also name the compensated event (R167) |
 | `BE_INTEGRATION_SPEC_MISSING` | error | an integration (`src/modules/integrations/<provider>/` with `<provider>.config.ts`) without a `src/tests/integration/<provider>/*.integration-spec.ts` that registers its module through `useTestWorld({ modules })`, references its ErrorCode enum and drives an outage through the world (R112) |
+| `HFS_MONO_WORKSPACES` | error | the app root `package.json` without `workspaces` exactly `["fe/apps/*", "fe/packages/*"]`, `packageManager` `npm@<version>` or a `turbo` devDependency (R143) |
+| `HFS_MONO_FE_WORKSPACE` | error | an fe app `package.json` not named `@<project>/<app>`, not private, or without exactly the workspace scripts; an fe package without `build`, `typecheck` and the workspace `lint` (R144) |
+| `HFS_MONO_NEST_PROJECTS` | error | `be/nest-cli.json` not `monorepo: true`, its default project not an api app, or its `projects` not exactly the declared be apps (R145) |
+| `HFS_MONO_WORKSPACE_DEP` | error | an fe workspace imports a package its own `package.json` does not declare, or the root `package.json` declares a workspace package (R146) |
+| `BE_CLI_REQUIRED` | error | a back end with a connection or a command under `src/features/cli/` and no cli app `be/apps/cli`, a cli app of another name, or no `be/apps/cli/Dockerfile` (R147) |
 | `HFS_PEER_INTEGRATION_MISSING` | error | the app root `package.json` depends on a driver integration (a pair of `knowledge/hfs/peer-integrations.yaml`) without its runtime peer, e.g. `@nestjs/apollo` on `@nestjs/platform-express` 11 without `@as-integrations/express5` (R111) |
 | `FE_WIRE_GENERATED` | error | a contract copy with no `codegen` script wired before `build` and `typecheck`, or generated types older than the copy (R52) |
 | `FE_I18N_PLACEMENT` | error | no `next-intl`, no `src/proxy.ts`, a `middleware.ts`, a route file outside `[locale]`, no `vi.json` catalog (R59) |
 | `FE_I18N_CATALOG` | error | a locale catalog lacking a key another locale has (R60) |
 | `FE_I18N_KEYS` | error | a literal key read through `next-intl` that a locale lacks, or a catalog key no source reads (R106; the architecture machine) |
-| `FE_NO_TESTS` | error | a front end holds a `*.spec.*`, `*.test.*` or `*-spec.*` file, an `e2e/`, `__tests__/`, `__mocks__/` or `test-support/` directory, a vitest, Playwright, jest or Cypress file, a test script, or a test dependency in a `package.json`; no exception (R97; `scripts/lib/hfs-rules/fe-no-tests.mjs`) |
+| `FE_NO_TESTS` | error | a front end holds a `*.spec.*`, `*.test.*` or `*-spec.*` file, an `e2e/`, `__tests__/`, `__mocks__/` or `test-support/` directory, a vitest, Playwright, jest or Cypress file, a test script, or a test dependency in a `package.json`; no exception (R97; `scripts/hfs/rules/fe-no-tests.mjs`) |
 | `HFS_GITIGNORE_BLOCK_DRIFT` | error | the managed `.gitignore` block differs from its render (R04; `sync/managed.mjs`) |
-| `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render: no `sonar.host.url`, the `sonar.exclusions` of the installed jest preset, the be lcov import with the services as the only coverage scope (R11; `sync/managed.mjs`) |
+| `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render: no `sonar.host.url`, the `sonar.exclusions` of the installed jest preset, the be lcov import with the coverage scope the slot manifest derives as the only coverage scope (R11; `sync/managed.mjs`) |
 | `HFS_FORMAT` | error | a tracked file the repository's own prettier would change (R19; `sync/format.mjs`, not under `--fast`) |
 | `HFS_FORMAT_TOOL_MISSING` | refusal (exit 2) | prettier is not installed in the repository; the format check is never skipped |
 
 The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
-files is the `managedBy` slots of `slots.yaml`; `hfs sync --write` renders them and `hfs check` compares them, so a hand edit and a forgotten `sync` are the same finding.
+files is the `managedBy` slots of `slots.yaml`; `starci app sync --write` renders them and `starci app check` compares them, so a hand edit and a forgotten `sync` are the same finding.
 Each finding is reported once: the eslint and stylelint one-liners under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
-The root and both sides are rendered by the one mechanism. The root: `package.json` `scripts` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:stack`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `.prettierrc`, `.prettierignore`, the `.husky` hooks, the CI workflows, the Sonar file and the `.gitignore` block. A side: its `tsconfig.json` (resolving `@starci/tsconfig` from the root `node_modules`), its `eslint.config.mjs` one-liner, and for be `tsconfig.build.json`, `src/tests/tsconfig.json` and `jest.config.js`, for fe `stylelint.config.mjs`. `lint` is the one lint gate, `hfs lint`: ESLint over each side with its canon, the app check and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
-(`fe.tool-config-repo`): it carries the task graph, which no preset can render.
+The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:stack`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its eslint one-liner, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is the one lint gate, `starci app lint`: ESLint over each side with its canon, the app check and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
+(slot `app.task-graph`): it carries the task graph, which no preset can render.
 
-The architecture machine (`scripts/checks/architecture.mjs` of the runtime, the same code bundled here): tiers and import
+The architecture machine (`scripts/hfs/architecture.mjs` of the runtime, the same code bundled here): tiers and import
 direction, owner public API, cycles, module registration and composition, clones, dead exports, required files,
 the source-shape, contract-form and front-end rules, and the repository-tree rules. Each violation and each error is one
 finding under the machine's own rule id (`BE_TIER_DIRECTION`, `HFS_UNUSED_EXPORT`, `ARCH_OWNER_EXPORT_BYPASS`, ...). A
 repository without `typescript` installed fails with `ARCH_TYPESCRIPT_MISSING`; the check never passes because it could not run.
 
-`--fast` (the template pre-push hook runs `npx hfs check --fast`) judges only what changed since the merge-base of `HEAD` with
+`--fast` judges only what changed since the merge-base of `HEAD` with
 `origin/main` (else `main`; `--base <ref>` names another ref): the slot and pin checks on the changed paths, the machine on the owners
 of the changed source files without clones and dead exports, and no file-system tree checks. The required-file and minimum-instance
 checks still cover the whole tree. With no merge-base `--fast` is a refusal (exit 2) that names the fix, never a silent full
 pass.
 
-Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). `hfs check` and `hfs lint` never write to the app
-(`hfs lint --fix` lets ESLint and stylelint fix in place).
+Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). `starci app check` and `starci app lint` never write to the app
+(`starci app lint --fix` lets ESLint and stylelint fix in place).
 
 ## Sonar
 
 One mechanism for both sides: every finding of the canon is imported into Sonar, and the quality gate
-fails while any is open. Nothing is configured per app; the pieces are managed files (`hfs sync`) and this package.
+fails while any is open. Nothing is configured per app; the pieces are managed files (`starci app sync`) and this package.
 
-One entry, one report, one file: `npm run lint` is `hfs lint`; `npm run lint -- --sonar reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings of `hfs check`, rule id = the finding code), `eslint` (the BE and FE canon plugins alike, rule id = the ESLint rule) and `stylelint` over fe (rule id = the stylelint rule). `hfs lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
+One entry, one report, one file: `npm run lint` is `starci app lint`; `npm run lint -- --sonar reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings of `starci app check`, rule id = the finding code), `eslint` (the BE and FE canon plugins alike, rule id = the ESLint rule) and `stylelint` over fe (rule id = the stylelint rule). `starci app lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
 
 `--sonar` writes the findings as a Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`) before the verdict, so a
 failing lint still leaves its report. A rule's name and description are the catalog's English title and Vietnamese title, meaning and next step;
 impacts are HIGH (maintainability). `info` findings (the soft-size backlog) are report-only and not imported. The output is sorted, so two runs
 over one tree are byte-identical. Sonar drops an issue on a file it does not index (a tracked source file or stylesheet under `sonar.sources`), so the ONE placement rule of the three engines files a finding on
 any other path (hfs.json, a workflow, a config file, `e2e/`, a package the sources do not list) and a finding with no path on the first source file, its message starting with the real path.
-Sonar's own ESLint import (`sonar.eslint.reportPaths`) is not used: it drops those issues silently. `sonar.sources` lists `be/apps`, `be/src` and `fe/apps` (plus `fe/packages` when the front end opts into an `fe.package.*` slot); `sonar.tests` is the back end's.
+Sonar's own ESLint import (`sonar.eslint.reportPaths`) is not used: it drops those issues silently. `sonar.sources` lists the back end's app and shared-source roots (the `be.app.*` and `be.*` source slots) and the front end's apps (the `fe.app.*` slots, plus `repo.packages` when the front end opts into an `fe.package.*` package); `sonar.tests` is the back end's.
 
 The managed `sonar-project.properties` carries `sonar.externalIssuesReportPaths` (`reports/lint.sonar.json` only) and no `sonar.host.url` (the host is
 `SONAR_HOST_URL`); the managed CI workflow produces the report and runs the scan and the gate action with `!cancelled()`, so a failed lint step still
@@ -117,25 +160,25 @@ clones with its own token rule), so the machine enforces it (R21) and its findin
 
 The gate is `knowledge/sonar-gate.yaml`, the one declaration: the new-code conditions (coverage 100, duplication, blocker and critical issues, hotspots) and an `overall` part (coverage 100, 0 open issues on the whole code,
 every hotspot reviewed, duplicated lines density, cognitive complexity through the S3776 rule). A SonarQube gate condition cannot filter by engine, so the condition counts every
-open issue, imported or native; that is stricter than the three imports alone and is intended. `hfs check` reports `HFS_SONAR_CONFIG` (R11) when the
+open issue, imported or native; that is stricter than the three imports alone and is intended. `starci app check` reports `HFS_SONAR_CONFIG` (R11) when the
 properties file is not its render or the stack declaration names another gate. R20 and R21 have their Sonar enforcers as conditions of that file.
 
-Coverage is the services' alone, from one scope. The managed `test` script is `jest --selectProjects unit --coverage`: it fails below the per-file 100 threshold on `src/**/*.service.ts` and writes `be/coverage/lcov.info` (the jest preset's lcov reporter). The managed `sonar-project.properties` imports that report (`sonar.javascript.lcov.reportPaths=be/coverage/lcov.info`) with `sonar.coverage.inclusions=be/src/**/*.service.ts` and no other coverage key, so a handler, resolver, controller, module, config file or test is not a coverage target and `fe/` is outside coverage. The managed `codecov.yml` holds the same paths at 100 on the project and the patch and ignores `fe/**`; the managed CI workflow uploads the lcov with `codecov/codecov-action` after the unit run. `hfs sync` renders the scope into both files from the installed jest preset's `COVERAGE_SOURCES` (`coverageScope` in `sync/index.mjs`), so they can never drift. The runtime judges the coverage per file: `sonar-local.mjs scan` holds every service a slice touched at 100, and `sonar-local.mjs dashboard` fails a project unless every service is at 100.
+Coverage is the logic of `be/src/modules/**`, from one derivation. `scripts/hfs/coverage-scope.mjs` derives the measured files once from the slot manifest — every `<name>.<role>.ts` of a `ruleParams.be.logicRoles` role inside a slot whose `coverage` is `required` — and `starci app sync` renders it into the three files that state it (R204 `HFS_COVERAGE_SCOPE_DRIFT`): `be/jest.config.js` as `starciJestConfig({ coverage: { roots, roles, excludes } })`, the `sonar.coverage.exclusions` line of `sonar-project.properties` and `codecov.yml`. The managed `test` script is `jest --selectProjects unit --coverage`: it fails below the per-file 100 threshold on the measured files and writes `be/coverage/lcov.info` (the jest preset's lcov reporter). The managed `sonar-project.properties` imports that report (`sonar.javascript.lcov.reportPaths=be/coverage/lcov.info`) with `sonar.coverage.exclusions` set to the complement of the measured files (SonarQube has no coverage inclusions) and no other coverage key, so the feature tier, declaration files, tests and `fe/` are never coverage targets. The managed `codecov.yml` holds the measured roots at 100 on the project and the patch, plus one component per service app and one `platform`, each at 100; the managed CI workflow uploads the lcov with `codecov/codecov-action` after the unit run. The runtime judges the coverage per file: `sonar-local.mjs scan` holds every measured file a slice touched at 100, and `sonar-local.mjs dashboard` fails a project unless every measured file is at 100.
 
-The upload needs the repository secret `CODECOV_TOKEN` (each product monorepo gets its own; the runtime repository's root `.github/workflows/examples.yml` uses the runtime repository's one for the example apps; the owner adds it once per repository: Codecov, the repository's settings, then GitHub Settings > Secrets and variables > Actions > New repository secret `CODECOV_TOKEN`). Without it the step is skipped like the Sonar steps without `SONAR_TOKEN`.
+The upload authenticates with GitHub's OIDC token: the managed `ci.yml` job has `permissions: id-token: write` and the `codecov/codecov-action@v5` step has `use_oidc: true`, so there is no repository secret and no step that skips silently when one is missing (rule CI_UPLOAD_NOT_SILENT). The owner activates the repository on Codecov once.
 
 ## Maintaining the bundle
 
-`runtime/` is a byte copy of the slot loader files, the pins, and the import closure of `scripts/lib/hfs-check.mjs` and
-`scripts/checks/architecture.mjs` (computed by `scripts/sync-runtime.mjs`, so a new import of the machine is bundled without
-editing a list), plus the catalog slice of every code `hfs check` can emit: its own and the machine's (`ARCHITECTURE_RULE_IDS`,
+`runtime/` is a byte copy of the slot loader files, the pins, and the import closure of `scripts/hfs/check.mjs` and
+`scripts/hfs/architecture.mjs` (computed by `scripts/hfs/sync-runtime.mjs`, so a new import of the machine is bundled without
+editing a list), plus the catalog slice of every code `starci app check` can emit: its own and the machine's (`ARCHITECTURE_RULE_IDS`,
 derived from the machine's rule id lists). After changing any of those files, `knowledge/hfs/slots.yaml`,
-`knowledge/hfs/canon-pins.yaml`, `knowledge/patterns/fe/folder.yaml` or the catalog entries of those codes, run `node packages/hfs/scripts/sync-runtime.mjs`;
-`tests/hfs-cli.spec.mjs` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.
+`knowledge/hfs/canon-pins.yaml`, `knowledge/patterns/fe/folder.yaml` or the catalog entries of those codes, run `starci release sync-runtime`;
+`tests/packages-hfs/hfs-cli.spec.mjs` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.
 
-The examples gate `node scripts/checks/check-example-architecture.mjs` runs `hfs lint` of this CLI at the root of every `examples/*`
-app with an `hfs.json` (`examples/todo-app`, `examples/ecommerce-app`) and fails on any finding or any tool that could not run;
-`hfs check` alone would miss the machine's source rules, which the canons judge. It is heavy: run it once, by hand, after `npm ci`
+The examples gate `starci runtime check --only example-architecture` runs `starci app lint` of this CLI at the root of every `examples/*`
+app with an `hfs.json` (each `examples/<app>` root) and fails on any finding or any tool that could not run;
+`starci app check` alone would miss the machine's source rules, which the canons judge. It is heavy: run it once, by hand, after `npm ci`
 in each app.
 
 ## Serving knowledge to other packages

package/emit/contracts.mjs

@@ -1,5 +1,6 @@
 /**
- * `hfs emit-contracts`: writes `contracts/<app>/schema.graphql` for every api app of hfs.json that serves GraphQL, and
+ * `starci app emit`: writes `contracts/<service>/events.json` for every service that declares typed event classes under
+ * `src/modules/events/<service>/` (events.mjs: the async contract, R166), `contracts/<app>/schema.graphql` for every api app of hfs.json that serves GraphQL, and
  * `contracts/<app>/openapi.json` for every api app whose `apps/<app>/src/operations.ts` exports the typed operation table
  * `OPERATIONS` (operations.mjs: OpenAPI 3.1 read from the TypeScript checker; nothing is executed).
  *
@@ -15,15 +16,24 @@
  *
  * TypeScript, Nest and graphql are the repository's own packages; nothing is added to the managed devDependencies. Every app
  * runs in its own child process (`schema-worker.mjs`) because Nest GraphQL's type metadata is process-global.
+ *
+ * An app whose declaration enables the slot `app.supabase.types` (a connection with provider supabase) also gets its generated
+ * Database types written: `supabase/types/database.types.ts` at the app root through `writeDbTypes` (emit/db-types.mjs), the
+ * same `supabase gen types typescript --local` text L09 DB_TYPES_DRIFT regenerates to judge drift. The types are an app-level
+ * artifact, so a redirected `outDir` (the R23 check mode, which emits into a scratch root) does not get them.
  */
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { emitEvents, eventServices, eventsSnapshotPath } from './events.mjs';
 import { openapiPath } from './operations.mjs';
+import { readEnv } from '../runtime/scripts/lib/env.mjs';
+import { appHasDbTypes, writeDbTypes } from './db-types.mjs';
+import { createSlotResolver, loadSlotManifest, locateDeclaration, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
 
 /** The stderr prefix of a dependency the worker could not load and stood in for. */
-export const STAND_IN = 'stand-in ';
+const STAND_IN = 'stand-in ';
 const WORKER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'schema-worker.mjs');
 const OPERATIONS_WORKER = path.join(path.dirname(fileURLToPath(import.meta.url)), 'operations-worker.mjs');
 
@@ -54,10 +64,10 @@ export const snapshotText = (printed) => `${printed.replace(/\n+$/, '')}\n`;
 
 /** Runs one worker of one app; answers its stdout, or null when the app has nothing of that kind (exit 3). */
 function runWorker(worker, repoRoot, app) {
-  const result = spawnSync(process.execPath, [worker, repoRoot, app], { encoding: 'utf8', cwd: repoRoot, env: { PATH: process.env.PATH ?? '' }, maxBuffer: 256 * 1024 * 1024 });
+  const result = spawnSync(process.execPath, [worker, repoRoot, app], { encoding: 'utf8', cwd: repoRoot, env: { PATH: readEnv('PATH') ?? '' }, maxBuffer: 256 * 1024 * 1024 });
   if (result.status === 3) return { text: null, lines: [] };
   const lines = (result.stderr ?? '').split(/\r?\n/).filter(Boolean);
-  if (result.status !== 0) throw new Error(`hfs emit-contracts: ${app} failed (exit ${result.status}): ${(lines.join('\n') || result.stdout).trim()}`);
+  if (result.status !== 0) throw new Error(`starci app emit: ${app} failed (exit ${result.status}): ${(lines.join('\n') || result.stdout).trim()}`);
   return { text: result.stdout, lines: lines.filter((line) => line.startsWith(STAND_IN)) };
 }
 
@@ -68,16 +78,37 @@ function emitApp(repoRoot, app) {
   return { graphql: graphql.text, openapi: operations.text, standIns: [...graphql.lines, ...operations.lines] };
 }
 
+/**
+ * The app-scope slot view of the repository `repoRoot` belongs to: `{ appRoot, resolver }`, or null when no app declaration
+ * resolves there (a bare folder is not an app and emits no types). `repoRoot` is the be side folder, so `locateDeclaration`
+ * answers the app root above it.
+ */
+function appSupabaseScope(repoRoot) {
+  try {
+    const { appRoot } = locateDeclaration(repoRoot);
+    const manifest = loadSlotManifest();
+    return { appRoot, resolver: createSlotResolver(manifest, readRepoDeclaration(manifest, appRoot)) };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Writes the snapshots of every api app: `contracts/<app>/schema.graphql` when it serves GraphQL and `contracts/<app>/openapi.json`
- * when it has an operation table. Answers `{ written: [paths], skipped: [apps], standIns: { app: [lines] } }`, `skipped` being the
- * apps with neither. `declaration` is the parsed hfs.json. `outDir` (absolute) redirects the snapshots to another root, keeping
- * their relative paths.
+ * when it has an operation table. Answers `{ written: [paths], skipped: [apps], standIns: { app: [lines] }, types }`, `skipped`
+ * being the apps with neither. `declaration` is the parsed hfs.json. `outDir` (absolute) redirects the snapshots to another
+ * root, keeping their relative paths.
+ *
+ * On the real write pass (`outDir` is `repoRoot`) the app's Supabase types are written too when the slot `app.supabase.types`
+ * is enabled: `resolver` is the app-scope slot view (built from the declaration at the app root when not passed), `appRoot`
+ * overrides where the types land, and `run` is the command runner `writeDbTypes` spawns `supabase` with. `types` in the answer
+ * is `writeDbTypes`'s `{ path, changed }`, or null for an app without the slot or a redirected pass.
  */
-export function emitContracts({ repoRoot, declaration, outDir = repoRoot }) {
+export function emitContracts({ repoRoot, declaration, outDir = repoRoot, resolver, appRoot, run } = {}) {
   const written = [];
   const skipped = [];
   const standIns = {};
+  let types = null;
   for (const app of apiApps(declaration)) {
     const emitted = emitApp(repoRoot, app);
     if (emitted.graphql === null && emitted.openapi === null) {
@@ -93,5 +124,21 @@ export function emitContracts({ repoRoot, declaration, outDir = repoRoot }) {
     }
     if (emitted.standIns.length) standIns[app] = emitted.standIns;
   }
-  return { written, skipped, standIns };
+  for (const service of eventServices(repoRoot)) {
+    const events = emitEvents({ repoRoot, service });
+    if (events === null) continue;
+    const relative = eventsSnapshotPath(service);
+    const target = path.join(outDir, relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, events);
+    written.push(relative);
+  }
+  // The generated Database types are an app-level artifact of the write pass only: a redirected outDir is the R23 check
+  // mode, and L09 judges drift on the same emitted text through the injected emitTypes (emit/db-types.mjs dbTypesEmitter).
+  if (outDir === repoRoot) {
+    const scope = resolver === undefined ? appSupabaseScope(repoRoot) : { appRoot: locateDeclaration(repoRoot).appRoot, resolver };
+    const target = appRoot ?? scope?.appRoot;
+    if (target !== null && target !== undefined && scope?.resolver != null && appHasDbTypes(scope.resolver)) types = writeDbTypes({ root: target, run });
+  }
+  return { written, skipped, standIns, types };
 }

package/emit/db-types.mjs

@@ -0,0 +1,169 @@
+/**
+ * `supabase/types/database.types.ts` (slot `app.supabase.types`): the Database types the Supabase CLI generates from an app's
+ * local stack, written by `npm run contract:emit` (`starci app emit`) beside the be contract snapshots and judged for drift
+ * by DB_TYPES_DRIFT (L09, scripts/hfs/rules/database.mjs) - the rule compares the committed file with the text `emitTypes()`
+ * produces, and `dbTypesEmitter` below is that callback.
+ *
+ * The text is `supabase gen types typescript --local` run at the app root against the running local stack, narrowed to the
+ * schemas `supabase/config.toml` declares under [api]; the CLI reaches Docker, so nothing here runs inside a check that has
+ * no stack. `run` is the command runner - `(file, args, {cwd})` answering the spawnSync result `{status, stdout, stderr}` -
+ * the default spawns the `supabase` binary with an argument array, never a shell string and never printing env; a spec's fake
+ * keeps Docker out of the suite. A run that cannot produce the text throws DbTypesError (HFS_EMIT_DB_TYPES_FAILED).
+ */
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+
+/** The repository-relative path of the generated types (the path of slot `app.supabase.types`). */
+export const dbTypesPath = 'supabase/types/database.types.ts';
+
+/** The folder of the app's migrations, and the first line of the committed types: the digest of the migrations they were generated from. */
+const MIGRATIONS_DIR = 'supabase/migrations';
+export const TYPES_STAMP = '// migrations-sha256: ';
+
+/**
+ * The sha256 of the app's migrations, hex: every `supabase/migrations/*.sql` by name, each as name, NUL, its text with LF line ends,
+ * NUL. The offline codegen hook of a lite app (templates/app/codegen-lite) computes the same digest and refuses types stamped with another.
+ */
+export function migrationsDigest(root) {
+  const dir = path.join(root, MIGRATIONS_DIR);
+  const hash = createHash('sha256');
+  for (const name of (fs.existsSync(dir) ? fs.readdirSync(dir) : []).filter((file) => file.endsWith('.sql')).sort()) {
+    hash.update(`${name}\0${fs.readFileSync(path.join(dir, name), 'utf8').replace(/\r\n/g, '\n')}\0`);
+  }
+  return hash.digest('hex');
+}
+
+/** The slot that owns the generated types; enabled by a connection declaring provider supabase. */
+const DB_TYPES_SLOT = 'app.supabase.types';
+
+/** The config file whose [api] schemas narrow the generation. */
+const CONFIG_FILE = 'supabase/config.toml';
+const SUPABASE_CLI = 'supabase';
+
+/** A types emit that could not run: the code modules/kernel/failure-codes.yaml catalogues as HFS_EMIT_DB_TYPES_FAILED. */
+class DbTypesError extends Error {
+  constructor(message, details = {}) {
+    super(`HFS_EMIT_DB_TYPES_FAILED: ${message}`);
+    this.name = 'DbTypesError';
+    this.code = 'HFS_EMIT_DB_TYPES_FAILED';
+    this.details = details;
+  }
+}
+
+const spawn = (file, args, options = {}) => spawnSync(file, args, { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024, ...options });
+const PINS_FILE = new URL('../runtime/knowledge/hfs/canon-pins.yaml', import.meta.url);
+
+/**
+ * The one spawn: an argument array, a hidden window, a bound buffer, never a shell. Specs inject a fake of the same shape. The
+ * `supabase` binary is the one on PATH; a machine without it runs the CLI at the canon pin through npx (the pin of knowledge/hfs/canon-pins.yaml).
+ */
+const withNpxFallback = (run, platform) => (file, args, options = {}) => {
+  const first = run(file, args, options);
+  if (file !== SUPABASE_CLI || first.error?.code !== 'ENOENT') return first;
+  const version = parseYaml(fs.readFileSync(PINS_FILE, 'utf8'))?.pins?.[SUPABASE_CLI]?.version;
+  if (!version) return first;
+  return platform === 'win32'
+    ? run('cmd.exe', ['/d', '/s', '/c', 'npx', '--yes', `${SUPABASE_CLI}@${version}`, ...args], options)
+    : run('npx', ['--yes', `${SUPABASE_CLI}@${version}`, ...args], options);
+};
+
+/** The first meaningful line of a failure output, for the error a human acts on. */
+const firstLine = (text) => String(text ?? '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean)[0];
+
+/**
+ * The schemas `supabase/config.toml` exposes under [api] (`[]` when the file or the list is absent - the CLI then reads its
+ * own defaults). A config that does not parse is a refusal: L08 reads the same file and the emit must not guess.
+ */
+function apiSchemas(root) {
+  const file = path.join(root, CONFIG_FILE);
+  if (!fs.existsSync(file)) return [];
+  let toml;
+  try { toml = parseToml(fs.readFileSync(file, 'utf8')); } catch (error) {
+    throw new DbTypesError(`${CONFIG_FILE} is not readable valid TOML (${firstLine(error?.message ?? error) ?? 'unreadable'}); the types scope comes from its [api] schemas`, { file: CONFIG_FILE });
+  }
+  return (toml?.api?.schemas ?? []).filter((schema) => typeof schema === 'string');
+}
+
+/**
+ * The freshly generated text of `dbTypesPath` for the app at `root`: `supabase gen types typescript --local` (the running
+ * local stack), narrowed to the [api] schemas of supabase/config.toml. A failing CLI, a spawn error and an empty answer all
+ * raise DbTypesError; the first stderr line names the cause.
+ */
+function emitDbTypesWithRunner({ root, run }) {
+  const schemas = apiSchemas(root);
+  const args = ['gen', 'types', 'typescript', '--local', ...(schemas.length ? ['--schema', schemas.join(',')] : [])];
+  const command = `${SUPABASE_CLI} ${args.join(' ')}`;
+  let result;
+  try {
+    result = run(SUPABASE_CLI, args, { cwd: root });
+  } catch (error) {
+    throw new DbTypesError(`\`${command}\` could not run: ${firstLine(error?.message ?? error) ?? 'unknown failure'}; the local Supabase stack must be up (supabase start)`, { file: dbTypesPath });
+  }
+  const stdout = String(result?.stdout ?? '');
+  const stderr = String(result?.stderr ?? '');
+  if (result?.error || result?.status !== 0 || !stdout.trim()) {
+    const cause = firstLine(stderr) ?? firstLine(result?.error?.message ?? result?.error) ?? 'no output';
+    throw new DbTypesError(`\`${command}\` failed${result?.status !== undefined && result?.status !== null ? ` (exit ${result.status})` : ''}: ${cause}; the local Supabase stack must be up (supabase start)`, { file: dbTypesPath, stderr });
+  }
+  return `${TYPES_STAMP}${migrationsDigest(root)}\n${stdout}`;
+}
+
+export function emitDbTypes({ root, run = spawn, platform = process.platform } = {}) {
+  return emitDbTypesWithRunner({ root, run: withNpxFallback(run, platform) });
+}
+
+/**
+ * The types of an app that has no stack yet (a fresh scaffold): start the app's own local stack (its project id and ports from
+ * supabase/config.toml; every migration of supabase/migrations is applied on start), emit the types, and stop the stack again when
+ * this call started it. The slow, Docker-reaching path `starci app scaffold --edition lite` takes; `emitDbTypes` alone is the fast one for a stack that is up.
+ */
+export function generateDbTypes({ root, run = spawn, platform = process.platform } = {}) {
+  const execute = withNpxFallback(run, platform);
+  const started = execute(SUPABASE_CLI, ['start', '-x', 'studio,mailpit,logflare,vector,edge-runtime,imgproxy,supavisor'], { cwd: root });
+  const already = /already (?:running|started)/i.test(`${started?.stderr ?? ''}${started?.stdout ?? ''}`);
+  if (started?.error || (started?.status !== 0 && !already)) {
+    throw new DbTypesError(`\`${SUPABASE_CLI} start\` failed${started?.status != null ? ` (exit ${started.status})` : ''}: ${firstLine(started?.stderr) ?? firstLine(started?.error?.message ?? started?.error) ?? 'no output'}; Docker must be running`, { file: dbTypesPath });
+  }
+  try {
+    return emitDbTypesWithRunner({ root, run: execute });
+  } finally {
+    if (!already) execute(SUPABASE_CLI, ['stop', '--no-backup'], { cwd: root });
+  }
+}
+
+/**
+ * Writes `emitDbTypes` to `<root>/<dbTypesPath>`, creating `supabase/types/` when needed. Answers `{ path, changed }`:
+ * `changed` is false when the committed text already equals the generated one, so a re-run is a no-op on disk.
+ */
+export function writeDbTypes({ root, run } = {}) {
+  const text = emitDbTypes({ root, run });
+  const target = path.join(root, dbTypesPath);
+  const committed = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+  const changed = committed !== text;
+  if (changed) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, text);
+  }
+  return { path: dbTypesPath, changed };
+}
+
+/**
+ * Whether the slot `app.supabase.types` is enabled for the app `resolver` views (a connection of the app declares
+ * provider: supabase). Read through the slot view, never through a path check: a side-scope resolver holds no app slots
+ * and answers false, exactly like an app without a supabase connection.
+ */
+export function appHasDbTypes(resolver) {
+  const slot = typeof resolver?.slot === 'function' ? resolver.slot(DB_TYPES_SLOT) : null;
+  return slot != null && typeof resolver?.slotEnabled === 'function' && resolver.slotEnabled(slot) === true;
+}
+
+/**
+ * The `emitTypes` callback checkDatabase (L09 DB_TYPES_DRIFT) expects: `({repoRoot, declaration}) -> text`, `repoRoot`
+ * being the app root under check; the bound `root` is the fallback for a caller that already knows it. The declared
+ * `supabase` block plays no part: the schemas come from supabase/config.toml on disk.
+ */
+export const dbTypesEmitter = ({ root = null, run } = {}) => async ({ repoRoot } = {}) => emitDbTypes({ root: repoRoot ?? root, run });