@starci/hfs 5.4.0 → 5.5.0

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;
+}

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

@@ -1,7 +1,7 @@
 // stacks.mjs - HFS_STACKS_SHAPE (R10): standard stack shape, Sonar owner and deployment runtime consistency.
 //   - every tracked path under the app root's `.starcistacks/` is one the app.starcistacks slot allows (its `allows` list is the shape:
 //     application-stacks.yaml and <env>/{README.md, environment.json, infra/{compose,swarm,k8s,terraform}, runtime/{config,env},
-//     secrets/<slug>.enc.yaml, seeds}); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
+//     secrets/<slug>.enc.yaml}, and the seed levels seeds/ and <env>/seeds/); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
 //     `deployment.json` and `k8s/` are not in the list, so they fall out of it;
 //   - the declaration (read by scripts/lib/stack-declaration.mjs, the one reader of it) states a sonar service, a local
 //     Sonar is owned by the host (`stack.owner: host`, root `.claude/ext/sonar`).
@@ -15,6 +15,8 @@ const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
 const STACKS_SLOT = 'app.starcistacks';
 const HOST_SONAR_ROOT = '.claude/ext/sonar';
 const INSIDE_SECRETS = /^[^/]+\/secrets\/[^/]+\.enc(?:\.yaml)?$/;
+/** The folders of .starcistacks/ that are no environment, each with what it holds. */
+const RESERVED = [['cache', 'the committed check cache'], ['seeds', 'the shared seed level']];
 /** The anchored expressions of a slot's `allows` entries: `<name>` is one path segment, braces alternate. */
 const allowedExpressions = (allows) => allows.flatMap((entry) => braceVariants(entry.replace(/<[a-z][a-z0-9-]*>/g, '*'))).map((variant) => globExpression(variant.endsWith('/') ? `${variant}**` : variant));
 const shapeFinding = (file, message, extra) => found(STACKS_SHAPE, file, message, extra);
