@starci/hfs 5.3.0 → 5.5.0

package/runtime/scripts/hfs/coverage-scope.mjs

@@ -243,3 +243,29 @@ export function measuredBy({ roots, roles, files, excludes }) {
 }
 /** True when the be-relative `file` is measured by the scope of the whole manifest (measuredBy). */
 export const isMeasured = (manifest, file) => measuredBy(coverageScope(manifest))(file);
+/**
+ * The parts of a root workspace package (`packages/<name>` at the app root, PROJECT-3) that are never measured: its workbench and its public face (front
+ * ends, judged by the front-end canon and the Grammar lint) and its barrels. Everything else below its `src/` is its logic.
+ */
+const PACKAGE_UNMEASURED = Object.freeze(['src/workbench/**', 'src/public/**', 'src/**/index.ts']);
+/**
+ * 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 function packagesCoverage(folders) {
+    const sorted = [...new Set(folders)].sort(byCodeUnit);
+    return { folders: sorted, files: sorted.map((folder) => `${folder}/src/**/*.ts`), excludes: sorted.flatMap((folder) => PACKAGE_UNMEASURED.map((glob) => `${folder}/${glob}`)) };
+}
+/** The registry of the module packages (slot app.module-registry): managed, it lists the modules and carries no logic of its own. */
+const PACKAGE_REGISTRY = 'modules';
+/** 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 function rootPackageFoldersOf(files) {
+    const names = new Set(files.map((file) => /^packages\/([^/]+)\/package\.json$/.exec(file)?.[1]).filter((name) => name !== undefined && name !== PACKAGE_REGISTRY));
+    return [...names].filter((name) => files.some((file) => file.startsWith(`packages/${name}/src/`))).map((name) => `packages/${name}`).sort(byCodeUnit);
+}
+/** The one test of whether an app-relative file is measured by a packages scope (a spec never is): R273 asks it. */
+export function packageMeasuredBy({ files, excludes }) {
+    const measured = files.map((glob) => globExpression(glob));
+    const unmeasured = excludes.map((glob) => globExpression(glob));
+    return (file) => !/\.spec\.ts$/.test(file) && measured.some((glob) => glob.test(file)) && !unmeasured.some((glob) => glob.test(file));
+}

package/runtime/scripts/hfs/db-squash.mjs

@@ -2,7 +2,7 @@
 // cutover whose production starts on an empty database. Nothing is rebuilt from migration SQL: the source's schema is dumped with its
 // privileges, the objects of the extensions the target image lacks (--drop-extension) and every function or view whose body reaches their
 // schemas are left out by name, the role facts a per-database dump loses go to a marked section of db/bootstrap.sql, and the reference rows
-// of --seed-tables go to db/seed.sql. The verb proves its own output before it writes anything: a scratch container of the app's db image
+// of --seed-tables go to .starcistacks/seeds/sql/reference.sql, an entry of the shared seed level (every environment). The verb proves its own output before it writes anything: a scratch container of the app's db image
 // replays bootstrap + baseline + seed (the seed twice) and the same projection read back from the replay must equal the source's, or it
 // refuses with the differences. The source is only read; its migration history is never changed.
 import fs from 'node:fs';
@@ -12,9 +12,12 @@ import { randomBytes } from 'node:crypto';
 import { DB_DOCKERFILE, DB_IMAGE_CONTEXT } from '../../../db/image.mjs';
 import { DbVerbError } from './db-errors.mjs';
 import { BOOTSTRAP_FILE, BOOTSTRAP_SQUASH_BEGIN, BOOTSTRAP_SQUASH_END, SEED_FILE, bootstrapSection } from './rules/database-constants.mjs';
+import { addSeedEntries } from './stack-seeds-config.mjs';
 /** The extensions a lite app's db image does not ship, dropped unless --drop-extension names others (pgmq stays: it is the lite event bus). */
 export const DEFAULT_DROPPED_EXTENSIONS = Object.freeze(['pg_net', 'pg_cron']);
 export const SEED_HEADER = '-- Generated by starci app db baseline --squash';
+/** The entry of the shared seed level that declares the reference rows the squash writes (upserted on every change of them). */
+const SQUASH_SEED_ENTRY = { id: 'reference', kind: 'sql', path: 'sql/reference.sql', target: 'primary', mode: 'upsert' };
 // Roles of a hosted platform (Supabase) that a self-hosted lite database never has; a grant naming one is platform state, not the app's.
 const PLATFORM_ROLE = /^(?:supabase_\w+|authenticator|dashboard_user|pgbouncer)$/;
 // Role-level settings carried to the bootstrap; any other setting of a carried role is refused, so no secret travels.
@@ -566,8 +569,12 @@ export function squashBaseline({ root, opts, plan, urlEnv, connection, commandOf
         stdout(`proof: bootstrap + baseline + seed (twice) replayed on ${image}; schema, grants, roles and seed rows equal the source minus ${config.dropped.join(', ')}\n`);
         if (!opts.execute)
             return 0;
-        for (const [file, text] of files)
+        for (const [file, text] of files) {
+            fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
             fs.writeFileSync(path.join(root, file), text, { flag: file === plan.file ? 'wx' : 'w' });
+        }
+        if (projected.seed)
+            addSeedEntries(root, null, [SQUASH_SEED_ENTRY]);
         archive();
         return 0;
     }

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

@@ -140,7 +140,7 @@ function observeBlockProblems(observe) {
         bad.push('observe.reporter must name the optional error reporter');
     return bad;
 }
-const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'lexicon', 'observe']);
+const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'modules', 'lexicon', 'observe']);
 const RUNTIME_DECLARATION_KEYS = new Set(['hfs', 'kind', 'project']);
 function productDeclarationProblems(declaration, profiles) {
     const bad = [];
@@ -150,6 +150,8 @@ function productDeclarationProblems(declaration, profiles) {
     bad.push(...dbBlockProblems(declaration.db), ...lexiconBlockProblems(declaration.lexicon), ...observeBlockProblems(declaration.observe));
     if (declaration.browser !== undefined && declaration.browser !== true)
         bad.push('browser is `true` when the app has a browser journey (slot app.browser), and is left out otherwise');
+    if (declaration.modules !== undefined && declaration.modules !== 'data')
+        bad.push('modules is `"data"` when the app keeps its modules as data (seeds, no rendered registry package), and is left out otherwise');
     if (declaration.kind !== APP_KIND)
         bad.push(`kind must be ${APP_KIND} (a product is one app repository with a be and an fe side) or ${RUNTIME_KIND} (the StarCi runtime repository)`);
     if (!isPlainObject(declaration.sides) || Object.keys(declaration.sides).sort(byCodeUnit).join() !== profiles.join()) {

package/runtime/scripts/hfs/rules/app-root.mjs

@@ -4,7 +4,8 @@
 //   (HFS_MONO_*, monorepo.mjs), the one cli app (BE_CLI_REQUIRED, cli.mjs), BE_INTEGRATION_SPEC_MISSING (R112,
 //   integration-specs.mjs), FE_GRAPHQL_CONTRACT (R113, fe-contract-documents.mjs), HFS_CI_MISSING_CANON (R13, pipeline.mjs),
 //   BE_TEST_TOPOLOGY (R47, test-topology.mjs), HFS_PROOF_COMMAND_FILE_MISSING (R105, proof-commands.mjs), the app front-end
-//   tree (FE_WIRE_GENERATED, FE_I18N_PLACEMENT, frontend-tree.mjs) and HFS_STACKS_SHAPE (R10, stacks.mjs).
+//   tree (FE_WIRE_GENERATED, FE_I18N_PLACEMENT, frontend-tree.mjs), HFS_STACKS_SHAPE (R10, stacks.mjs) and the root seed data
+//   (HFS_SEED_*: R375, seeds.mjs).
 import { cliFindings } from './cli.mjs';
 import { contractCompatFindings } from './contract-compat.mjs';
 import { depFindings } from './deps.mjs';
@@ -19,6 +20,7 @@ import { peerIntegrationFindings } from './peer-integrations.mjs';
 import { pipelineFindings } from './pipeline.mjs';
 import { proofCommandFindings } from './proof-commands.mjs';
 import { sagaFindings } from './saga.mjs';
+import { seedsFindings } from './seeds.mjs';
 import { serviceFindings } from './services.mjs';
 import { stacksFindings } from './stacks.mjs';
 import { testTopologyFindings } from './test-topology.mjs';
@@ -46,5 +48,6 @@ export function appRootFindings({ repoRoot, files, all, repo, resolver, pins, ph
         ...proofCommandFindings({ repoRoot, files: all, resolver, sides: Object.keys(repo.sides ?? {}) }),
         ...appFrontendFindings({ repoRoot, files: all, repo, phase }),
         ...stacksFindings({ repoRoot, files, resolver }),
+        ...seedsFindings({ repoRoot, files }),
     ];
 }

package/runtime/scripts/hfs/rules/ci-standard.mjs

@@ -6,7 +6,7 @@
 //   sonar-lint-per-side    a lint with --out names --side
 //   required-providers      no continue-on-error; Codecov fail_ci_if_error true; no availability probe, no secret-gated Codecov or Sonar step
 //   test-sharding          the test job is a shard matrix; each shard runs --shard=i/N with STARCI_COVERAGE_SHARD and no threshold or pass-empty flag; the coverage job merges, then proves
-//   lint-parallel          the lint job is a matrix over side [be, fe]
+//   lint-parallel          the lint job is a matrix over side [be, fe], or [be, fe, packages] in an app with root packages
 //   cache-saved-always     no cache keyed by the commit sha; actions/cache/save runs under if: always()
 //   timeouts               every job declares timeout-minutes
 //   sha-pinned-actions     every remote `uses:` names a 40-hex commit sha (docker:// a sha256 digest; ./ local actions allowed)
@@ -123,7 +123,8 @@ function testSharding(doc, say) {
 }
 function lintParallel(doc, say) {
     const sides = record(doc.jobs?.lint) ? doc.jobs.lint.strategy?.matrix?.side : null;
-    return Array.isArray(sides) && sides.map(String).sort(byCodeUnit).join() === 'be,fe' ? [] : [say('lint-parallel', 'the lint job must be a matrix over side [be, fe]')];
+    const joined = Array.isArray(sides) ? sides.map(String).sort(byCodeUnit).join() : '';
+    return joined === 'be,fe' || joined === 'be,fe,packages' ? [] : [say('lint-parallel', 'the lint job must be a matrix over side [be, fe], with packages when the app has root packages')];
 }
 function cacheSavedAlways(doc, say) {
     const out = [];
@@ -174,8 +175,8 @@ function sonarLintPerSide(doc, say) {
     for (const [id, job] of jobsOf(doc)) {
         for (const step of stepsOf(job)) {
             const run = runOf(step);
-            if (/\b(?:npm run lint|app check)\b/.test(run) && /\s--out\b/.test(run) && !/\s--side\s+(?:be\b|fe\b|\$\{\{\s*matrix\.side\s*\}\})/.test(run)) {
-                out.push(say('sonar-lint-per-side', `job ${id}, step ${step.name ?? 'lint'}: a lint with a Sonar import must name its side (--side be|fe) and the reports are merged afterwards; a combined lint with Sonar breaks the standard`));
+            if (/\b(?:npm run lint|app check)\b/.test(run) && /\s--out\b/.test(run) && !/\s--side\s+(?:be\b|fe\b|packages\b|\$\{\{\s*matrix\.side\s*\}\})/.test(run)) {
+                out.push(say('sonar-lint-per-side', `job ${id}, step ${step.name ?? 'lint'}: a lint with a Sonar import must name its side (--side be|fe|packages) and the reports are merged afterwards; a combined lint with Sonar breaks the standard`));
             }
         }
     }

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

@@ -3,7 +3,7 @@
 // lcov carries lines, functions and branches; the unit runner also enforces its statement threshold.
 import fs from 'node:fs';
 import path from 'node:path';
-import { coverageScope, measuredBy } from '../coverage-scope.mjs';
+import { coverageScope, measuredBy, packageMeasuredBy, packagesCoverage, rootPackageFoldersOf } from '../coverage-scope.mjs';
 import { editionRuleParams, effectiveSlot, slotInEdition } from '../edition-slots.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { found } from './read.mjs';
@@ -120,12 +120,17 @@ function inventory({ files, all, repo, manifest }) {
     const effective = manifestOfEdition(manifest, repo.edition ?? 'full');
     const scope = coverageScope(effective, repo.providers ?? repo.sides?.be?.providers ?? []);
     const measures = measuredBy(scope);
-    const candidates = [...new Set((all ?? files ?? []).map(slash))].filter((file) => file.startsWith(prefix) && file.endsWith('.ts') && !SPEC.test(file)).sort(byCodeUnit);
+    const tracked = [...new Set((all ?? files ?? []).map(slash))];
+    // At the app root the root packages are measured too, by the same unit run as the back end (packagesCoverage, BE-TEST-13).
+    const packages = packagesCoverage(prefix ? rootPackageFoldersOf(tracked) : []);
+    const measuresPackage = packageMeasuredBy(packages);
+    const inPackage = (file) => packages.folders.some((folder) => file.startsWith(`${folder}/src/`));
+    const candidates = tracked.filter((file) => (file.startsWith(prefix) || inPackage(file)) && file.endsWith('.ts') && !SPEC.test(file)).sort(byCodeUnit);
     const measured = [];
     const unmeasured = [];
     for (const file of candidates)
-        (measures(file.slice(prefix.length)) ? measured : unmeasured).push(file);
-    return { measured, unmeasured, unmeasuredScopes: scope.none.map((entry) => `${prefix}${entry}`), scope, prefix };
+        ((inPackage(file) ? measuresPackage(file) : measures(file.slice(prefix.length))) ? measured : unmeasured).push(file);
+    return { measured, unmeasured, unmeasuredScopes: [...scope.none.map((entry) => `${prefix}${entry}`), ...packages.excludes], scope, prefix };
 }
 function sourcePath(source) {
     if (source.startsWith('file:')) {
@@ -144,6 +149,9 @@ function matchesSource(source, file, prefix) {
     const choices = [file, relative, ...(prefix ? [] : [`be/${file}`])];
     const windows = /^[a-z]:\//i.test(source) || source.startsWith('//');
     const absolute = source.startsWith('/') || windows;
+    // A relative source is relative to the jest root, the back end: a root package's file is `../packages/<name>/...` there.
+    if (!absolute && prefix && slash(`${prefix}${source}`) === file)
+        return true;
     const key = windows ? source.toLowerCase() : source;
     return choices.some((choice) => {
         const candidate = windows ? choice.toLowerCase() : choice;

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

@@ -1,8 +1,9 @@
-// database-config.mjs - the database content checks of db/ (R259: extensions, custody SQL, destructive migrations, seed data). It starts no
+// database-config.mjs - the database content checks of db/ and seeds/ (R259: extensions, custody SQL, destructive migrations, seed data). It starts no
 // database and no Docker process.
 import { found, readText } from './read.mjs';
-import { DB_EXTENSION_ALLOWED, DB_VAULT_WRITE, HFS_SEED_PII, isActiveMigration, SEED_FILE, } from './database-constants.mjs';
-import { databaseExecutableTokens, databaseSqlStatements, databaseSqlTokens, destructiveMigrationFindings } from './database-migrations.mjs';
+import { DB_EXTENSION_ALLOWED, DB_VAULT_WRITE, HFS_SEED_PII, isActiveMigration, } from './database-constants.mjs';
+import { databaseExecutableTokens, databaseSqlStatements, destructiveMigrationFindings } from './database-migrations.mjs';
+import { isSeedFile, seedLiterals } from './seeds.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 const DEFAULT_EXTENSIONS = ['pgcrypto', 'pg_trgm', 'vector', 'uuid-ossp', 'unaccent', 'btree_gist', 'pgmq'];
 const word = (token, value) => token?.t === 'word' && token.v === value;
@@ -108,10 +109,10 @@ function seedPiiFindings(repoRoot, seeds) {
         const text = readText(repoRoot, file);
         if (text === null)
             continue;
-        for (const token of databaseSqlTokens(text)) {
-            if (!['string', 'body'].includes(token.t) || !piiLiteral(token.v))
+        for (const literal of seedLiterals(file, text)) {
+            if (!piiLiteral(literal.v))
                 continue;
-            findings.push(found(HFS_SEED_PII, file, `${file}:${token.line} contains an email or phone literal; seed data uses synthetic identities and the example.test domain`, { line: token.line }));
+            findings.push(found(HFS_SEED_PII, file, `${file}:${literal.line} contains an email or phone literal; seed data uses synthetic identities and the example.test domain`, { line: literal.line }));
         }
     }
     return findings;
@@ -127,7 +128,7 @@ export function databaseConfigFindings({ repoRoot, files = [], all = files, repo
     for (const { file, tokens } of sources)
         findings.push(...extensionFindings(file, tokens, new Set(parameters.extensions)), ...custodySqlFindings(file, tokens));
     findings.push(...destructiveMigrationFindings({ repoRoot, migrations, files: all }));
-    const seeds = all.filter((file) => file === SEED_FILE || /^\.starcistacks\/[^/]+\/seeds\/.+\.sql$/.test(file));
+    const seeds = all.filter((file) => isSeedFile(file) && /\/(?:sql|data)\/.+\.(?:sql|json|ya?ml)$/.test(file));
     findings.push(...seedPiiFindings(repoRoot, seeds));
     return findings.filter((finding) => inScope(finding.path));
 }

package/runtime/scripts/hfs/rules/database-constants.d.mts

@@ -18,7 +18,8 @@ export declare const MIGRATIONS_DIR = "db/migrations";
 export declare const MIGRATIONS_ARCHIVE_DIR = "db/migrations/archive";
 /** True for a migration `starci app db migrate` applies: a path under db/migrations/ outside the archive. */
 export declare const isActiveMigration: (file: string) => boolean;
-export declare const SEED_FILE = "db/seed.sql";
+/** The shared SQL seed `db baseline --squash --seed-tables` writes the reference rows to, an entry of the shared seed level (R375). */
+export declare const SEED_FILE = ".starcistacks/seeds/sql/reference.sql";
 /** The managed pre-migration bootstrap (slot app.db.bootstrap): `starci app sync` renders it, and `db baseline --squash` owns one marked section. */
 export declare const BOOTSTRAP_FILE = "db/bootstrap.sql";
 export declare const BOOTSTRAP_SQUASH_BEGIN = "-- >>> starci app db baseline --squash: roles, role settings and grants a per-database dump loses (regenerate with the verb; do not edit) >>>";

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

@@ -19,7 +19,8 @@ export const MIGRATIONS_DIR = `${DB_DIR}/migrations`;
 export const MIGRATIONS_ARCHIVE_DIR = `${MIGRATIONS_DIR}/archive`;
 /** True for a migration `starci app db migrate` applies: a path under db/migrations/ outside the archive. */
 export const isActiveMigration = (file) => file.startsWith(`${MIGRATIONS_DIR}/`) && !file.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`);
