@starci/hfs 5.3.0 → 5.5.0

package/codemod/sops-rules.d.mts

@@ -24,7 +24,7 @@ export declare function managedPathRegex(from: string): string;
 /**
  * Migrate a legacy `.sops.yaml` to the form `starci app secret init --env` writes (public recipients only, a rule per member spelling): a rule whose
  * path_regex matches the legacy `.enc` spelling alone also matches `.enc.yaml`, the spelling `secret set` writes, which sops otherwise refuses with
- * no creation rule. Recipients and the other rules are kept; nothing private is read or written.
+ * no creation rule. Recipients, the other rules and the comment header the file opens with (the managed header of `secret init`) are kept; nothing private is read or written.
  */
 export declare function migrateSopsRules({ root, write }: {
     root: string;

package/codemod/sops-rules.mjs

@@ -15,19 +15,24 @@ export function managedPathRegex(from) {
         return CURRENT;
     return /secrets/.test(from) && from.endsWith(LEGACY_END) ? `${from.slice(0, -LEGACY_END.length)}${MODERN_END}` : from;
 }
+/** The comment lines a file opens with (its managed header among them), which a rewrite of the YAML body keeps as written. */
+function leadingComments(text) {
+    return text.replace(/^((?:[ \t]*(?:#[^\n]*)?\r?\n)*)[\s\S]*$/, '$1');
+}
 /**
  * Migrate a legacy `.sops.yaml` to the form `starci app secret init --env` writes (public recipients only, a rule per member spelling): a rule whose
  * path_regex matches the legacy `.enc` spelling alone also matches `.enc.yaml`, the spelling `secret set` writes, which sops otherwise refuses with
- * no creation rule. Recipients and the other rules are kept; nothing private is read or written.
+ * no creation rule. Recipients, the other rules and the comment header the file opens with (the managed header of `secret init`) are kept; nothing private is read or written.
  */
 export function migrateSopsRules({ root, write = false }) {
     const report = { schema: 'starci/sops-rules-report@1', root, write, file: FILE, changes: [], findings: [] };
     const target = path.join(root, FILE);
     if (!fs.existsSync(target))
         return report;
+    const text = fs.readFileSync(target, 'utf8');
     let config;
     try {
-        config = parseYaml(fs.readFileSync(target, 'utf8'));
+        config = parseYaml(text);
     }
     catch {
         config = null;
@@ -46,7 +51,7 @@ export function migrateSopsRules({ root, write = false }) {
         rule.path_regex = to;
     });
     if (report.changes.length > 0 && write)
-        fs.writeFileSync(target, stringifyYaml(config));
+        fs.writeFileSync(target, `${leadingComments(text)}${stringifyYaml(config)}`);
     return report;
 }
 const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');

package/lint/run.d.mts

@@ -15,8 +15,9 @@ export interface LinterRun {
 }
 /**
  * What a linter run is asked for. `list` is the files an ESLint run lints (cwd-relative, posix) when they are named one by one: they go to the child
- * through a file, never the command line, and `args` then holds the options alone. `files` is the number of source files the run judges, which the
- * heavy-command budget of the ESLint kind scales with (a list names its own count).
+ * through a file, never the command line, and `args` then holds the options alone. `files` is the number of source files the child's work is made of,
+ * which the heavy-command budget of the ESLint kind scales with: the typed program and the project graph of a side are built whole for a named list
+ * too, so a list run of a side whose scope is known names the side's count; without `files` a list names its own count.
  */
 export interface LinterSpec {
     cwd: string;
@@ -134,8 +135,8 @@ export interface CachedLinters {
 }
 /**
  * ESLint and stylelint through the result cache: per side, the files the records cannot vouch for go to the very launcher, chunking and result
- * validation of a full run (eslintRepository), the rest take their records. The answer has the shape of eslintRepository's, plus the stylelint
- * results, so the lint report is built the same way from either.
+ * validation of a full run (eslintRepository), the rest take their records; then the root packages, linted whole. Each scope runs on its own
+ * (scopeFailure). The answer has the shape of eslintRepository's, plus the stylelint results, so the lint report is built the same way from either.
  */
 export declare function cachedLinters({ repoRoot, app, side: only, run, session }: {
     repoRoot: string;

package/lint/run.mjs

@@ -84,7 +84,7 @@ export async function runLinter({ cwd, pkg, bin, args, bound = null, list, files
         fs.writeFileSync(job, JSON.stringify({ files: list ?? ['.'], fix: args.includes('--fix'), ...(snapshotFile === null || graph === undefined ? {} : { graph: { out: snapshotFile, canons: graph } }) }));
         childArgs = [LIST_RUNNER, job];
     }
-    const count = list?.length ?? files;
+    const count = files ?? list?.length;
     let run;
     let handed;
     try {
@@ -365,8 +365,10 @@ async function launchEslint({ app, repoRoot, opts, changed, existing, run = runL
         // the child that builds the canon's project graph for its rules hands the snapshot out when the caller keeps the graph findings (the cache); the packages are no side folder and have no graph
         const graph = handOutGraph && !packages ? graphCanonsOf(repoRoot, cwd, side) : undefined;
         // The files of a diff go to ONE child through a file (a diff of hundreds of long paths outgrows the Windows command line, and each extra
-        // child would build the whole TypeScript program again); the whole side is a single directory argument.
-        const launch = Promise.resolve().then(() => run(changed ? { cwd, pkg: 'eslint', bin: 'eslint', args: head, list: sources, bound: repoRoot, ...(graph === undefined ? {} : { graph }) } : { cwd, pkg: 'eslint', bin: 'eslint', args: [...head, packages ? PACKAGES : '.'], files: expected.length, bound: repoRoot, ...(graph === undefined ? {} : { graph }) }));
+        // child would build the whole TypeScript program again); the whole side is a single directory argument. Either child builds the typed program
+        // and the project graph of the whole side, so its liveness budget scales with the side's scope when the caller knows it, never with the diff alone.
+        const programFiles = known?.length ?? expected.length;
+        const launch = Promise.resolve().then(() => run(changed ? { cwd, pkg: 'eslint', bin: 'eslint', args: head, list: sources, files: programFiles, bound: repoRoot, ...(graph === undefined ? {} : { graph }) } : { cwd, pkg: 'eslint', bin: 'eslint', args: [...head, packages ? PACKAGES : '.'], files: programFiles, bound: repoRoot, ...(graph === undefined ? {} : { graph }) }));
         launches.push({ side, cwd, expected, run: launch.catch(spawnFailure) });
     }
     return launches;
@@ -489,10 +491,20 @@ export function gitBaseToken(repoRoot) {
     }
     return 'no-base';
 }
+/**
+ * A scope whose linter reached no complete measurement (a child ended by its liveness budget, a capture cut short) is a tool error of that scope, and the
+ * next scope still runs: the root packages are judged whatever became of the back end. Nothing of the failed scope is recorded (its records are written
+ * only after its child completed). A hold of the host (HOST_HELD, HEAVY_DEFERRED) still ends the run, since no scope would be admitted either.
+ */
+function scopeFailure(error, scope) {
+    if (!isNodeExecutionRefusal(error) || isHostHeld(error) || error.code === 'HEAVY_DEFERRED')
+        throw error;
+    return `eslint did not complete in ${scope}/: ${String(error.message).split('\n')[0]}`;
+}
 /**
  * ESLint and stylelint through the result cache: per side, the files the records cannot vouch for go to the very launcher, chunking and result
- * validation of a full run (eslintRepository), the rest take their records. The answer has the shape of eslintRepository's, plus the stylelint
- * results, so the lint report is built the same way from either.
+ * validation of a full run (eslintRepository), the rest take their records; then the root packages, linted whole. Each scope runs on its own
+ * (scopeFailure). The answer has the shape of eslintRepository's, plus the stylelint results, so the lint report is built the same way from either.
  */
 export async function cachedLinters({ repoRoot, app, side: only, run, session }) {
     const eslint = { findings: [], errors: [], raw: [], engine: { sides: {} } };
@@ -514,23 +526,31 @@ export async function cachedLinters({ repoRoot, app, side: only, run, session })
             continue;
         }
         const styled = side === STYLE_SIDE;
-        const outcome = await lintSide({
-            session, side, sideRoot: cwd, scope, stylesheets: styled ? stylesheetsOf(cwd) : [],
-            canons, styleCanon: styled ? await styleDeclaration({ repoRoot, cwd }) : null, typescript: () => loadAppTypeScript(cwd), extraKey: '', gitToken, full, write: true,
-            eslint: async (files) => {
-                const listed = files === null ? null : files.map((file) => `${side}/${file}`);
-                const sub = await eslintRepository({ repoRoot, app, opts: { side }, changed: listed, existing: listed ?? [], run, scopes: { [side]: scope }, handOutGraph: true });
-                return { results: sub.raw, errors: sub.errors, ...(sub.graphs[side] === undefined ? {} : { graph: sub.graphs[side] }) };
-            },
-            stylelint: styled ? async (files) => {
-                const linted = await (run ?? runLinter)({ cwd, pkg: 'stylelint', bin: 'stylelint', args: [...(files ?? [STYLE_GLOB]), '--formatter', 'json'] });
-                const appRelative = appRelativeMessages(STYLE_SIDE, cwd);
-                for (const result of linted.results ?? [])
-                    for (const warning of result.warnings ?? [])
-                        warning.text = appRelative(warning.text);
-                return { results: (linted.results ?? []), errors: linted.error ? [linted.error] : [] };
-            } : null,
-        });
+        let outcome;
+        try {
+            outcome = await lintSide({
+                session, side, sideRoot: cwd, scope, stylesheets: styled ? stylesheetsOf(cwd) : [],
+                canons, styleCanon: styled ? await styleDeclaration({ repoRoot, cwd }) : null, typescript: () => loadAppTypeScript(cwd), extraKey: '', gitToken, full, write: true,
+                eslint: async (files) => {
+                    const listed = files === null ? null : files.map((file) => `${side}/${file}`);
+                    const sub = await eslintRepository({ repoRoot, app, opts: { side }, changed: listed, existing: listed ?? [], run, scopes: { [side]: scope }, handOutGraph: true });
+                    return { results: sub.raw, errors: sub.errors, ...(sub.graphs[side] === undefined ? {} : { graph: sub.graphs[side] }) };
+                },
+                stylelint: styled ? async (files) => {
+                    const linted = await (run ?? runLinter)({ cwd, pkg: 'stylelint', bin: 'stylelint', args: [...(files ?? [STYLE_GLOB]), '--formatter', 'json'] });
+                    const appRelative = appRelativeMessages(STYLE_SIDE, cwd);
+                    for (const result of linted.results ?? [])
+                        for (const warning of result.warnings ?? [])
+                            warning.text = appRelative(warning.text);
+                    return { results: (linted.results ?? []), errors: linted.error ? [linted.error] : [] };
+                } : null,
+            });
+        }
+        catch (error) {
+            eslint.errors.push(scopeFailure(error, side));
+            eslint.engine.sides[side] = { files: 0 };
+            continue;
+        }
         sides.push({ side, stats: outcome.stats });
         for (const message of outcome.errors)
             (message.startsWith('stylelint ') ? style.errors : eslint.errors).push(message);
@@ -544,11 +564,17 @@ export async function cachedLinters({ repoRoot, app, side: only, run, session })
     }
     // The root packages are small and have no result records: they are linted whole on every run, through the same launcher.
     if ((only === undefined || only === PACKAGES) && hasPackagesLint(repoRoot)) {
-        const linted = await eslintRepository({ repoRoot, app, opts: { side: PACKAGES }, run });
-        eslint.errors.push(...linted.errors);
-        eslint.raw.push(...linted.raw);
-        eslint.findings.push(...linted.findings);
-        eslint.engine.sides[PACKAGES] = linted.engine.sides[PACKAGES] ?? { files: 0 };
+        try {
+            const linted = await eslintRepository({ repoRoot, app, opts: { side: PACKAGES }, run });
+            eslint.errors.push(...linted.errors);
+            eslint.raw.push(...linted.raw);
+            eslint.findings.push(...linted.findings);
+            eslint.engine.sides[PACKAGES] = linted.engine.sides[PACKAGES] ?? { files: 0 };
+        }
+        catch (error) {
+            eslint.errors.push(scopeFailure(error, PACKAGES));
+            eslint.engine.sides[PACKAGES] = { files: 0 };
+        }
     }
     session.report(lintFamilyReport(sides));
     return { eslint, stylelint: style, sides };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "5.3.0",
+  "version": "5.5.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/release/lint-report.mjs

@@ -5,7 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { firstLine, tool } from '../stack/context.mjs';
-const LINT_SIDES = ['be', 'fe'];
+import { PACKAGES, PACKAGES_CONFIG } from '../lint/run.mjs';
+const LINT_SIDES = ['be', 'fe', PACKAGES];
 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. */
@@ -14,8 +15,8 @@ function mergeSonarReports(reports) {
     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)));
+/** The lint scopes the app has: a be/ or fe/ folder beside the app root, and its root packages when it has their managed config. */
+const sidesOf = (root) => LINT_SIDES.filter((side) => fs.existsSync(path.join(root, side)) && (side !== PACKAGES || fs.existsSync(path.join(root, PACKAGES_CONFIG))));
 /**
  * Runs `starci app check --gate lint --side <side> --out <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.

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

@@ -38,7 +38,7 @@ pins:
     source: packages/next-data/package.json
     why: 'the SWR data helpers of every front end (fe-stack data, owner:next-data-package): pollingRestart, the viewer and tenant key helpers, viewerSwrConfig and the viewer cache; each operation hook stays in the app and the package holds no component.'
   '@starci/grammar':
-    version: 0.21.15
+    version: 0.21.17
     group: starci
     install: registry
     side: fe
@@ -52,28 +52,28 @@ pins:
     source: packages/next-i18n/package.json
     why: 'the next-intl stack of every front end (fe-stack i18n, owner:next-i18n-package): defineI18n over the locales of the app, the locale-negotiating proxy, the locale-aware navigation, the request config that loads the catalogs of the app and the locale read of the [locale] layout; the app keeps its message catalogs and writes none of the stack.'
   '@starci/eslint-canon-be':
-    version: 3.14.0
+    version: 3.15.0
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-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: 9.12.0
+    version: 9.13.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe 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; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.21.15
+    version: 0.21.17
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.21.15
+    version: 0.21.17
     group: starci
     install: registry
     side: fe
@@ -99,7 +99,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.6.2
+    version: 2.7.0
     group: starci
     install: registry
     side: be
@@ -127,14 +127,14 @@ pins:
     source: packages/nest-kit/package.json
     why: 'the module definition of every back-end module: defineConfigurableModule and defineCapabilityModule return the module base class, the options token and the options types with their types stated, so a <x>.module-definition.ts is one call that the lint on stated export types (R368) and the duplicate-code check (R21) both accept; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/auth':
-    version: 0.2.0
+    version: 0.3.0
     group: starci
     install: registry
     side: both
     source: packages/auth/package.json
     why: 'the lite sign-in: the NestJS module (EdDSA access tokens with a multi-key JWKS, passwords, Google OAuth with state and PKCE, rotating refresh sessions, the sign-in budget, the refresh cookie), the front-end client and its React bindings, the door contracts and test doubles; the one importer of the identity libraries, reached by a back end only through integrations/passport; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/auth-oidc':
-    version: 0.1.0
+    version: 0.1.2
     group: starci
     install: registry
     side: both
@@ -155,7 +155,7 @@ pins:
     source: packages/mail/package.json
     why: 'outgoing mail of a back end: a NestJS module and the Mailer port over SMTP (connect, greeting, socket and total timeouts, STARTTLS required by default, recipient, message and attachment checks, a shared SMTP target policy, coded errors, typed escaping render helpers returning { subject, text, html }), with @starci/mail/testing for its specs; the only importer of nodemailer (R90).'
   '@starci/hfs':
-    version: 5.3.0
+    version: 5.5.0
     group: starci
     install: registry
     side: both
@@ -592,7 +592,7 @@ pins:
     version: 3.1150.0
     group: framework
     side: be
-    why: 'the S3 transport inside @starci/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces), which depends on it at exactly this version and which no app file imports; 3.1150.0 is the release of 2026-10-12, chosen over newer ones that had not aged two weeks.'
+    why: 'the S3 transport inside @starci/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces), which depends on it at exactly this version and which no app file imports; 3.1150.0 is the release of 2026-10-12.'
   '@aws-sdk/s3-request-presigner':
     version: 3.1150.0
     group: framework
@@ -602,7 +602,7 @@ pins:
     version: 10.1.7
     group: framework
     side: be
-    why: 'the SMTP client inside @starci/mail, which depends on it at exactly this version and which no app file imports; 10.1.7 is the release of 2026-10-18, chosen over newer ones that had not aged two weeks.'
+    why: 'the SMTP client inside @starci/mail, which depends on it at exactly this version and which no app file imports; 10.1.7 is the release of 2026-10-18.'
   '@apollo/server':
     version: 5.5.1
     group: framework
@@ -652,7 +652,7 @@ pins:
     version: 6.29.0
     group: framework
     side: be
-    why: 'the Agent of platform/http (its one owner, R90): FetchHttpClient hands fetch a pool that trusts HttpOptions.trustedCa beside the bundled roots (a test world''s per-run fake CA); the 6 line is the undici the Node 22 runtime of the app images bundles, and its Agent also serves the fetch of Node 24; 6.29.0 is the release of 2026-09-25, chosen over newer ones that had not aged two weeks.'
+    why: 'the Agent of platform/http (its one owner, R90): FetchHttpClient hands fetch a pool that trusts HttpOptions.trustedCa beside the bundled roots (a test world''s per-run fake CA); the 6 line is the undici the Node 22 runtime of the app images bundles, and its Agent also serves the fetch of Node 24; 6.29.0 is the release of 2026-09-25.'
   # --- lite identity (integrations/passport, ruling lite-self-hosted-postgres-passport-minio)
   '@nestjs/passport':
     version: 11.0.5

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

@@ -77,7 +77,7 @@ items:
     check: ci-standard
   - id: sonar-lint-per-side
     title: the Sonar lint runs per side
-    requires: "a lint with a Sonar import (`starci app check --gate lint --out`) names its side (--side be|fe); the reports are merged into reports/lint.sonar.json afterwards; no combined lint with Sonar"
+    requires: "a lint with a Sonar import (`starci app check --gate lint --out`) names its side (--side be|fe|packages); the reports are merged into reports/lint.sonar.json afterwards; no combined lint with Sonar"
     covers: [app-ci, runtime]
     check: ci-standard
   - id: test-sharding
@@ -87,7 +87,7 @@ items:
     check: ci-standard
   - id: lint-parallel
     title: lint each side in its own job
-    requires: "the lint job is a matrix over side [be, fe]; each side lints (with its own Sonar report when a token is set) in parallel, and the sonar job merges the reports"
+    requires: "the lint job is a matrix over side [be, fe], plus packages in an app with root packages; each scope lints (with its own Sonar report when a token is set) in parallel and on its own, and the sonar job merges the reports"
     covers: [app-ci]
     check: ci-standard
   - id: cache-saved-always

package/runtime/knowledge/hfs/rules.yaml

@@ -3299,7 +3299,7 @@ rules:
     code: "HFS_DOCKER_BUILD_CONTEXT"
     editions: [lite, full]
     docs: [docs/application-stacks.md#r187]
-    law: "Every app image is built from the app root: the header comment of an app's Dockerfile states `starci docker build <app>` for its own path, and no COPY or ADD source leaves the build context (a `..` segment or an absolute path)."
+    law: "Every app image is built from the app root: the header comment of an app's Dockerfile states `starci docker build <app>` for its own path, no COPY or ADD source leaves the build context (a `..` segment or an absolute path), and the image of a Next app whose front end reads be/contracts/ copies that folder exactly when the app holds it (a COPY of a missing folder fails the build, a missing COPY leaves the codegen without its contract)."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["HFS_DOCKER_BUILD_CONTEXT"]
@@ -5791,7 +5791,7 @@ rules:
         ruling: "Lite storage is the MinIO already running on the Tay Son host, reached through the one S3 integration."
   - id: R332
     code: "LITE_DB_MIGRATION"
-    law: "A lite app's schema lives only in db/: every schema change is one db/migrations/<ts14>_<kebab>.sql (archive db/migrations/archive/, seed db/seed.sql), and the tree holds no supabase/ folder and no SQL file outside db/ but a .starcistacks seed."
+    law: "A lite app's schema lives only in db/: every schema change is one db/migrations/<ts14>_<kebab>.sql (archive db/migrations/archive/, the managed db/bootstrap.sql), every other SQL file under db/ is refused, and the tree holds no supabase/ folder and no SQL file outside db/ but the sql/ entries of its seed levels (R375)."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["LITE_DB_MIGRATION"]
@@ -6628,3 +6628,16 @@ rules:
       - {path: contexts/project/stacks.md#project-stacks-11-a-customised-service-is-an-image-the-app-builds-the-same-in-every-environment, editions: [lite, full]}
     proves:
       - {path: packages/hfs/src/stacks-service-images.spec.mjs, editions: [lite, full]}
+  - id: R375
+    code: "HFS_SEEDS_SHAPE"
+    law: "Seed data lives only in the seed levels of `.starcistacks/`, where `seeds/` is applied in every environment first and `<env>/seeds/` in the one environment the stack declaration names `<env>`; each level is a `seeds.yaml` manifest (schema starci/seeds@1) whose entries list every file of its `sql/`, `data/` and `files/` folders; a seed is never a migration (no statement that creates, alters, drops, truncates, grants, revokes or comments on an object), never custody, a data document validates against the schema its entry names, a level a production environment applies holds no test data but the one test account an environment declares (a test-account entry with its reason), and a document names a secret only as a reference to a sealed seeds-<name> member of its environment."
+    kinds: [check]
+    gates: [settle, land, ci]
+    failureCodes: ["HFS_SEEDS_SHAPE", "HFS_SEED_MANIFEST", "HFS_SEED_DDL", "HFS_SEED_DATA_SCHEMA", "HFS_SEED_TEST_DATA", "HFS_SEED_SECRET_REF"]
+    enforcers:
+      - {kind: hfs, id: seeds-shape, at: scripts/hfs/rules/seeds.mjs}
+    editions: [lite, full]
+    docs:
+      - {path: contexts/project/stacks.md#project-stacks-12-seed-data-lives-in-the-seed-levels-of-the-stack, editions: [lite, full]}
+    proves:
+      - {path: packages/hfs/src/hfs-seeds-shape.spec.mjs, editions: [lite, full]}

package/runtime/knowledge/hfs/slots.yaml

@@ -7,7 +7,7 @@
 # catalog READ this file through scripts/hfs/slots.mjs; none of them hardcodes a path.
 # Shape: modules/schemas/hfs-slots.schema.yaml. The repository side is hfs.json: modules/schemas/hfs-repo.schema.yaml.
 schema: starci/hfs-slots@3
-version: 3.17.0
+version: 3.19.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -61,6 +61,10 @@ versioning:
 # 3.17.0 (ruling auth-oidc-package, 2026-11-03) adds the optional full-edition be.integrations.keycloak, the glue of @starci/auth-oidc (the OIDC client of the
 # identity provider behind the PrincipalVerifier of @starci/auth), and gives @starci/auth-oidc to it in ruleParams.be.infraOwners.
 # 3.17.0 (ruling module-packages, 2026-11-03) adds the optional app.packages and app.module-registry: the workspace packages of the app root (the agent SDK, the module packages, the managed registry).
+# 3.18.0 (ruling seed-levels, 2026-11-03) gives app.starcistacks its two seed levels, the shared .starcistacks/seeds/ and each environment's
+# <env>/seeds/, each a seeds.yaml manifest and the folders sql/, data/ and files/, and retires app.db.seed (its rows are the shared level's
+# sql/ entries); `starci app codemod seeds-layout` moves an older app's seed data into them.
+# 3.19.0 (ruling root-packages-any-name, 2026-11-03) widens app.packages to any packages/<name>/: the agent SDK, a block library, a module package.
 # 3.15.0 (ruling app-check-cache, 2026-10-31) adds the optional app.starcistacks.cache, the committed check cache of the app (.starcistacks/cache/, both editions).
 # 3.14.0 (ruling app-secrets-one-standard, 2026-10-29) adds the optional app.ci-stack-key-restore, the managed workflow that writes the
 # deploy server's age identity back from its GitHub Environment backup.
@@ -502,7 +506,7 @@ ruleParams:
     # R334 (lite): the only `.query(` outside platform/database's composer and the test world is the pass-through of a file listed here
     # (or in hfs.json sides.be.sqlPassThrough), whose SQL text is not the app's own. Paths are relative to the side folder.
     sqlPassThrough:
-      - {file: src/modules/platform/database/seed-runner.service.ts, reason: "the tracked seed file's text, run as it is (db/seed.sql); the app writes no SQL there"}
+      - {file: src/modules/platform/database/seed-runner.service.ts, reason: "the tracked seed files' text, run as it is (the sql/ entries of .starcistacks/seeds/, then of .starcistacks/<env>/seeds/); the app writes no SQL there"}
 
     lite:
       schemaAuthority: sql
@@ -891,10 +895,10 @@ slots:
   - id: app.packages
     since: 3.17.0
     profiles: [app]
-    editionWhy: Lite and full share the slot; a product's agent SDK and its agent modules are workspace packages in both.
-    # A workspace package of the app ROOT (packages/agent-sdk, packages/module-<name>): first-party source that both sides import through its
+    editionWhy: Lite and full share the slot; every root workspace package of a product (its agent SDK, a block library, a module package, a reviewed plugin package) is one in both.
+    # A workspace package of the app ROOT (packages/<name>: the agent SDK, a block library, packages/module-<name>): first-party source that both sides import through its
     # package entry points and never past them (ARCH_INTERNAL_IMPORT_OUTSIDE), linted by the root eslint config by subpath.
-    path: "packages/{agent-sdk,module-<name>}/"
+    path: "packages/<name>/"
     presence: optional
     tracked: tracked
     tier: none
@@ -964,16 +968,18 @@ slots:
     tests: none
     requires: [application-stacks.yaml]
     allows: [application-stacks.yaml, "<env>/README.md", "<env>/environment.json", "<env>/infra/{compose,swarm,k8s,terraform}/**", "<env>/infra/metadata.json",
-             "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.{enc.yaml,enc}", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
+             "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.{enc.yaml,enc}", "<env>/secrets/.gitkeep",
+             "seeds/seeds.yaml", "seeds/{sql,data,files}/**", "<env>/seeds/seeds.yaml", "<env>/seeds/{sql,data,files}/**"]
     forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
-    # Owner ruling 2026-10-14: lite declares docker-swarm production, app runtime config, sealed custody and seed data.
+    # Owner ruling 2026-10-14: lite declares docker-swarm production, app runtime config, sealed custody and the seed levels.
     # The db service supplies the database; schedules are platform/jobs ticks (R335); production has no Compose or host cron.
     lite:
       requires: [application-stacks.yaml]
       allows: [application-stacks.yaml, images/db/Dockerfile, "<env>/README.md", "<env>/environment.json", "<env>/infra/{compose,swarm}/**", "<env>/infra/metadata.json",
-               "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.{enc.yaml,enc}", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
+               "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.{enc.yaml,enc}", "<env>/secrets/.gitkeep",
+             "seeds/seeds.yaml", "seeds/{sql,data,files}/**", "<env>/seeds/seeds.yaml", "<env>/seeds/{sql,data,files}/**"]
       forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
-    rules: [HFS_STACKS_SHAPE, HFS_STACKS_IN_SIDE, HFS_PLAINTEXT_SECRET, HFS_IDENTITY_CUSTODY]
+    rules: [HFS_STACKS_SHAPE, HFS_STACKS_IN_SIDE, HFS_PLAINTEXT_SECRET, HFS_IDENTITY_CUSTODY, HFS_SEEDS_SHAPE, HFS_SEED_MANIFEST, HFS_SEED_DDL, HFS_SEED_DATA_SCHEMA, HFS_SEED_TEST_DATA, HFS_SEED_SECRET_REF, HFS_SEED_PII]
   - id: app.sops
     since: 3.1.0
     profiles: [app]
@@ -1072,15 +1078,6 @@ slots:
     tier: none
     tests: none
     since: 3.9.0
-  - id: app.db.seed
-    profiles: [app]
-    editions: [lite]
-    path: "db/seed.sql"
-    presence: optional            # synthetic dev data only; a lite app seeds nothing it cannot regenerate
-    tracked: tracked
-    tier: none
-    tests: none
-    since: 3.9.0
   - id: app.db.image
     profiles: [app]
     editions: [lite]

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

@@ -4233,6 +4233,67 @@ HFS_SEED_PII:
   owner: op-retry
   kind: check-finding
 
+HFS_SEEDS_SHAPE:
+  title: "Seed data lives in a seed level of .starcistacks and holds no custody"
+  title_vi: "Dữ liệu seed nằm ngoài cấp seed hoặc chứa custody"
+  meaning_vi: "Một tệp dưới `.starcistacks/seeds/` hoặc `.starcistacks/<env>/seeds/` không phải `seeds.yaml` và không nằm trong `sql/`, `data/`, `files/`; hoặc thuộc cấp seed của một môi trường không được khai báo; hoặc là custody (envelope `.enc`, khoá `.pem`/`.key`, tệp `.env`)."
+  causes_vi:
+    - "Vi phạm R375: dữ liệu seed chỉ nằm trong hai cấp seed của `.starcistacks/`, mỗi cấp là một manifest và các thư mục sql/, data/, files/."
+    - "Một secret được đặt cạnh seed thay vì niêm phong bằng sops trong `.starcistacks/<env>/secrets/`."
+  nextStep_vi: "Chuyển tệp vào thư mục loại của cấp seed (`starci app codemod seeds-layout` chuyển dữ liệu cũ); niêm phong secret bằng `starci app secret set --env <env>` và xoá bản rõ."
+  owner: op-retry
+  kind: check-finding
+
+HFS_SEED_MANIFEST:
+  title: "Every seed file is an entry of its level's seeds.yaml"
+  title_vi: "Manifest seeds.yaml thiếu, sai hoặc không liệt kê tệp seed"
+  meaning_vi: "Cấp seed có tệp nhưng không có `seeds.yaml`, manifest không đọc được hoặc sai schema starci/seeds@1, một mục trỏ tới đường dẫn không tồn tại, `after` nêu id không có hoặc tạo vòng, hay một tệp trong sql/, data/, files/ không thuộc mục nào."
+  causes_vi:
+    - "Vi phạm R375: manifest là nơi khai báo thứ tự, loại, đích và chế độ (once, upsert) của mọi seed."
+  nextStep_vi: "Thêm hoặc sửa mục `{ id, kind, path, target, mode, after? }` trong `seeds.yaml` của cấp đó cho tệp được nêu."
+  owner: op-retry
+  kind: check-finding
+
+HFS_SEED_DDL:
+  title: "A seed only writes rows: seed data is never a migration"
+  title_vi: "Seed chứa câu lệnh thay đổi schema"
+  meaning_vi: "Một tệp SQL của mục sql có câu lệnh CREATE, ALTER, DROP, TRUNCATE, GRANT, REVOKE hoặc COMMENT: thay đổi schema hoặc quyền, việc chỉ migration được làm."
+  causes_vi:
+    - "Vi phạm R375 và BE-PERSISTENCE-1: dữ liệu seed không bao giờ là migration, và migration là nơi duy nhất thay đổi schema."
+  nextStep_vi: "Chuyển câu lệnh schema thành một migration (lite: `db/migrations/<ts14>_<kebab>.sql`), để seed chỉ ghi dòng dữ liệu một cách idempotent (`on conflict do nothing` hoặc upsert)."
+  owner: op-retry
+  kind: check-finding
+
+HFS_SEED_DATA_SCHEMA:
+  title: "A data seed validates against the schema its entry names"
+  title_vi: "Tài liệu seed không khớp schema đã khai báo"
+  meaning_vi: "Một tài liệu JSON hoặc YAML của mục data không qua được JSON schema mà mục đó nêu (`schema`, do app khai báo), hoặc schema đó không đọc được."
+  causes_vi:
+    - "Vi phạm R375: app sở hữu ý nghĩa và schema của dữ liệu, harness kiểm tra tài liệu trước khi lệnh của app nạp nó."
+  nextStep_vi: "Sửa tài liệu cho khớp schema, hoặc sửa đường dẫn `schema` của mục trỏ tới schema app khai báo."
+  owner: op-retry
+  kind: check-finding
+
+HFS_SEED_TEST_DATA:
+  title: "A level production applies holds no test data"
+  title_vi: "Seed áp dụng cho production chứa dữ liệu thử"
+  meaning_vi: "Cấp seed dùng chung hoặc cấp của một môi trường không phải docker-compose có danh tính example.test hoặc giá trị, tên tệp bắt đầu bằng uat- hay test- ngoài mục test-account duy nhất mà môi trường đó khai báo."
+  causes_vi:
+    - "Vi phạm R375: dữ liệu thử (tài khoản mẫu, workspace mẫu) chỉ nằm trong cấp seed của môi trường dev."
+  nextStep_vi: "Chuyển dữ liệu thử vào `.starcistacks/dev/seeds/`, hoặc khai báo tài khoản thử duy nhất của production là một mục `kind: test-account` có `reason`; chỉ để dữ liệu ban đầu thật (gói, danh mục) ở cấp dùng chung."
+  owner: op-retry
+  kind: check-finding
+
+HFS_SEED_SECRET_REF:
+  title: "A seed names a secret only as a sealed seeds-<name> member of its environment"
+  title_vi: "Tham chiếu secret của seed sai tên hoặc thiếu member niêm phong"
+  meaning_vi: "Một tài liệu seed có `{ \"secret\": \"<member>\" }` mà tên không có dạng seeds-<name>, hoặc môi trường của cấp đó (cấp dùng chung: mọi môi trường) không có `.starcistacks/<env>/secrets/<member>.enc.yaml`."
+  causes_vi:
+    - "Vi phạm R375: giá trị bí mật của seed nằm trong custody sops của môi trường, được bước seed mở trong bộ nhớ, không bao giờ nằm trong tệp seed."
+  nextStep_vi: "Niêm phong giá trị bằng `starci app secret set --env <env>` vào member seeds-<name> của môi trường đó và tham chiếu đúng tên."
+  owner: op-retry
+  kind: check-finding
+
 HFS_SERVICE_PLACEMENT:
   title: "A back-end service lives only at be/apps/<service>"
   title_vi: "Dịch vụ back end nằm ngoài be/apps/<service>"
@@ -5668,10 +5729,10 @@ BE_STORAGE_OWNER:
 LITE_DB_MIGRATION:
   title: "A lite schema change lives outside db/migrations"
   title_vi: "Thay đổi schema của app lite nằm ngoài db/migrations"
-  meaning_vi: "`<path>` là tệp của thư mục supabase/ hoặc một tệp SQL ngoài db/ (trừ seed của .starcistacks)."
+  meaning_vi: "`<path>` là tệp của thư mục supabase/, một tệp SQL ngoài db/ (trừ mục sql của các cấp seed trong `.starcistacks/`), hoặc một tệp SQL trong db/ không phải migration, archive hay bootstrap."
   causes_vi:
-    - "Vi phạm R332: schema của app lite chỉ nằm trong db/migrations/<ts14>_<kebab>.sql, archive và seed trong db/."
-  nextStep_vi: "Chuyển migration sang db/migrations (giữ nguyên stamp), seed sang db/seed.sql, types sang db/types/; xoá supabase/."
+    - "Vi phạm R332: schema của app lite chỉ nằm trong db/migrations/<ts14>_<kebab>.sql, archive và db/bootstrap.sql; dữ liệu seed nằm trong các cấp seed của `.starcistacks/` (R375)."
+  nextStep_vi: "Chuyển migration sang db/migrations (giữ nguyên stamp), seed sang `.starcistacks/seeds/sql/` (`starci app codemod seeds-layout`), types sang db/types/; xoá supabase/."
   owner: op-retry
   kind: check-finding
 

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

@@ -1,4 +1,4 @@
-// root-packages.mjs - the workspace packages of an app ROOT (packages/agent-sdk, packages/module-<name>, the managed packages/modules).
+// root-packages.mjs - the workspace packages of an app ROOT (packages/<name>: the agent SDK, a block library, a module package, the managed packages/modules).
 // They lie outside both side folders and belong to no side; both sides import them by package name, through their package entry points
 // (the `exports` of the manifest), so the import graph reads them as first-party packages and the back-end canon never reads them as
 // a third-party library. The app root's one package.json lists them in `workspaces`; the patterns that start with a side folder

package/runtime/scripts/hfs/check.mjs

@@ -18,6 +18,9 @@
 //   HFS_MIN_INSTANCES             fewer instances of a slot than minInstances
 //   HFS_PLAINTEXT_SECRET          (R06, rules/secrets.mjs) a plaintext secret file or value in a tracked file; a `.enc` that is no sops envelope
 //   HFS_STACKS_SHAPE              (R10, rules/stacks.mjs) invalid stack shape, Swarm runtime policy, host crontab installation or lite backing duplication
+//   HFS_SEEDS_SHAPE, HFS_SEED_MANIFEST, HFS_SEED_DDL, HFS_SEED_DATA_SCHEMA, HFS_SEED_TEST_DATA, HFS_SEED_SECRET_REF (R375, rules/seeds.mjs) seed
+//                                 data outside the seed levels or unlisted, custody, a schema statement, a document off its schema, test data
+//                                 production applies outside its one test account, a secret reference to no sealed seeds-<name> member
 //   HFS_CI_MISSING_CANON          (R13, rules/pipeline.mjs) CI without the pinned `starci app check`, pre-push without typecheck or lint
 //   HFS_DEP_VERSION_SKEW          (R14, rules/deps.mjs) a dependency at two versions in the workspace, or a nested copy in the lockfile
 //   HFS_CONTRACT_SNAPSHOT_DRIFT   (R23, rules/contract.mjs) an uncommitted back-end snapshot, or a front-end copy that differs from it
@@ -108,7 +111,7 @@ export const CHECK_CODES = Object.freeze([
     'HFS_SLOT_UNDECLARED', 'HFS_SLOT_NOT_ENABLED', 'HFS_SLOT_AMBIGUOUS', 'HFS_TRACKED_MUST_BE_IGNORED', 'HFS_FORBIDDEN_PRESENT',
     'HFS_SLOT_REQUIRED_MISSING', 'HFS_MIN_INSTANCES', 'HFS_CANON_PIN_DRIFT', 'HFS_SIZE_SOFT_BACKLOG', 'BE_SOURCE_FORM',
     'HFS_MANAGED_FILE_DRIFT', 'HFS_TOOL_CONFIG_LOCAL', 'HFS_RULE_OFF_WITHOUT_REPLACEMENT', 'HFS_TS_STRICT',
-    'HFS_PLAINTEXT_SECRET', 'HFS_STACKS_SHAPE', 'HFS_CI_MISSING_CANON', 'HFS_DEP_VERSION_SKEW', 'HFS_CONTRACT_SNAPSHOT_DRIFT', 'HFS_MCP_TOOLS_SNAPSHOT',
+    'HFS_PLAINTEXT_SECRET', 'HFS_STACKS_SHAPE', 'HFS_SEEDS_SHAPE', 'HFS_SEED_MANIFEST', 'HFS_SEED_DDL', 'HFS_SEED_DATA_SCHEMA', 'HFS_SEED_TEST_DATA', 'HFS_SEED_SECRET_REF', 'HFS_CI_MISSING_CANON', 'HFS_DEP_VERSION_SKEW', 'HFS_CONTRACT_SNAPSHOT_DRIFT', 'HFS_MCP_TOOLS_SNAPSHOT',
     'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_BYPASS_MARKER', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'BE_INTEGRATION_SPEC_MISSING', 'FE_GRAPHQL_CONTRACT', 'FE_NO_TESTS', 'HFS_MONO_WORKSPACES', 'HFS_MONO_FE_WORKSPACE', 'HFS_MONO_NEST_PROJECTS', 'HFS_MONO_WORKSPACE_DEP', 'BE_CLI_REQUIRED', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG', 'HFS_SERVICE_PLACEMENT', 'HFS_IMAGE_UNPINNED', 'HFS_SERVICE_STACK_DECLARATION', 'HFS_EVENT_CONTRACT', 'BE_ASYNC_SPEC_MISSING', 'BE_SAGA_STEP_COMPENSATION', 'BE_SAGA_STATE_VERSIONED', 'BE_SAGA_EVENT_CONTRACT', 'BE_SAGA_CONSUMER_DEDUPE', 'BE_EVENT_CLASS_CONTRACT', 'BE_PATTERN_SPEC_MISSING', 'BE_CONTRACT_BREAKING', 'BE_KIND_DECLARATION', 'BE_KIND_EMPTY', 'HFS_DOCKER_BUILD_CONTEXT', 'HFS_DOCKER_STAGES', 'HFS_DOCKER_ENTRY', 'HFS_DOCKER_BASE_PIN', 'HFS_DOCKER_SECRETS', 'BE_SAGA_E2E_MISSING',
     'FE_STACK_FORBIDDEN', 'HFS_EDITION_FORBIDDEN_PRESENT', 'HFS_BACKING_UNDECLARED', 'HFS_BACKING_UNUSED', 'HFS_LITE_SECRET_CUSTODY', 'HFS_STARCIWORK_LITE_FORBIDDEN',
     'DB_MIGRATION_SHAPE', 'DB_RLS_REQUIRED', 'DB_DYNAMIC_DDL', 'DB_POLICY_SHAPE', 'DB_DEFINER_SAFE', 'DB_STORAGE_POLICY', 'LITE_DB_MIGRATION',

package/runtime/scripts/hfs/coverage-scope.d.mts

@@ -84,4 +84,19 @@ export declare function measuredBy({ roots, roles, files, excludes }: {
 }): (file: string) => boolean;
 /** True when the be-relative `file` is measured by the scope of the whole manifest (measuredBy). */
 export declare const isMeasured: (manifest: ScopeManifest, file: string) => boolean;
+/** The measured scope of the app's root packages, every path app-relative: the folders that hold specs, the files measured and the ones never measured. */
+export interface PackagesCoverage {
+    folders: string[];
+    files: string[];
+    excludes: string[];
+}
+/**
+ * THE derivation of what the root packages measure (BE-TEST-13): every TypeScript file below a package's `src/` but its front-end subtrees and barrels, at
+ * 100 per file in the back end's unit run. The rendered be/jest.config.js, Sonar's coverage exclusions and sources, Codecov's paths and R273 read it.
+ */
+export declare function packagesCoverage(folders: readonly string[]): PackagesCoverage;
+/** The app-relative folders of the root packages a tracked file list holds: each `packages/<name>/` with a `package.json` and a `src/`, the registry aside. */
+export declare function rootPackageFoldersOf(files: readonly string[]): string[];
+/** The one test of whether an app-relative file is measured by a packages scope (a spec never is): R273 asks it. */
+export declare function packageMeasuredBy({ files, excludes }: PackagesCoverage): (file: string) => boolean;
 export {};