@starci/hfs 4.7.12 → 4.7.14

package/release/lint-report.mjs

@@ -0,0 +1,52 @@
+// lint-report.mjs - the external issues report the release gate's sonar row produces before it runs the scanner.
+// The app declares `sonar.externalIssuesReportPaths=reports/lint.sonar.json`; the managed CI makes it with `lint --side <side> --sonar reports/lint.<side>.sonar.json`
+// per lint matrix side and a "merge Sonar lint reports" step. This module does the same locally, through the same process seam as every gate
+// (an argument array through ctx.spawn, never a shell). The merge below is the one in packages/hfs/sync/ci-commands.mjs (sonarMergeSteps): keep them identical.
+import fs from 'node:fs';
+import path from 'node:path';
+import { firstLine, tool } from '../stack/context.mjs';
+
+const LINT_SIDES = ['be', 'fe'];
+const MERGED_REPORT = 'reports/lint.sonar.json';
+const sideReport = (side) => `reports/lint.${side}.sonar.json`;
+
+/** CI merge: rules unique by id (last one wins, first position kept), issues concatenated in side order. */
+function mergeSonarReports(reports) {
+  const rules = [...new Map(reports.flatMap((report) => report.rules).map((rule) => [rule.id, rule])).values()];
+  const issues = reports.flatMap((report) => report.issues);
+  return { rules, issues };
+}
+
+/** The sides the app has: a be/ or fe/ folder beside the app root. */
+const sidesOf = (root) => LINT_SIDES.filter((side) => fs.existsSync(path.join(root, side)));
+
+/**
+ * Runs `starci app lint --side <side> --sonar <file>` for every side the app has, then writes reports/lint.sonar.json.
+ * `launch` turns an argv into [command, args] for the platform. Returns { pass, text }: the honest log of every lint run and the verdict.
+ * A lint that exits non-zero (findings or error) or writes no report fails the row; nothing is skipped.
+ */
+export function produceLintReports(ctx, { launch, platform, env }) {
+  const sides = sidesOf(ctx.cwd);
+  const out = [];
+  if (sides.length === 0) return { pass: false, text: `no be/ or fe/ side in ${ctx.cwd}: cannot produce ${MERGED_REPORT}\n` };
+  fs.mkdirSync(path.join(ctx.cwd, 'reports'), { recursive: true });
+  for (const side of sides) {
+    const file = path.join(ctx.cwd, sideReport(side));
+    fs.rmSync(file, { force: true });
+    const argv = ['npx', 'starci', 'app', 'lint', '--side', side, '--sonar', sideReport(side)];
+    const [command, args] = launch(argv, platform);
+    out.push(`$ ${argv.join(' ')}\n`);
+    const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
+    out.push(`${run.stdout ?? ''}${run.stderr ?? ''}`);
+    if (run.error) return { pass: false, text: `${out.join('')}\nlint ${side} cannot run (${run.error.message})\n` };
+    if (run.status !== 0) return { pass: false, text: `${out.join('')}\nlint ${side} failed: exit ${run.status}; the scanner was not run\n` };
+    if (!fs.existsSync(file)) return { pass: false, text: `${out.join('')}\nlint ${side} wrote no ${sideReport(side)}; the scanner was not run\n` };
+  }
+  try {
+    const reports = sides.map((side) => JSON.parse(fs.readFileSync(path.join(ctx.cwd, sideReport(side)), 'utf8')));
+    fs.writeFileSync(path.join(ctx.cwd, MERGED_REPORT), `${JSON.stringify(mergeSonarReports(reports), null, 2)}\n`);
+  } catch (error) {
+    return { pass: false, text: `${out.join('')}\ncannot merge the side reports: ${firstLine(error.message)}\n` };
+  }
+  return { pass: true, text: `${out.join('')}\nwrote ${MERGED_REPORT} from ${sides.map(sideReport).join(', ')}\n\n` };
+}

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

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.18
+    version: 3.4.22
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.18
+    version: 8.4.21
     group: starci
     install: registry
     side: fe
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.12
+    version: 1.7.14
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.12
+    version: 4.7.14
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/ci-standard.yaml

@@ -27,7 +27,7 @@ defaults:
 # The steps that need a raised Node heap on the GitHub runner, matched on their `run` text, and the least heap they must declare in NODE_OPTIONS.
 heap:
   minMiB: 6144
-  steps: ['npm run typecheck', 'npm run lint', 'app lint', 'app check --coverage-from']
+  steps: ['npm run typecheck', 'npm run lint', 'app lint', 'app check --coverage-from', 'npm run db:lint']
 
 items:
   - id: candidate-trigger

package/runtime/knowledge/hfs/rules.yaml

@@ -19,7 +19,7 @@
 schema: starci/hfs-rules@3
 version: 3.1.0
 gates:
-  pre-commit: the managed .husky/pre-commit at the app root - starci app hygiene (staged .starciwork and .starcistacks paths, secrets guard), typecheck, ESLint per side and stylelint on the staged files, prettier --check, the unit specs the staged files touch
+  pre-commit: the managed .husky/pre-commit at the app root - starci app hygiene (staged .starciwork and .starcistacks paths, secrets guard, a new back-end logic file staged without its unit spec), typecheck, ESLint per side and stylelint on the staged files, prettier --check, the unit specs the staged files touch
   pre-push: typecheck, lint (starci app lint), format:check and the unit specs affected since origin/main; runs every pre-commit rule again
   settle: the op gate `starci gate run` over the op's changed files (merge guard, starci app lint --changed, codegen, tsc, the slice's specs; only findings new against the workflow's previous checkpoint block), re-read at starci kernel settle, which refuses a red done; a green settle commits the op's checkpoint on wf-<workflowId>
   land: the workflow's finish, the only time main is touched - gate.mjs over the whole workflow branch against its merge-base with main, the merge guard, review.verify of the exact head that lands, the branch rebased onto main, then main fast-forwarded and pushed