-export const SEED_FILE = `${DB_DIR}/seed.sql`;
+/** The shared SQL seed `db baseline --squash --seed-tables` writes the reference rows to, an entry of the shared seed level (R375). */
+export const SEED_FILE = '.starcistacks/seeds/sql/reference.sql';
 /** The managed pre-migration bootstrap (slot app.db.bootstrap): `starci app sync` renders it, and `db baseline --squash` owns one marked section. */
 export const BOOTSTRAP_FILE = `${DB_DIR}/bootstrap.sql`;
 export const BOOTSTRAP_SQUASH_BEGIN = '-- >>> starci app db baseline --squash: roles, role settings and grants a per-database dump loses (regenerate with the verb; do not edit) >>>';

package/runtime/scripts/hfs/rules/database.d.mts

@@ -4,8 +4,8 @@ export declare const DB_DEFINER_REVOKE = "DB_DEFINER_REVOKE";
 export { DB_DEFINER_SAFE, DB_DYNAMIC_DDL, DB_MIGRATION_SHAPE, DB_POLICY_SHAPE, DB_RLS_REQUIRED, DB_STORAGE_POLICY, LITE_DB_MIGRATION, } from './database-constants.mjs';
 import type { Finding, Parsed } from './rule-types.mjs';
 /**
- * LITE_DB_MIGRATION: a lite app's schema lives only under db/: no supabase/ tree and no SQL file outside db/ (but a
- * .starcistacks seed), and every SQL file under db/ is a migration, the archive, the seed or nothing.
+ * LITE_DB_MIGRATION: a lite app's schema lives only under db/: no supabase/ tree and no SQL file outside db/ but its seed data (the seed
+ * levels of .starcistacks/, judged by R375), and every SQL file under db/ is a migration, the archive, the bootstrap or nothing.
  */
 export declare function liteDbPathFindings(files: string[]): Finding[];
 /**

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

@@ -5,7 +5,8 @@ import { contractReleaseFindings, defaultGit, migrationShapeFindings } from './d
 import { migrationSetPolicyFindings, sqlAnalysis } from './database-sql.mjs';
 import { migrationSetDefinerFindings } from './database-plpgsql.mjs';
 import { databaseAccessFindings } from './database-access.mjs';
-import { DB_DIR, DB_MIGRATION_SHAPE, isActiveMigration, LITE_DB_MIGRATION, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
+import { BOOTSTRAP_FILE, DB_DIR, DB_MIGRATION_SHAPE, isActiveMigration, LITE_DB_MIGRATION, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
+import { isSeedFile } from './seeds.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 import { eachInOrder } from '../../lib/in-order.mjs';
 export { migrationStamp } from './database-migrations.mjs';
@@ -14,11 +15,9 @@ export const DB_DEFINER_REVOKE = 'DB_DEFINER_REVOKE';
 export { DB_DEFINER_SAFE, DB_DYNAMIC_DDL, DB_MIGRATION_SHAPE, DB_POLICY_SHAPE, DB_RLS_REQUIRED, DB_STORAGE_POLICY, LITE_DB_MIGRATION, } from './database-constants.mjs';
 /** The schemas the app's tables live in; no schema is exposed to a browser, which reaches data only through the back end. */
 const APP_SCHEMAS = new Set(['public']);