@@ -26,7 +28,7 @@ function treeFindings(files, allowed, prefix) {
         if (/\.enc(?:\.yaml)?$/.test(rel) && !INSIDE_SECRETS.test(rel))
             findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc.yaml; move it to .starcistacks/<env>/secrets/`));
         else if (!allowed.some((expression) => expression.test(rel)))
-            findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml, images/db/Dockerfile in lite and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc.yaml, seeds}); move or delete it`));
+            findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml, images/db/Dockerfile in lite and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc.yaml}, and the seed levels seeds/ and <env>/seeds/ with their seeds.yaml, sql/, data/ and files/); move or delete it`));
     }
     return findings;
 }
@@ -36,8 +38,10 @@ function declarationFindings(files, prefix, declaration) {
         return [];
     const findings = [];
     const environments = declaration.doc?.environments;
-    if (environments !== null && typeof environments === 'object' && Object.hasOwn(environments, 'cache'))
-        findings.push(shapeFinding(declared, `${declared} declares an environment named cache; the name is reserved for the committed check cache (.starcistacks/cache/)`));
+    for (const [name, holds] of RESERVED) {
+        if (environments !== null && typeof environments === 'object' && Object.hasOwn(environments, name))
+            findings.push(shapeFinding(declared, `${declared} declares an environment named ${name}; the name is reserved for ${holds} (.starcistacks/${name}/)`));
+    }
     if (declaration.error)
         return [shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
     const services = declaration.doc?.services;

package/runtime/scripts/hfs/slots.d.mts

@@ -34,6 +34,8 @@ export interface RepoView {
     profile: string;
     apps: readonly AppRef[];
     optionalSlots: readonly string[];
+    /** How the app keeps its agent modules (app view only): `packages` (module packages and the rendered registry) unless hfs.json declares `modules: "data"`. */
+    modules?: 'packages' | 'data';
     patterns?: readonly string[];
     kinds?: readonly string[];
     backing?: readonly string[];

package/runtime/scripts/hfs/slots.mjs

@@ -177,6 +177,7 @@ export function resolveRepoDeclaration(manifest, declaration, { file = HFS_DECLA
         // tsconfig.json that type-checks it, both switched on by `browser: true`.
         apps: Object.freeze([]),
         optionalSlots: Object.freeze(declaration.browser === true ? ['app.browser', 'app.browser-config'] : []),
+        modules: declaration.modules === 'data' ? 'data' : 'packages',
         connections: Object.freeze([]),
         providers,
         reads: Object.freeze([]),

package/runtime/scripts/hfs/stack-seeds-config.d.mts

@@ -0,0 +1,88 @@
+import type { StackProblem } from './stack-config-kit.mjs';
+export declare const SEEDS_SCHEMA = "starci/seeds@1";
+/** The folder name of a seed level, at `.starcistacks/` and under each environment. */
+export declare const SEEDS_DIR = "seeds";
+/** The manifest of a level. */
+export declare const SEEDS_MANIFEST = "seeds.yaml";
+/** The kinds of entry; each lives in the folder `kindFolder` names. */
+export declare const SEED_KINDS: readonly ["sql", "data", "test-account", "files"];
+/** The folders of a level. */
+export declare const SEED_FOLDERS: readonly ["sql", "data", "files"];
+/** `once`: applied a single time; `upsert`: applied again whenever its content hash changes. */
+export declare const SEED_MODES: readonly ["once", "upsert"];
+/** The placeholder that keeps an empty seed folder tracked. */
+export declare const SEEDS_KEEP = ".gitkeep";
+/** The kind of one entry. */
+export type SeedKind = (typeof SEED_KINDS)[number];
+/** One entry of a level's manifest, normalised; `target` is the database (`sql`), the app command argv (`data`, `test-account`) or the bucket (`files`). */
+export interface SeedEntry {
+    id: string;
+    kind: SeedKind;
+    path: string;
+    target: string | string[];
+    mode: (typeof SEED_MODES)[number];
+    after: string[];
+    schema: string | null;
+    reason: string | null;
+}
+/** One document of a data or test-account entry, level-relative, parsed or with the reason it does not parse. */
+export type SeedDocument = {
+    path: string;
+    doc: unknown;
+    error?: undefined;
+} | {
+    path: string;
+    error: string;
+    doc?: undefined;
+};
+/** A level as the check and the seed step see it: its app-relative folder, its entries in apply order and its problems. */
+export interface SeedLevel {
+    dir: string;
+    env: string | null;
+    entries: SeedEntry[];
+    problems: StackProblem[];
+}
+/** The name of a sealed member a seed document may reference. */
+export declare const SEED_SECRET_MEMBER: RegExp;
+/** The folder of a level a kind's paths live in: a test account is data. */
+export declare const kindFolder: (kind: SeedKind) => (typeof SEED_FOLDERS)[number];
+/** True for an entry the app command loads as documents: `data` and `test-account`. */
+export declare const isDocumentEntry: (entry: Pick<SeedEntry, "kind">) => boolean;
+/** The sealed member file of `member` in the environment `env`, app-relative. */
+export declare const seedMemberFile: (env: string, member: string) => string;
+/** The app-relative folder of a level: the shared one when `env` is null. */
+export declare const seedLevelDir: (env: string | null) => string;
+/** Every file under `folder` (absolute) as a path relative to `base`, posix and sorted, the placeholders aside; a missing folder holds none. */
+export declare function filesBelow(base: string, folder: string): string[];
+/** The level-relative files an entry covers: its path when it is a file, every file below it when it is a folder. */
+export declare function entryFiles(levelRoot: string, entry: Pick<SeedEntry, 'path'>): string[];
+/** The content hash of an entry: its kind, target, mode and every file it covers, by path and bytes. */
+export declare function entryDigest(levelRoot: string, entry: SeedEntry): string;
+/**
+ * Normalises the parsed manifest of the level at `levelRoot`; `shared` holds the ids of the shared level an environment's entries may follow,
+ * and is null for the shared level itself, which declares no test account (an environment's level declares at most one).
+ */
+export declare function normalizeSeeds(doc: unknown, levelRoot: string, shared?: ReadonlySet<string> | null): {
+    entries: SeedEntry[];
+    problems: StackProblem[];
+};
+/** Reads and judges the level of `env` (null: the shared level) at `repoRoot`; a level without a manifest has no entries. */
+export declare function readSeedLevel(repoRoot: string, env: string | null, shared?: ReadonlySet<string>): SeedLevel;
+/** The documents of a data or test-account entry: every JSON or YAML file it covers, parsed. */
+export declare function seedDocuments(levelRoot: string, entry: Pick<SeedEntry, 'path'>): SeedDocument[];
+/** The member a value references when it is a secret reference (`{ "secret": "<member>" }` and nothing else), else null. */
+export declare function secretReference(value: unknown): string | null;
+/** Every member the secret references of a document name, in document order, once each. */
+export declare function secretReferences(doc: unknown): string[];
+/** A copy of `doc` with every secret reference replaced by what `resolve` answers for its member. */
+export declare function resolveSecrets(doc: unknown, resolve: (member: string) => unknown): unknown;
+/** An entry to declare in a manifest: `after` and `schema` as the manifest spells them, left out when empty. */
+export type SeedEntryInput = Pick<SeedEntry, 'id' | 'kind' | 'path' | 'target' | 'mode'> & {
+    after?: string[];
+    schema?: string;
+};
+/**
+ * Declares `entries` in the manifest of the level of `env` (null: the shared level), creating the manifest when the level has none; an id the
+ * manifest already holds is kept as it is. Answers the ids it added (none are written when `write` is false).
+ */
+export declare function addSeedEntries(repoRoot: string, env: string | null, entries: SeedEntryInput[], write?: boolean): string[];