@@ -205,10 +205,10 @@ rules:
       - {path: packages/hfs/templates/app/ci-workflows, edition: full}
     witness: {status: unreachable, reason: "owner:no-runtime-specs (2026-10-17): the mutation witness was a deleted runtime spec or fixture", date: "2026-10-17"}
     code: "HFS_CI_MISSING_CANON"
-    law: "CI runs the pinned `starci app lint` (`npm run lint`), and a clone never redirects `core.hooksPath` away from husky."
+    law: "CI runs the pinned `starci app lint` (`npm run lint`), a clone never redirects `core.hooksPath` away from husky, and the folder a set `core.hooksPath` names holds the installed hooks in every checkout (husky's dispatcher in `.husky/_`), so no commit lands without the pre-commit gate."
     kinds: [check, codemod]
     gates: [land, ci]
-    failureCodes: ["HFS_CI_MISSING_CANON", "HFS_HOOKS_PATH_REDIRECTED"]
+    failureCodes: ["HFS_CI_MISSING_CANON", "HFS_HOOKS_PATH_REDIRECTED", "HFS_HOOKS_NOT_INSTALLED"]
     enforcers:
       - {kind: machine, id: hooks-path-not-redirected, at: scripts/hfs/architecture/hfs.mjs}
       - {kind: hfs, id: ci-missing-canon, at: scripts/hfs/rules/pipeline.mjs}
@@ -846,12 +846,13 @@ rules:
     exemplifiedBy:
       - {path: packages/hfs/templates/be/inbox/service.spec.ts.tpl, editions: [lite, full]}
     witness: {status: unreachable, reason: "owner:no-runtime-specs (2026-10-17): the mutation witness was a deleted runtime spec or fixture", date: "2026-10-17"}
-    law: "One jest config, projects `unit`, `integration`, `e2e` and `contract`, live by folder, `diagnostics: false`; unit specs are `<name>.<role>.spec.ts` beside the file they test: required for the roles of `ruleParams.be.unitRoles` (`<name>.service.spec.ts` beside a `<name>.service.ts`, `<name>.cli.spec.ts` beside a cli command `<name>.cli.ts` of `src/features/cli`), optional for any other logic role (`ruleParams.be.logicRoles`) inside a slot whose `coverage` is required, and nowhere else but beside a webhook or realtime door that has no service of its own (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<x>.subscription.spec.ts`) (every unit-tested subject has exactly one; any other `*.spec.ts` outside `be/src/tests/{world,integration,e2e,contract}` is a finding, including specs in apps), and the unit project collects coverage from the logic roles of the measured roots only (the scope derived from the slot manifest, R204) with a per-file threshold of 100 on lines, branches, functions and statements (`test` runs `--coverage`; `importHelpers` and `tslib`); `be/src/tests/world/` is the ONLY test infrastructure: `global-setup.ts` starts the app's own stack (`.starcistacks/<env>`, named by `stack` in `test-world.config.ts`, the declaration of the test-world library in its one named form `export const { useTestWorld, useSandbox } = defineTestWorld({...})` (a default export is not read): every service it declares runs REAL, behind toxiproxy, images and versions read from the stack at run time, never spelled in test source) or attaches to a warm one that answers, and runs the migrations once over the cli app's connections (the runner of the cli migrate command); `global-teardown.ts` stops only what its setup started; `use-test-world.ts` exports `useTestWorld({ apps } | { modules })` (`world.apps.<name>.api`, `world.db.<connection>`, `world.infra.<service>` with `latency(ms)`, `cut()` and `restore()` on the real service, `world.fake.<provider>`, `world.waitFor`) and `fakes/<provider>/` holds the network-edge fakes (`failNext`, `replayWebhook`, `delay`, payload fixtures) of external SaaS the team does not operate ONLY: a fake of a service the stack declares is refused, except stateless compute that needs special hardware or an external model (GPU inference, a self-hosted embedding model), whose `stacks` entry in `test-world.config.ts` declares `{ fakedBy: <fake>, reason }` with a non-empty `reason` (a stateful service, or one with a persistent volume, is never accepted); it alone owns containers, DataSource, migrations and `process.env`; nothing under `be/src/tests` overrides a provider or DI token; `be/src/tests/integration/<capability>/*.integration-spec.ts` (`{ modules }`, with the real peer apps its client calls beside them as `apps`; real infrastructure, no HTTP door of ours), `be/src/tests/e2e/<area>/*.e2e-spec.ts` (`{ apps }`) and `be/src/tests/contract/<provider>/*.contract-spec.ts` (provider sandboxes, skipped without sandbox config, run only by `test:contract`, never by `test` or `test:e2e`) agree folder with suffix; an integration or e2e spec passes `useTestWorld` one object literal with plain keys (no variable, spread or computed key) and calls it; the contract layer skips only through the test-world library's `useSandbox(...)` when the sandbox config is absent (`sandbox.describe(...)`), and every `fakes/<provider>/` that serves payload fixtures (`payloads/*.json`) has a `contract/<provider>/*.contract-spec.ts` that references those fixtures and asserts `shapeOf(real)` equals `shapeOf(fixture)` (the helper `shapeOf` is named by `ruleParams.be.contractShape` of the slot manifest; fakes the test-world library provides are guarded by the library); no `.test.ts`, `int-spec` or `harness-spec`, no `live/` and no `be/src/tests/e2e/world`."
+    law: "One jest config, projects `unit`, `integration`, `e2e` and `contract`, live by folder, `diagnostics: false`; unit specs are `<name>.<role>.spec.ts` beside the file they test: required for the roles of `ruleParams.be.unitRoles` (`<name>.service.spec.ts` beside a `<name>.service.ts`, `<name>.cli.spec.ts` beside a cli command `<name>.cli.ts` of `src/features/cli`), optional for any other logic role (`ruleParams.be.logicRoles`) inside a slot whose `coverage` is required, except that the commit adding a measured logic file stages its `<name>.<role>.spec.ts` beside it (owner 2026-10-20, judged by `starci app hygiene` in the pre-commit hook), and nowhere else but beside a webhook or realtime door that has no service of its own (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<x>.subscription.spec.ts`) (every unit-tested subject has exactly one; any other `*.spec.ts` outside `be/src/tests/{world,integration,e2e,contract}` is a finding, including specs in apps), and the unit project collects coverage from the logic roles of the measured roots only (the scope derived from the slot manifest, R204) with a per-file threshold of 100 on lines, branches, functions and statements (`test` runs `--coverage`; `importHelpers` and `tslib`); `be/src/tests/world/` is the ONLY test infrastructure: `global-setup.ts` starts the app's own stack (`.starcistacks/<env>`, named by `stack` in `test-world.config.ts`, the declaration of the test-world library in its one named form `export const { useTestWorld, useSandbox } = defineTestWorld({...})` (a default export is not read): every service it declares runs REAL, behind toxiproxy, images and versions read from the stack at run time, never spelled in test source) or attaches to a warm one that answers, and runs the migrations once over the cli app's connections (the runner of the cli migrate command); `global-teardown.ts` stops only what its setup started; `use-test-world.ts` exports `useTestWorld({ apps } | { modules })` (`world.apps.<name>.api`, `world.db.<connection>`, `world.infra.<service>` with `latency(ms)`, `cut()` and `restore()` on the real service, `world.fake.<provider>`, `world.waitFor`) and `fakes/<provider>/` holds the network-edge fakes (`failNext`, `replayWebhook`, `delay`, payload fixtures) of external SaaS the team does not operate ONLY: a fake of a service the stack declares is refused, except stateless compute that needs special hardware or an external model (GPU inference, a self-hosted embedding model), whose `stacks` entry in `test-world.config.ts` declares `{ fakedBy: <fake>, reason }` with a non-empty `reason` (a stateful service, or one with a persistent volume, is never accepted); it alone owns containers, DataSource, migrations and `process.env`; nothing under `be/src/tests` overrides a provider or DI token; `be/src/tests/integration/<capability>/*.integration-spec.ts` (`{ modules }`, with the real peer apps its client calls beside them as `apps`; real infrastructure, no HTTP door of ours), `be/src/tests/e2e/<area>/*.e2e-spec.ts` (`{ apps }`) and `be/src/tests/contract/<provider>/*.contract-spec.ts` (provider sandboxes, skipped without sandbox config, run only by `test:contract`, never by `test` or `test:e2e`) agree folder with suffix; an integration or e2e spec passes `useTestWorld` one object literal with plain keys (no variable, spread or computed key) and calls it; the contract layer skips only through the test-world library's `useSandbox(...)` when the sandbox config is absent (`sandbox.describe(...)`), and every `fakes/<provider>/` that serves payload fixtures (`payloads/*.json`) has a `contract/<provider>/*.contract-spec.ts` that references those fixtures and asserts `shapeOf(real)` equals `shapeOf(fixture)` (the helper `shapeOf` is named by `ruleParams.be.contractShape` of the slot manifest; fakes the test-world library provides are guarded by the library); no `.test.ts`, `int-spec` or `harness-spec`, no `live/` and no `be/src/tests/e2e/world`."
     kinds: [check, codemod, lint]
     gates: [land, ci]