-/** A .starcistacks seed is the one SQL file a lite app keeps outside db/. */
-const STACK_SEED = /^\.starcistacks\/[^/]+\/seeds\/.+\.sql$/;
 /**
- * LITE_DB_MIGRATION: a lite app's schema lives only under db/: no supabase/ tree and no SQL file outside db/ (but a
- * .starcistacks seed), and every SQL file under db/ is a migration, the archive, the seed or nothing.
+ * LITE_DB_MIGRATION: a lite app's schema lives only under db/: no supabase/ tree and no SQL file outside db/ but its seed data (the seed
+ * levels of .starcistacks/, judged by R375), and every SQL file under db/ is a migration, the archive, the bootstrap or nothing.
  */
 export function liteDbPathFindings(files) {
     const findings = [];
@@ -27,10 +26,12 @@ export function liteDbPathFindings(files) {
             findings.push(found(LITE_DB_MIGRATION, file, `${file} is a Supabase project file; a lite app keeps its schema in ${MIGRATIONS_DIR}/<ts14>_<kebab>.sql (move the migrations, delete supabase/)`, {}));
             continue;
         }
-        if (!file.endsWith('.sql') || STACK_SEED.test(file))
+        if (!file.endsWith('.sql') || isSeedFile(file))
             continue;
         if (!file.startsWith(`${DB_DIR}/`))
             findings.push(found(LITE_DB_MIGRATION, file, `${file} is SQL outside ${DB_DIR}/; a schema change is one ${MIGRATIONS_DIR}/<ts14>_<kebab>.sql`, {}));
+        else if (!isActiveMigration(file) && !file.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`) && file !== BOOTSTRAP_FILE)
+            findings.push(found(LITE_DB_MIGRATION, file, `${file} is SQL under ${DB_DIR}/ that is no migration, archive or bootstrap; seed data is an entry of a seed level, .starcistacks/seeds/sql/ or .starcistacks/<env>/seeds/sql/ (starci app codemod seeds-layout moves it)`, {}));
     }
     return findings;
 }

package/runtime/scripts/hfs/rules/docker.mjs

@@ -3,7 +3,8 @@
 // The Dockerfile is app-owned (starci app scaffold writes it once from templates/<side>/image) and judged here, structurally, from its parsed
 // instructions (scripts/lib/dockerfile.mjs), never by matching the text:
 //   HFS_DOCKER_BUILD_CONTEXT  the header comment states the app's own build command (`starci docker build <app>` or `docker build -f <side>/apps/<app>/Dockerfile ... .`, the
-//                             context the app root) and no COPY or ADD source leaves the context (`..`, an absolute path)
+//                             context the app root) and no COPY or ADD source leaves the context (`..`, an absolute path); a Next image of a front end
+//                             that reads be/contracts/ copies that folder exactly when the app holds it (its codegen input; a COPY of a missing folder fails the build)
 //   HFS_DOCKER_STAGES         a `build` stage and a last `runtime` stage; the runtime is unprivileged (`USER node`) and runs no build; every install
 //                             is `npm ci` (never `npm install`); a back-end runtime installs `--omit=dev --ignore-scripts`, a front-end runtime installs nothing
 //   HFS_DOCKER_ENTRY          the runtime starts the app's own built entry (be: node be/dist/apps/<app>/src/main.js; fe: node fe/apps/<app>/server.js); an api or
@@ -40,6 +41,8 @@ const SECRET_FOLDERS = new Set(['.starcistacks', '.secrets', '.volume', '.git',
 const SECRET_SUFFIXES = ['.key', '.pem', '.p12', '.pfx', '.crt'];
 const BUILD_TOOLS = new Set(['tsc', 'tsc-alias', 'next', 'turbo', 'nest', 'webpack', 'vite', 'esbuild']);
 const DIGEST = /@sha256:[0-9a-f]{64}$/;
+/** The back-end contracts a front end reads in place (`sides.fe.reads`), its codegen input. */
+const CONTRACTS = 'be/contracts';
 /** The path of the Dockerfile of a be or fe app, app-relative. */
 export const dockerfilePath = (side, app) => `${side}/apps/${app}/Dockerfile`;
 /** The entry a built be app starts (from the app root). */
@@ -93,14 +96,16 @@ const statesBuildCommand = (parsed, wanted, app) => parsed.comments.some((commen
     const flag = parts.indexOf('-f', build);
     return flag > 0 && parts[flag + 1] === wanted && parts.at(-1) === '.';
 });
+/** The context sources of a COPY or ADD (none for a COPY from a stage). */
+const contextSources = (item) => {
+    const parts = words(item.text);
+    if (parts.some((part) => part.startsWith('--from=')))
+        return [];
+    return parts.filter((part) => !part.startsWith('--')).slice(0, -1);
+};
 function copySourceFindings(file, item) {
     const findings = [];
-    const parts = words(item.text).filter((part) => !part.startsWith('--'));
-    const sources = parts.slice(0, -1);
-    const fromStage = words(item.text).some((part) => part.startsWith('--from='));
-    if (fromStage)
-        return findings;
-    for (const source of sources) {
+    for (const source of contextSources(item)) {
         if (/^[a-z]+:\/\//i.test(source))
             continue;
         const segments = source.split('/');
@@ -119,6 +124,15 @@ function contextFindings(file, parsed, side, app) {
         findings.push(...copySourceFindings(file, item));
     return findings;
 }
+/** R187: a Next image copies be/contracts, the contract its codegen reads, when the app holds it, and never when it does not. */
+function contractCopyFindings(file, parsed, holdsContracts) {
+    const copies = parsed.instructions.filter((entry) => entry.keyword === 'COPY' || entry.keyword === 'ADD').find((entry) => contextSources(entry).some((source) => source.replace(/\/$/u, '') === CONTRACTS));
+    if (copies && !holdsContracts)
+        return [found(DOCKER_BUILD_CONTEXT, file, `${file}:${copies.line} copies ${CONTRACTS}, which the app does not hold (its back end emits no contract), so the image build fails; drop the COPY until a contract is emitted.`, { line: copies.line, source: CONTRACTS })];
+    if (!copies && holdsContracts)
+        return [found(DOCKER_BUILD_CONTEXT, file, `${file} does not copy ${CONTRACTS}, the contract the front end's codegen reads; add \`COPY ${CONTRACTS} ${CONTRACTS}\` before the codegen.`, { source: CONTRACTS })];
+    return [];
+}
 /** R188: the stages and the install, the user and the build discipline of each. */
 function stageInstallFindings(file, stages) {
     const findings = [];
@@ -330,6 +344,8 @@ export function dockerFindings({ repoRoot, files, repo }) {
         ...repo.sides.fe.apps.map((entry) => ({ side: 'fe', app: entry.name, kind: entry.kind })),
     ];
     const ts = apps.some((entry) => entry.side === 'fe' || entry.kind === 'api') ? typescriptFor(repoRoot) : null;
+    const readsContracts = (repo.sides.fe.reads ?? []).includes(`${CONTRACTS}/`);
+    const holdsContracts = files.some((name) => name.startsWith(`${CONTRACTS}/`));
     return apps.flatMap(({ side, app, kind }) => {
         const file = dockerfilePath(side, app);
         if (!tracked.has(file))
@@ -340,6 +356,7 @@ export function dockerFindings({ repoRoot, files, repo }) {
         const parsed = parseDockerfile(text);
         return [
             ...contextFindings(file, parsed, side, app),
+            ...(side === 'fe' && kind === 'next' && readsContracts ? contractCopyFindings(file, parsed, holdsContracts) : []),
             ...stageFindings(file, parsed, side, kind),
             ...entryFindings({ repoRoot, file, parsed, side, app, kind, project: repo.project, ts }),
             ...healthReachabilityFindings({ repoRoot, file, parsed, side, app, kind, ts }),

package/runtime/scripts/hfs/rules/monorepo.d.mts

@@ -1,7 +1,7 @@
 import type { Parsed, Repo } from './rule-types.mjs';
 /** The npm workspaces of every app, in this order. */
 export declare const WORKSPACES: readonly string[];
-/** The workspace of the app's own root packages (slot app.packages: packages/agent-sdk, packages/module-<name>), added after the fe ones once one is tracked. */
+/** The workspace of the app's own root packages (slot app.packages: packages/<name>, the agent SDK, a block library or a module package), added after the fe ones once one is tracked. */
 export declare const ROOT_PACKAGES_WORKSPACE = "packages/*";
 /** The workspaces the tracked tree `files` calls for: the fe ones, then `packages/*` when a root package tracks its package.json. */
 export declare const workspacesFor: (files: readonly string[]) => readonly string[];

package/runtime/scripts/hfs/rules/monorepo.mjs

@@ -22,7 +22,7 @@ const MONO_NEST_PROJECTS = 'HFS_MONO_NEST_PROJECTS';
 const MONO_WORKSPACE_DEP = 'HFS_MONO_WORKSPACE_DEP';
 /** The npm workspaces of every app, in this order. */
 export const WORKSPACES = Object.freeze(['fe/apps/*', 'fe/packages/*']);
-/** The workspace of the app's own root packages (slot app.packages: packages/agent-sdk, packages/module-<name>), added after the fe ones once one is tracked. */
+/** The workspace of the app's own root packages (slot app.packages: packages/<name>, the agent SDK, a block library or a module package), added after the fe ones once one is tracked. */
 export const ROOT_PACKAGES_WORKSPACE = 'packages/*';
 /** The workspaces the tracked tree `files` calls for: the fe ones, then `packages/*` when a root package tracks its package.json. */
 export const workspacesFor = (files) => (files.some((file) => /^packages\/[^/]+\/package\.json$/.test(file)) ? [...WORKSPACES, ROOT_PACKAGES_WORKSPACE] : WORKSPACES);

package/runtime/scripts/hfs/rules/seeds.d.mts

@@ -0,0 +1,21 @@
+import type { Finding } from './rule-types.mjs';
+export declare const HFS_SEEDS_SHAPE = "HFS_SEEDS_SHAPE";
+export declare const HFS_SEED_MANIFEST = "HFS_SEED_MANIFEST";
+export declare const HFS_SEED_DDL = "HFS_SEED_DDL";
+export declare const HFS_SEED_DATA_SCHEMA = "HFS_SEED_DATA_SCHEMA";
+export declare const HFS_SEED_TEST_DATA = "HFS_SEED_TEST_DATA";
+export declare const HFS_SEED_SECRET_REF = "HFS_SEED_SECRET_REF";
+/** True for a tracked file of a seed level (the `.gitkeep` placeholders aside). */
+export declare const isSeedFile: (file: string) => boolean;
+/** The environments of the stack declaration of `repoRoot` with their runtime, or null when it declares none that parses to a mapping. */
+export declare function declaredEnvironments(repoRoot: string): Map<string, string> | null;
+/** The literals of a seed document or SQL file, each with its line: SQL strings and bodies, or every string value of a JSON or YAML document. */
+export declare function seedLiterals(file: string, text: string): Array<{
+    v: string;
+    line: number;
+}>;
+/** The findings of R375 over the tracked files of an app root. */
+export declare function seedsFindings({ repoRoot, files }: {
+    repoRoot: string;
+    files: string[];
+}): Finding[];

package/runtime/scripts/hfs/rules/seeds.mjs

@@ -0,0 +1,194 @@
+// seeds.mjs - R375, the seed data of an app (contexts/project/stacks.md PROJECT-STACKS-12). It lives in two levels of `.starcistacks/`, the
+// shared `seeds/` and `<env>/seeds/` of an environment the stack declaration names, each a manifest (`seeds.yaml`, stack-seeds-config.mjs) and
+// the folders `sql/`, `data/` and `files/`:
+//   HFS_SEEDS_SHAPE       a seed file outside those folders, a level of an undeclared environment, custody (a sealed member, a key) in a level;
+//   HFS_SEED_MANIFEST     a manifest that is missing, does not parse or names a path that is not there, a file no entry covers, an after cycle;
+//   HFS_SEED_DDL          a statement of a sql entry that changes the schema or its grants (seed data is never a migration);
+//   HFS_SEED_DATA_SCHEMA  a data document that does not validate against the JSON schema its entry names;
+//   HFS_SEED_TEST_DATA    a test marker (an example.test identity, a uat- or test- prefix) in a level a production environment applies (the
+//                         shared level and the level of every environment that is not docker-compose), outside its one test-account entry;
+//   HFS_SEED_SECRET_REF   a document's secret reference `{ "secret": "<member>" }` to a name that is no seeds-<name>, or to a member the
+//                         environment does not seal (`.starcistacks/<env>/secrets/<member>.enc.yaml`; the shared level: every environment).
+// A plaintext secret on any seed line is R06's and a real identity R259's (HFS_SEED_PII). A finding names the file and line, never a value.
+import path from 'node:path';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { validateAgainstSchema } from '../../lib/json-schema.mjs';
+import { findStackDeclaration } from '../../lib/stack-declaration.mjs';
+import { databaseExecutableTokens, databaseSqlStatements, databaseSqlTokens } from './database-migrations.mjs';
+import { envelopeOf } from '../secret-document.mjs';
+import { entryFiles, isDocumentEntry, readSeedLevel, resolveSecrets, SEED_SECRET_MEMBER, secretReferences, seedDocuments, seedMemberFile, SEEDS_DIR, SEEDS_KEEP, SEEDS_MANIFEST } from '../stack-seeds-config.mjs';
+import { found, readText } from './read.mjs';
+export const HFS_SEEDS_SHAPE = 'HFS_SEEDS_SHAPE';
+export const HFS_SEED_MANIFEST = 'HFS_SEED_MANIFEST';
+export const HFS_SEED_DDL = 'HFS_SEED_DDL';
+export const HFS_SEED_DATA_SCHEMA = 'HFS_SEED_DATA_SCHEMA';
+export const HFS_SEED_TEST_DATA = 'HFS_SEED_TEST_DATA';
+export const HFS_SEED_SECRET_REF = 'HFS_SEED_SECRET_REF';
+/** What a secret's value reads as where no value is opened: the schema check and the dry run. */
+const SEALED = '[sealed]';
+/** A seed file: `.starcistacks/seeds/<rest>` or `.starcistacks/<env>/seeds/<rest>`, captured as [level folder, rest]. */
+const SEED_PATH = /^(\.starcistacks\/(?:[^/]+\/)?seeds)\/(.+)$/u;
+/** Where a file of a level may sit: the manifest, or under one of the kind folders. */
+const LEVEL_FILE = /^(?:seeds\.yaml|(?:sql|data|files)\/.+)$/u;
+/** Custody by its shape: a sealed member, a key or certificate, an env file. */
+const CUSTODY = /(?:\.enc(?:\.yaml)?|\.pem|\.key|\.p12|\.pfx|(?:^|\/)\.env(?:\..*)?)$/u;
+/** The statements a seed may not hold: each one changes the schema or its grants, which only a migration does. */
+const SCHEMA_WORDS = new Set(['create', 'alter', 'drop', 'truncate', 'grant', 'revoke', 'comment']);
+/** The words that open a block around statements (a DO block's body is read as statements, so `do begin drop ...` is a DROP). */
+const BLOCK_WORDS = new Set(['do', 'begin']);
+/** A test marker: an identity of the example.test domain, or a value that starts uat- or test-. */
+const TEST_MARKER = /@example\.test\b|^(?:uat|test)[-_]/iu;
+const DOCUMENT = /\.(?:json|ya?ml)$/u;
+/** True for a tracked file of a seed level (the `.gitkeep` placeholders aside). */
+export const isSeedFile = (file) => SEED_PATH.test(file) && !file.endsWith(`/${SEEDS_KEEP}`);
+/** The environments of the stack declaration of `repoRoot` with their runtime, or null when it declares none that parses to a mapping. */
+export function declaredEnvironments(repoRoot) {
+    const environments = findStackDeclaration(repoRoot).doc?.environments;
+    if (environments === null || typeof environments !== 'object' || Array.isArray(environments))
+        return null;
+    return new Map(Object.entries(environments).map(([name, entry]) => [name, String(entry?.runtime ?? '')]));
+}
+/** The literals of a seed document or SQL file, each with its line: SQL strings and bodies, or every string value of a JSON or YAML document. */
+export function seedLiterals(file, text) {
+    if (!DOCUMENT.test(file))
+        return databaseSqlTokens(text).flatMap((token) => (['string', 'body'].includes(token.t) ? [{ v: String(token.v), line: token.line }] : []));
+    let doc;
+    try {
+        doc = file.endsWith('.json') ? JSON.parse(text) : parseYaml(text);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const visit = (value) => {
+        if (typeof value === 'string')
+            out.push({ v: value, line: Math.max(1, text.slice(0, text.indexOf(value)).split('\n').length) });
+        else if (value !== null && typeof value === 'object')
+            for (const item of Object.values(value))
+                visit(item);
+    };
+    visit(doc);
+    return out;
+}
+/** The schema statements of one SQL seed: the line of each statement whose first word (past a block opener) changes the schema. */
+function schemaStatements(text) {
+    return databaseSqlStatements(databaseExecutableTokens(text)).flatMap((statement) => {
+        const first = statement.find((token) => !(token.t === 'word' && BLOCK_WORDS.has(token.v)));
+        return first?.t === 'word' && SCHEMA_WORDS.has(first.v) ? [{ line: first.line, word: String(first.v).toUpperCase() }] : [];
+    });
+}
+/** Where one seed file sits: the shape finding of a file outside the kind folders, of an undeclared environment's level, or of custody. */
+function shapeFinding(file, environments) {
+    const [, level = '', rest = ''] = SEED_PATH.exec(file) ?? [];
+    const env = level.split('/')[1];
+    if (CUSTODY.test(file))
+        return found(HFS_SEEDS_SHAPE, file, `${file} is custody, not seed data; a secret is sealed with sops at .starcistacks/<env>/secrets/<slug>.enc.yaml and read by *_FILE`);
+    if (env !== SEEDS_DIR && environments !== null && !environments.has(String(env)))
+        return found(HFS_SEEDS_SHAPE, file, `${file} is in the seed level of ${String(env)}, which is no environment of .starcistacks/application-stacks.yaml`);
+    if (!LEVEL_FILE.test(rest))
+        return found(HFS_SEEDS_SHAPE, file, `${file} is no part of a seed level (${SEEDS_MANIFEST}, sql/, data/, files/); starci app codemod seeds-layout moves a loose seed into it`);
+    return null;
+}
+/** The manifest findings of one level: its problems, and every file of its kind folders that no entry covers. */
+function manifestFindings(repoRoot, level, files) {
+    const manifest = `${level.dir}/${SEEDS_MANIFEST}`;
+    const own = files.filter((file) => file.startsWith(`${level.dir}/`) && file !== manifest);
+    if (own.length > 0 && !files.includes(manifest))
+        return [found(HFS_SEED_MANIFEST, manifest, `${level.dir} holds seed files but no ${SEEDS_MANIFEST}; every seed is an entry of its level's manifest`)];
+    const covered = new Set(level.entries.flatMap((entry) => entryFiles(path.join(repoRoot, level.dir), entry).map((file) => `${level.dir}/${file}`)));
+    return [
+        ...level.problems.map((problem) => found(HFS_SEED_MANIFEST, manifest, `${manifest} ${problem.at}: ${problem.message}`)),
+        ...own.filter((file) => !covered.has(file)).map((file) => found(HFS_SEED_MANIFEST, file, `${file} is listed by no entry of ${manifest}`)),
+    ];
+}
+/** The parsed JSON schema an entry names, or null when it names none or it cannot be read. */
+function entrySchema(repoRoot, entry) {
+    const text = entry.schema === null ? null : readText(repoRoot, entry.schema);
+    try {
+        return text === null ? null : parseYaml(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** The findings of the secret references of one document: a name that is no seed member, or a member an environment of the level lacks. */
+function referenceFindings(file, doc, environments, files) {
+    return secretReferences(doc).flatMap((member) => {
+        if (!SEED_SECRET_MEMBER.test(member))
+            return [found(HFS_SEED_SECRET_REF, file, `${file} references the secret ${member}; a seed references a sealed member named seeds-<name> of its environment`)];
+        const missing = environments.filter((env) => !files.has(seedMemberFile(env, member)));
+        return missing.map((env) => found(HFS_SEED_SECRET_REF, file, `${file} references ${member}, which ${seedMemberFile(env, member)} does not hold; seal it with starci app secret set --env ${env}`));
+    });
+}
+/** What the schema sees for a secret reference: the member's keys, each a sealed placeholder (the envelope names them; no value is opened). */
+function sealedShape(repoRoot, environments, member) {
+    const text = environments.map((env) => readText(repoRoot, seedMemberFile(env, member))).find((item) => item !== null) ?? null;
+    let keys = [];
+    try {
+        keys = text === null ? [] : envelopeOf(text).keys;
+    }
+    catch {
+        keys = [];
+    }
+    return Object.fromEntries(keys.map((key) => [key, SEALED]));
+}
+/** The findings of a document entry: a document off its schema (secret references read as their sealed keys) and its secret references. */
+function documentFindings(repoRoot, level, entry, scope) {
+    const manifest = `${level.dir}/${SEEDS_MANIFEST}`;
+    const schema = entrySchema(repoRoot, entry);
+    if (schema === null)
+        return [found(HFS_SEED_DATA_SCHEMA, manifest, `entry ${entry.id} names the schema ${String(entry.schema)}, which is not a readable JSON or YAML schema`)];
+    return seedDocuments(path.join(repoRoot, level.dir), entry).flatMap((document) => {
+        const file = `${level.dir}/${document.path}`;
+        if (document.error !== undefined)
+            return [found(HFS_SEED_DATA_SCHEMA, file, `${file} does not parse: ${document.error}`)];
+        const errors = validateAgainstSchema(resolveSecrets(document.doc, (member) => sealedShape(repoRoot, scope.environments, member)), schema);
+        return [
+            ...(errors.length > 0 ? [found(HFS_SEED_DATA_SCHEMA, file, `${file} does not validate against ${String(entry.schema)}: ${errors[0] ?? ''}`)] : []),
+            ...referenceFindings(file, document.doc, scope.environments, scope.files),
+        ];
+    });
+}
+/** The findings of one entry's files: DDL in SQL, documents and secret references, test markers where production applies the level. */
+function entryFindings(repoRoot, level, entry, scope) {
+    const findings = isDocumentEntry(entry) ? documentFindings(repoRoot, level, entry, scope) : [];
+    // The one test account a level declares holds test data by design; every other entry of a production level holds none.
+    const judged = scope.production && entry.kind !== 'test-account';
+    for (const file of entryFiles(path.join(repoRoot, level.dir), entry).map((name) => `${level.dir}/${name}`)) {
+        if (judged && TEST_MARKER.test(path.posix.basename(file)))
+            findings.push(found(HFS_SEED_TEST_DATA, file, `${file} is named as test data in a level a production environment applies`));
+        const text = entry.kind === 'files' ? null : readText(repoRoot, file);
+        if (text === null)
+            continue;
+        if (entry.kind === 'sql')
+            for (const { line, word } of schemaStatements(text))
+                findings.push(found(HFS_SEED_DDL, file, `${file}:${line} runs ${word}, a schema change; seed data is never a migration: the schema change is a migration (BE-PERSISTENCE-1) and a seed only writes rows`, { line }));
+        const marker = judged ? seedLiterals(file, text).find((literal) => TEST_MARKER.test(literal.v)) : undefined;
+        if (marker)
+            findings.push(found(HFS_SEED_TEST_DATA, file, `${file}:${marker.line} holds test data (an example.test identity or a uat- or test- prefix) in a level a production environment applies; the one test account of an environment is its test-account entry`, { line: marker.line }));
+    }
+    return findings;
+}
+/** The findings of R375 over the tracked files of an app root. */
+export function seedsFindings({ repoRoot, files }) {
+    const seeds = files.filter((file) => SEED_PATH.test(file));
+    if (seeds.length === 0)
+        return [];
+    const environments = declaredEnvironments(repoRoot);
+    const findings = seeds.flatMap((file) => shapeFinding(file, environments) ?? []);
+    const placed = seeds.filter((file) => !findings.some((finding) => finding.path === file) && !file.endsWith(`/${SEEDS_KEEP}`));
+    const shared = readSeedLevel(repoRoot, null);
+    const levels = [shared, ...[...(environments ?? new Map()).keys()].map((env) => readSeedLevel(repoRoot, env, new Set(shared.entries.map((entry) => entry.id))))];
+    const tracked = new Set(files);
+    for (const level of levels) {
+        findings.push(...manifestFindings(repoRoot, level, placed));
+        const scope = {
+            environments: level.env === null ? [...(environments?.keys() ?? [])] : [level.env],
+            files: tracked,
+            production: level.env === null || environments?.get(level.env) !== 'docker-compose',
+        };
+        for (const entry of level.entries)
+            findings.push(...entryFindings(repoRoot, level, entry, scope));
+    }
+    return findings;
+}