-    failureCodes: ["BE_TEST_TOPOLOGY", "BE_CONTRACT_UNGUARDED"]
+    failureCodes: ["BE_TEST_TOPOLOGY", "BE_CONTRACT_UNGUARDED", "BE_UNIT_SPEC_NOT_STAGED"]
     enforcers:
       - {kind: hfs, id: test-topology, at: scripts/hfs/rules/test-topology.mjs}
+      - {kind: hfs, id: staged-spec-presence, at: scripts/hfs/rules/staged-specs.mjs}
       - {kind: machine, id: test-kind-unsupported, at: scripts/hfs/architecture/hfs.mjs}
       - {kind: eslint-be, id: test-world-files}
       - {kind: machine, id: contract-fixture-guard, at: scripts/hfs/architecture/contract-fixture-guard.mjs}
@@ -2710,7 +2711,7 @@ rules:
       - {path: packages/hfs/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml, edition: lite}
       - {path: packages/hfs/templates/app/skeleton/.starcistacks/application-stacks.yaml, edition: full}
     witness: {status: unreachable, reason: "owner:no-runtime-specs (2026-10-17): the mutation witness was a deleted runtime spec or fixture", date: "2026-10-17"}
-    law: "Every api or worker app `be/apps/<service>` of a product with more than one service is a component of the same name with `role: service` in `.starcistacks/application-stacks.yaml`."
+    law: "Every api or worker app `be/apps/<service>` of a product with more than one service is a `role: service` component in `.starcistacks/application-stacks.yaml`: the component of the same name, or one whose `environments.<env>.deploy.images.<component>.app` names the app."
     kinds: [check]
     gates: [land, ci]
     failureCodes: ["HFS_SERVICE_STACK_DECLARATION"]

package/runtime/knowledge/patterns/be/cli.yaml

@@ -133,6 +133,7 @@ rules:
         - BE_CLI_COMMAND_SHAPE
         - BE_TEST_TOPOLOGY
         - BE_CONTRACT_UNGUARDED
+        - BE_UNIT_SPEC_NOT_STAGED
         - BE_SPEC_PLACEMENT
         - BE_FEATURE_THIN
       manual:

package/runtime/knowledge/patterns/be/realtime.yaml

@@ -76,6 +76,7 @@ rules:
         - HFS_README_BADGE_NOT_LIVE
         - BE_TEST_TOPOLOGY
         - BE_CONTRACT_UNGUARDED
+        - BE_UNIT_SPEC_NOT_STAGED
         - BE_REALTIME_SHAPE
       manual:
         - Confirm no query or mutation lives in a subscription door; it lives in an api feature.

package/runtime/knowledge/patterns/be/webhooks.yaml

@@ -82,6 +82,7 @@ rules:
         - HFS_README_BADGE_NOT_LIVE
         - BE_TEST_TOPOLOGY
         - BE_CONTRACT_UNGUARDED
+        - BE_UNIT_SPEC_NOT_STAGED
       manual:
         - Confirm the provider endpoint is one door and that a second endpoint of the same provider is a second door only when it has a different proof.
     relatedExamples: [webhooks]

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

@@ -1605,6 +1605,17 @@ BE_TYPE_ESCAPE:
   owner: op-retry
   kind: check-finding
 
+BE_UNIT_SPEC_NOT_STAGED:
+  title: "A new back-end logic file is committed without its unit spec"
+  title_vi: "Tệp logic back-end mới được commit mà không có unit spec"
+  meaning_vi: "Commit thêm `<file>`, một tệp `<name>.<role>.ts` có vai trò logic mà unit coverage đo ở mức 100 mỗi tệp, nhưng index không có `<name>.<role>.spec.ts` bên cạnh nó: mã được viết trước, spec để sau."
+  causes_vi:
+    - "Agent viết mã trước rồi định sửa lint và spec sau, thay vì chạy vòng op `starci gate read` → mã + spec → `starci gate run`"
+    - "Spec đã viết nhưng chưa được stage cùng tệp"
+  nextStep_vi: "Viết `<name>.<role>.spec.ts` bên cạnh tệp trong cùng thay đổi, chạy `starci gate run --root <app> --changed <files> --tests <pattern>`, rồi stage cả hai tệp và commit lại qua hook. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không thêm ngoại lệ."
+  owner: op-retry
+  kind: check-finding
+
 BE_UNNAMED_DATA_ACCESS:
   title: "Database reached without the named shared EntityManager"
   title_vi: "Truy cập cơ sở dữ liệu không qua EntityManager dùng chung có tên"
@@ -3475,6 +3486,17 @@ HFS_GITIGNORE_BLOCK_DRIFT:
   owner: op-retry
   kind: check-finding
 
+HFS_HOOKS_NOT_INSTALLED:
+  title: "The hooks folder core.hooksPath names is missing or empty in this checkout"
+  title_vi: "Hook Git chưa được cài trong bản checkout này"
+  meaning_vi: "`core.hooksPath` trỏ tới `.husky/_` (hoặc `.husky`) nhưng thư mục đó không tồn tại hoặc không có hook đã cài (không có tệp điều phối `h` của husky) trong bản checkout này, nên Git không chạy pre-commit và pre-push: mọi commit bỏ qua lint và spec. Một worktree dùng chung cấu hình Git của clone chính nhưng `.husky/_` chỉ được husky tạo ở nơi đã cài phụ thuộc có chạy lifecycle script."
+  causes_vi:
+    - "Cài phụ thuộc với `--ignore-scripts` nên script `prepare` (husky) không chạy"
+    - "Worktree mới tạo chưa từng chạy husky; runtime chỉ ghi hook riêng của nó vào `.husky/_`"
+  nextStep_vi: "Chạy `starci npm ci` ở gốc app (lệnh này chạy trình cài hook husky `prepare` của app kể cả khi lifecycle script bị bỏ qua), rồi commit lại qua hook; không dùng `--no-verify`. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra."
+  owner: op-retry
+  kind: check-finding
+
 HFS_HOOKS_PATH_REDIRECTED:
   title: "A clone redirects core.hooksPath away from husky"
   title_vi: "core.hooksPath bị đổi hướng khỏi husky"
@@ -3962,10 +3984,10 @@ HFS_SERVICE_ROLE_SCOPE:
 HFS_SERVICE_STACK_DECLARATION:
   title: "Each service app is a service component of the stack"
   title_vi: "Ứng dụng dịch vụ chưa được khai báo trong stack"
-  meaning_vi: "Một ứng dụng api hoặc worker dưới `be/apps/<service>/` của sản phẩm nhiều dịch vụ không có thành phần `role: service` cùng tên trong `.starcistacks/application-stacks.yaml`."
+  meaning_vi: "Một ứng dụng api hoặc worker dưới `be/apps/<service>/` của sản phẩm nhiều dịch vụ không có thành phần `role: service` trong `.starcistacks/application-stacks.yaml`: không có thành phần cùng tên, và không có thành phần nào được `environments.<env>.deploy.images.<component>.app` gắn với ứng dụng đó."
   causes_vi:
     - "Vi phạm luật R165: mọi dịch vụ của sản phẩm nhiều dịch vụ là một thành phần `role: service` của stack (image riêng `<repo>/<service>:<x.y.z>`, build từ Dockerfile của app)."
-  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: thêm thành phần cùng tên app (role service, image đã ghim, file compose và cổng của môi trường)."
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: thêm thành phần cùng tên app (role service, image đã ghim, file compose và cổng của môi trường), hoặc gắn thành phần dịch vụ đang chạy với app qua `environments.<env>.deploy.images.<component>.app` thay vì đổi tên dịch vụ."
   owner: op-retry
   kind: check-finding
 

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "8913c2eedad972f96410ed412622ca511f32f9a4f2b5fb8104b745e310007ac5",
+  "hash": "1ac457c26ee05922e910a56fab64d9bdc9b0bc251466dd4a2f341bf698ff3e73",
   "global": [
     {
       "name": "json",
@@ -1039,7 +1039,7 @@ export const CATALOG = {
           "runtimeSide": "host"
         },
         "hygiene": {
-          "summary": "judge staged worktree metadata, stack files and plaintext secrets",
+          "summary": "judge staged worktree metadata, stack files, plaintext secrets and new logic files without a spec",
           "owner": "@starci/hfs",
           "flags": [],
           "exit": {
@@ -7872,7 +7872,7 @@ export const CATALOG = {
           ],
           "exit": {
             "0": "the clean lockfile was installed",
-            "1": "npm or the host lock failed",
+            "1": "npm, the host lock or the git hooks install failed",
             "2": "the worktree or install state was refused"
           },
           "json": "starci/npm-ci@1",
@@ -7898,7 +7898,10 @@ export const CATALOG = {
           "conventions": [
             "npm ci installs the lockfile into this worktree's real node_modules and never uses a junction or symbolic link",
             "package.json and package-lock.json must be clean before the run",
-            "dependency installs run one at a time under the host lock and never use npm install"
+            "dependency installs run one at a time under the host lock and never use npm install",
+            "after an install, a core.hooksPath naming a missing or empty folder runs the root husky prepare (npm run prepare), lifecycle scripts ignored or not",
+            "the receipt's hooks field reports the git hooks as installed, repaired, not-set or not-declared",
+            "a hooks path still naming a missing or empty folder after the installer ran fails the verb"
           ],
           "runtimeSide": "host"
         },
@@ -7926,7 +7929,7 @@ export const CATALOG = {
           ],
           "exit": {
             "0": "exact dependencies and any requested canon pins were installed",
-            "1": "npm, Git, target canon loading or the host lock failed",
+            "1": "npm, Git, target canon loading, the host lock or the git hooks install failed",
             "2": "the package, target pin or worktree was refused"
           },
           "json": "starci/npm-install@1",
@@ -7958,7 +7961,10 @@ export const CATALOG = {
             "target pins never fall back to the running runtime when the target pin file is missing or inconsistent",
             "each target StarCi pin is reported as moved (with its workspace), skipped when no package.json declares it, or refused with a reason",
             "a failed canon phase exits nonzero even when the first CLI install succeeded",
-            "installs always use --save-exact and report the package.json and package-lock.json diff stat"
+            "installs always use --save-exact and report the package.json and package-lock.json diff stat",
+            "after an install, a core.hooksPath naming a missing or empty folder runs the root husky prepare (npm run prepare), lifecycle scripts ignored or not",
+            "the receipt's hooks field reports the git hooks as installed, repaired, not-set or not-declared",
+            "a hooks path still naming a missing or empty folder after the installer ran fails the verb"
           ],
           "runtimeSide": "host"
         }

package/runtime/scripts/hfs/architecture/canon-clones.mjs

@@ -106,7 +106,7 @@ function queueMethods(env, declaration, constructor, excluded) {
     && decoratorsHave(env, parameter, 'InjectQueueOutbox', '@modules/platform/queue'));
   if (!outbox || !env.ts.isIdentifier(outbox.name)) return;
   for (const method of declaration.members) {
-    if (!env.ts.isMethodDeclaration(method) || !method.body || method.body.statements.length !== 1) continue;
+    if (!env.ts.isMethodDeclaration(method) || method.body?.statements.length !== 1) continue;
     const call = statementCall(env.ts, method.body.statements[0]);
     if (call && env.ts.isCallExpression(call) && receiverMember(env.ts, call) === outbox.name.text && call.expression.name.text === 'write'
       && call.arguments.length === 3 && call.arguments.every(argument => mapping(env, argument))) excluded.add(method);

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

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { lsFiles } from '../../api/git/ls-files.mjs'; import { revParseQuery } from '../../api/git/rev-parse-query.mjs'; import { configGet } from '../../api/git/config-get.mjs'; import { gitOutputOf } from '../../lib/git.mjs';
 import { braceVariants } from '../../lib/glob.mjs';
+import { hooksDirState } from '../../lib/git-hooks-dir.mjs';
 import { createSlotResolver, loadSlotManifest, openHfs } from '../slots.mjs';
 import { isFeTestPath } from '../rules/fe-no-tests.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
@@ -21,6 +22,7 @@ export const HFS_RULE_IDS = [
   'HFS_APPS_REQUIRED',
   'HFS_APP_LAYOUT_INVALID',
   'HFS_E2E_IN_AUTOMATIC_GATE',
+  'HFS_HOOKS_NOT_INSTALLED',
   'HFS_HOOKS_PATH_REDIRECTED',
   'HFS_MODULE_TIER_INVALID',
   'HFS_PACKAGE_MANAGER_MIXED',
@@ -114,15 +116,28 @@ function ownsGitTopLevel(root) {
   }
 }
 
-/** A directory that is not the top level of its own work tree has no hooks of its own: the check is not applicable there. */
+/**
+ * The hooks of the checked root: core.hooksPath stays husky's (HFS_HOOKS_PATH_REDIRECTED), and the folder it names holds
+ * installed hooks in this checkout (HFS_HOOKS_NOT_INSTALLED, scripts/lib/git-hooks-dir.mjs). An unset key judges nothing: a CI
+ * checkout installs without hooks. A directory that is not the top level of its own work tree has no hooks of its own: the
+ * check is not applicable there.
+ */
 function hooksPathNotRedirected({ root, finding }) {
   if (!ownsGitTopLevel(root)) return { status: 'not-applicable', reason: 'the checked root is not the top level of its own Git work tree, so it has no hooks of its own' };
   const set = configGet(root, 'core.hooksPath', { local: true });
   if (!set.ok) return { status: 'checked' }; // key not set: nothing is redirected
-  const value = set.stdout;
-  if (value && !HUSKY_HOOKS_PATH.test(value.replaceAll('\\', '/')))
+  const value = String(set.stdout ?? '').trim();
+  if (!value) return { status: 'checked' };
+  if (!HUSKY_HOOKS_PATH.test(value.replaceAll('\\', '/'))) {
     finding('HFS_HOOKS_PATH_REDIRECTED', '.git/config', `core.hooksPath is set to ${value} in this clone. Unset it (git config --local --unset core.hooksPath) and let husky own the hooks; a redirected path skips the pre-commit and pre-push gates.`);
-  return { status: 'checked' };
+    return { status: 'checked' };
+  }
+  const hooks = hooksDirState(root, value);
+  if (hooks.state !== 'installed') {
+    const what = { missing: 'does not exist', empty: 'holds no installed hook (husky never ran here)', unreadable: `cannot be read (${hooks.error})` }[hooks.state];
+    finding('HFS_HOOKS_NOT_INSTALLED', value, `core.hooksPath is ${value}, but that folder ${what} in this checkout, so git runs no pre-commit or pre-push gate and a commit skips lint and specs. Install the hooks before committing: run \`starci npm ci\` at the app root (it runs the app's hook installer \`npm run prepare\` even when lifecycle scripts are ignored), or \`npm run prepare\`; an install with --ignore-scripts alone never installs them.`);
+  }
+  return { status: 'checked', hooks: hooks.state };
 }
 
 /** The tracked paths under the given root, relative to it: the pathspec keeps a nested directory from listing the paths of its enclosing clone. */

package/runtime/scripts/hfs/architecture/i18n-keys.mjs

@@ -62,11 +62,13 @@ function catalogsPerApp(config, graph) {
 
 /** Each interpolation can fill part or all of a segment; the template's static fragments keep their literal spelling. */
 function templatePatternOf(node) {
-  return [node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').split('.').map(segment => {
-    if (!segment.includes('\u0000')) return segment;
+  const pattern = [];
+  for (const segment of [node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').split('.')) {
+    if (!segment.includes('\u0000')) { pattern.push(segment); continue; }
     const parts = segment.split('\u0000');
-    return parts.every(part => part === '') ? '*' : new RegExp(`^${parts.map((part) => escapeRegExp(part)).join('.*')}$`, 'su');
-  });
+    pattern.push(parts.every(part => part === '') ? '*' : new RegExp(`^${parts.map((part) => escapeRegExp(part)).join('.*')}$`, 'su'));
+  }
+  return pattern;
 }
 
 function patternsOf(ts, files) {

package/runtime/scripts/hfs/architecture/transport-owner.mjs

@@ -94,7 +94,7 @@ function moduleSpecifierOf(ts, node) {
 function isApolloClientConstruction(ts, kit, checker, node) {
   if (!ts.isNewExpression(node)) return false;
   const binding = kit.importBinding(checker, node.expression);
-  return Boolean(binding && binding.name === 'ApolloClient' && binding.module.startsWith('@apollo/client'));
+  return Boolean(binding?.name === 'ApolloClient' && binding.module.startsWith('@apollo/client'));
 }
 
 function inspectLibraryImport({ ts, file, node, transport, report }) {

package/runtime/scripts/hfs/ci-declaration.mjs

@@ -60,7 +60,10 @@ export function qualityServices(doc, { example = false } = {}) {
 /** Enumerate a missing directory as empty; all filesystem access uses the caller's injected synchronous seam. */
 function entries(dir, fs) {
   try { return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
-  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
 }
 
 /** Read only encrypted envelope key names, never decrypting or returning any sealed value. */
@@ -70,7 +73,7 @@ export function sealedKeyNames(root, { fs }) {
     for (const member of entries(path.join(base, env.name, 'secrets'), fs).filter((entry) => entry.isFile() && entry.name.endsWith('.enc'))) {
       const file = `.starcistacks/${env.name}/secrets/${member.name}`;
       const source = fs.readFileSync(path.join(root, file), 'utf8');
-      const dotenv = [...source.matchAll(/^([A-Za-z_][A-Za-z0-9_]*)=ENC\[/gm)].map((match) => match[1]).filter((key) => !key.startsWith('sops_'));
+      const dotenv = [...source.matchAll(/^([A-Za-z_]\w*)=ENC\[/gm)].map((match) => match[1]).filter((key) => !key.startsWith('sops_'));
       let keys = dotenv;
       if (!dotenv.length) {
         const doc = parseYaml(source);

package/runtime/scripts/hfs/db-baseline-verb.mjs

@@ -87,7 +87,7 @@ function baselinePlan(root, opts, now) {
   if (!active.length) throw new DbVerbError('baseline requires an existing active migration chain');
   const archived = dbSqlFiles(root, MIGRATIONS_ARCHIVE_DIR);
   const oldStamps = [...active, ...archived].map((entry) => entry.stamp);
-  const last = oldStamps.sort((left, right) => left.localeCompare(right)).at(-1);
+  const last = oldStamps.toSorted((left, right) => left.localeCompare(right)).at(-1);
   const stamp = opts.stamp ?? now().toISOString().replace(/\D/g, '').slice(0, 14);
   if (!/^\d{14}$/.test(stamp) || migrationStamp(stamp) === null || stamp <= last) throw new DbVerbError('--stamp must be a valid UTC version after the archive boundary');
   const file = `${MIGRATIONS_DIR}/${stamp}_baseline.sql`;
@@ -225,7 +225,10 @@ function extensionDeclaration(stmt, sql, extensions) {
 
 function baselineStatement(state, stmt, sql) {
   if (roleDeclaration(stmt, sql, state.roles) || extensionDeclaration(stmt, sql, state.extensions)) return;
-  if (stmt.DropRoleStmt) { for (const role of stmt.DropRoleStmt.roles ?? []) state.roles.delete(role.RoleSpec?.rolename); return; }
+  if (stmt.DropRoleStmt) {
+    for (const role of stmt.DropRoleStmt.roles ?? []) state.roles.delete(role.RoleSpec?.rolename);
+    return;
+  }
   if (stmt.GrantRoleStmt || stmt.AlterExtensionStmt || stmt.AlterExtensionContentsStmt || /^OBJECT_ROLE$/.test(stmt.RenameStmt?.renameType ?? '')) throw new DbVerbError('baseline cannot reconstruct role membership, role renames or extension alterations');
   if (dataMutation(stmt) || sourceExecution(stmt)) throw new DbVerbError('baseline cannot reconstruct migration-owned data changes or custom execution from a schema-only dump');
   const node = Object.values(stmt)[0];

package/runtime/scripts/hfs/doc-commands.mjs

@@ -29,7 +29,8 @@ const inner = (t) => t.replace(/^<|>$/g, '');
 
 // ---- extraction -----------------------------------------------------------------------------------------------
 
-const COMMAND_AT = /(?<![\w@./:-])(?:npx\s+starci|npm\s+run\s+starci(?:\s+--silent)?(?:\s+--)?|starci)(?![\w@./-])(?=\s|$)/g;
+const COMMAND_FORM = /npx\s+starci|npm\s+run\s+starci(?:\s+--silent)?(?:\s+--)?|starci/;
+const COMMAND_AT = new RegExp(String.raw`(?<![\w@./:-])(?:${COMMAND_FORM.source})(?![\w@./-])(?=\s|$)`, 'g');
 const FENCE = /^\s*(?:[-*>|]\s*)?```/;
 const SCRIPT_COMMENT = /^\s*(?:\/\/|\*|\/\*)/;
 const CONTINUED = /\\\s*$/;

package/runtime/scripts/hfs/rule-catalog.mjs

@@ -21,7 +21,10 @@ const RULE_KEYS = new Set(['id', 'code', 'law', 'scope', 'kinds', 'gates', 'fail
 const CASE_KEYS = new Set(['id', 'date', 'source', 'ruling', 'quote', 'supersedes', 'status', 'staleWhen', 'amendedBy']);
 const CASE_DATE = /^\d{4}-\d{2}-\d{2}$/;
 const ENFORCER_KEYS = new Set(['kind', 'id', 'status', 'at', 'editions', 'editionWhy']);
-const CASE_REFERENCE = /^(?:case-[1-9][0-9]*|(?:ruling:)?R[0-9]{2,3}(?:\/case-[1-9][0-9]*)?|owner:[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/;
+const CASE_ID = /case-[1-9]\d*/;
+const RULING_REFERENCE = new RegExp(String.raw`(?:ruling:)?R\d{2,3}(?:/${CASE_ID.source})?`);
+const OWNER_REFERENCE = /owner:[a-z][a-z0-9]*(?:-[a-z0-9]+)*/;
+const CASE_REFERENCE = new RegExp(`^(?:${CASE_ID.source}|${RULING_REFERENCE.source}|${OWNER_REFERENCE.source})$`);
 const EVIDENCE_KEYS = new Set(['path', 'edition', 'editions']);
 const PROOF_KEYS = new Set([...EVIDENCE_KEYS, 'codes', 'fixtures']);
 const WITNESS_KEYS = new Set(['edition', 'base', 'mutate', 'expect']);
@@ -191,7 +194,7 @@ function checkRuleCases(rule, label, bad) {
     const at = `${label}.cases[${index}]`;
     if (!isPlainObject(item)) { bad.push(`${at} is not a map`); return; }
     for (const key of Object.keys(item)) if (!CASE_KEYS.has(key)) bad.push(`${at} has unknown key ${key}`);
-    if (typeof item.id !== 'string' || !/^case-[1-9][0-9]*$/.test(item.id) || ids.has(item.id)) bad.push(`${at}.id must be a unique case-N`);
+    if (typeof item.id !== 'string' || !/^case-[1-9]\d*$/.test(item.id) || ids.has(item.id)) bad.push(`${at}.id must be a unique case-N`);
     ids.add(item.id);
     if (typeof item.date !== 'string' || !CASE_DATE.test(item.date)) bad.push(`${at}.date must be YYYY-MM-DD`);
     if (item.source !== 'owner') bad.push(`${at}.source must be owner`);

package/runtime/scripts/hfs/rules/coverage-below.mjs

@@ -12,7 +12,6 @@ import { found } from './read.mjs';
 export const HFS_COVERAGE_BELOW = 'HFS_COVERAGE_BELOW';
 const METRICS = ['lines', 'functions', 'branches'];
 const SUMMARY = { LF: ['lines', 'found'], LH: ['lines', 'hit'], FNF: ['functions', 'found'], FNH: ['functions', 'hit'], BRF: ['branches', 'found'], BRH: ['branches', 'hit'] };
-const SOURCE = /\.ts$/;
 const SPEC = /(?:\.(?:spec|test)|-spec)\.ts$/;
 const countOf = (value) => /^\d+$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null;
 const slash = (value) => path.posix.normalize(String(value).replaceAll('\\', '/'));
@@ -66,7 +65,10 @@ function parseLcov(text) {
   const records = [];
   const problems = [];
   let current = null;
-  const flush = () => { if (current) records.push(current); current = null; };
+  const flush = () => {
+    if (current) records.push(current);
+    current = null;
+  };
   for (const [index, raw] of String(text).replace(/^\uFEFF/, '').split(/\r?\n/).entries()) {
     const line = raw.trim();
     if (!line) continue;
@@ -102,7 +104,7 @@ function inventory({ files, all, repo, manifest }) {
   const scope = coverageScope(effective, repo.providers ?? repo.sides?.be?.providers ?? []);
   const roots = scope.roots.map((dir) => globExpression(`${dir}**`));
   const excludes = scope.excludes.map((dir) => globExpression(`${dir}**`));
-  const candidates = [...new Set((all ?? files ?? []).map(slash))].filter((file) => file.startsWith(prefix) && SOURCE.test(file) && !SPEC.test(file)).sort(byCodeUnit);
+  const candidates = [...new Set((all ?? files ?? []).map(slash))].filter((file) => file.startsWith(prefix) && file.endsWith('.ts') && !SPEC.test(file)).sort(byCodeUnit);
   const measured = [];
   const unmeasured = [];
   for (const file of candidates) {

package/runtime/scripts/hfs/rules/database-access.mjs

@@ -74,7 +74,7 @@ async function principalHelpers(analyses) {
     try { bodies.push({ name: fn.name, ast: await parseSql(body) }); } catch { /* PL/pgSQL safety is checked separately. */ }
   });
   const helpers = new Set();
-  for (let pass = 0; pass < bodies.length; pass += 1) {
+  for (let remaining = bodies.length; remaining > 0; remaining -= 1) {
     for (const body of bodies) if (hasPrincipal(body.ast, helpers)) helpers.add(body.name);
   }
   return helpers;

package/runtime/scripts/hfs/rules/database-migrations.mjs

@@ -13,7 +13,10 @@ import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-const MIGRATION_NAME = /^(\d{14})_([a-z0-9]+(?:-[a-z0-9]+)*|contract_[a-z0-9]+(?:[-_][a-z0-9]+)*|[a-z0-9]+(?:-[a-z0-9]+)*_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*)\.sql$/;
+const MIGRATION_PLAIN = /[a-z0-9]+(?:-[a-z0-9]+)*/;
+const MIGRATION_CONTRACT_TAIL = /contract_[a-z0-9]+(?:[-_][a-z0-9]+)*/;
+const MIGRATION_SLUG = [MIGRATION_PLAIN.source, MIGRATION_CONTRACT_TAIL.source, `${MIGRATION_PLAIN.source}_${MIGRATION_CONTRACT_TAIL.source}`].join('|');
+const MIGRATION_NAME = new RegExp(String.raw`^(\d{14})_(${MIGRATION_SLUG})\.sql$`);
 export const isMigrationName = (name) => MIGRATION_NAME.test(name);
 const RESTAMP_HEADER = /^-- starci:restamp (\d{14}) (\d{14})(?:\r?\n|$)/;
 const withoutRestampHeader = (text) => text?.replace(RESTAMP_HEADER, '') ?? null;
@@ -227,7 +230,11 @@ export function databaseSqlTokens(text) {
   let index = 0;
   let line = 1;
   while (index < text.length) {
-    if (/\s/.test(text[index])) { if (text[index] === '\n') line += 1; index += 1; continue; }
+    if (/\s/.test(text[index])) {
+      if (text[index] === '\n') line += 1;
+      index += 1;
+      continue;
+    }
     const end = commentEnd(text, index);
     if (end !== null) { line += text.slice(index, end).split('\n').length - 1; index = end; continue; }
     const token = sqlTokenAt(text, index);
@@ -243,7 +250,10 @@ export function databaseSqlStatements(tokens) {
   const statements = [];
   let current = [];
   for (const token of tokens) {
-    if (token.t === 'punct' && token.v === ';') { if (current.length) statements.push(current); current = []; }
+    if (token.t === 'punct' && token.v === ';') {
+      if (current.length) statements.push(current);
+      current = [];
+    }
     else current.push(token);
   }
   if (current.length) statements.push(current);

package/runtime/scripts/hfs/rules/database-plpgsql.mjs

@@ -290,7 +290,7 @@ async function functionFindings(file, fn, facts, exposed) {
 
 function alteredDefinerFindings(file, alter, facts, exposed) {
   if (!alter.securityDefiner) return [];
-  const created = facts.functions.filter((fn) => fn.index < alter.index && matchesAlter(fn, alter)).at(-1);
+  const created = facts.functions.findLast((fn) => fn.index < alter.index && matchesAlter(fn, alter));
   const node = created?.node ?? { func: alter.node.func };
   const fn = { ...alter, node, altered: true, originIndex: created?.index ?? -1 };
   return definerDeclarationFindings(file, fn, facts, exposed, true);

package/runtime/scripts/hfs/rules/database-queues.mjs

@@ -104,7 +104,7 @@ function inspectDo(state, node, file) {
   const option = (key) => (node.args ?? []).find((item) => item.DefElem?.defname === key)?.DefElem?.arg?.String?.sval;
   const tree = plpgsqlTree(option('as') ?? '');
   walk(tree, (item) => {
-    if (item.PLpgSQL_expr && item.PLpgSQL_expr.parseMode === 0) inspectCalls(state, sqlTree(item.PLpgSQL_expr.query), file, true);
+    if (item.PLpgSQL_expr?.parseMode === 0) inspectCalls(state, sqlTree(item.PLpgSQL_expr.query), file, true);
     if (item.PLpgSQL_stmt_dynexecute) {
       const expression = sqlTree(`select ${item.PLpgSQL_stmt_dynexecute.query?.PLpgSQL_expr?.query ?? ''}`);
       dynamicOwnership(state, expression, file, true);
@@ -128,7 +128,7 @@ function grantCheck(state, node, file) {
 function recordGrant(state, node, file, executed) {
   state.grants.push({ node, file, created: new Map(state.created), executed });
   const grant = node.GrantStmt;
-  if (!executed || !grant || grant.objtype !== 'OBJECT_TABLE' || grant.targtype !== 'ACL_TARGET_OBJECT') return;
+  if (!executed || grant?.objtype !== 'OBJECT_TABLE' || grant.targtype !== 'ACL_TARGET_OBJECT') return;
   if (!(grant.grantees ?? []).some((item) => item.RoleSpec?.rolename === state.appRole)) return;
   const privileges = grant.privileges?.map((item) => item.AccessPriv?.priv_name).filter(Boolean) ?? TABLE_PRIVILEGES;
   for (const object of grant.objects ?? []) {