@starci/hfs 4.13.2 → 4.16.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 4.16.0 - 2026-10-31
+
+- Added: `starci app codemod spacing-roles [--execute] [--json] [--format json|markdown] [--out <file>]`: a dry run by default; plain flex column and row `div`s whose only spacing is one gap become `Stack` and `Cluster` bound from the file's Grammar import (gap-1 identity, gap-2 inline, gap-3 row, gap-4 section, gap-6 and gap-8 region, gap-8 marked for review); every other spacing utility is reported with its suggested role, and the report counts the utilities by family.
+- Changed: `starci app lint` reports an ESLint warning (a rule of the canon's counting cohort) with severity `warning`, counts them per rule (`counts.warning`, `counting`) and keeps them out of the verdict and the error threshold.
+- Changed: the canon pins name @starci/grammar, eslint-grammar-core and eslint-grammar-offset-pop 0.18.0, eslint-canon-fe 9.8.0, stylelint-canon 2.4.0 and hfs 4.16.0; R350 joins the bundled rule catalog.
+
+## 4.15.0 - 2026-10-31
+
+- Added: R345 `FE_PANE_GRID_CHILD_NOT_PANE`, R346 `FE_PANE_CHILD_NOT_SECTION`, R347 `FE_PANE_SECTION_PADDING` and R348 `FE_PANE_GRID_FRAME` (eslint-grammar-core `pane-grid-children`, `pane-children`, `no-pane-section-padding`, `pane-grid-page`) and R349 `FE_HAND_BUILT_PANES` (eslint-canon-fe `no-hand-built-panes`) in the bundled rule catalog.
+- Changed: the bundled canon pins name the cohort hfs 4.15.0, eslint-canon-be 3.11.0, eslint-canon-fe 9.7.0, @starci/grammar, eslint-grammar-core and eslint-grammar-offset-pop 0.17.0.
+
+## 4.14.0 - 2026-10-31
+
+- Added: `ruleParams.be.sqlPassThrough` and hfs.json `sides.be.sqlPassThrough` (a list of `{file, reason}`, side-relative forward-slash paths, unique): the files whose `.query(` passes through SQL text that is not the app's own (R334). The shape validators (`manifest-shape`, `rule-params-shape`, `declaration-shape`) accept it on the be side only, the resolver merges the app's list into the canon's like `dbFunctions`, and the canon lists the seed runner `src/modules/platform/database/seed-runner.service.ts`.
+- Changed: R334 `BE_PERSISTENCE_NO_RAW_SQL` is one style: lite TypeScript holds no SQL text outside the test world (entities, or a listed function through `callDbFunction`; the world keeps raw SQL for probes only), the failure code text follows, R68 names the call and LISTEN statements, and the `be.tests.world` slot allows `<name>.sql.ts`.
+- Changed: the lite skeleton's `platform/database/database.client.ts` writes no literal `.query(` but the call template: `advisoryXactLock` is `callDbFunction` of `hashtextextended(key, 0)` then `pg_advisory_xact_lock(hash)`, and `notify` is `callDbFunction` of `pg_notify`; its spec follows.
+- Changed: the bundled canon pins name the cohort hfs 4.14.0, eslint-canon-be 3.11.0, eslint-canon-fe 9.6.7, @starci/grammar, eslint-grammar-core and eslint-grammar-offset-pop 0.16.6.
+
+## 4.13.3 - 2026-10-31
+
+- Changed: the canon pins name @starci/ai-router 0.5.0 (many providers behind one virtual key, the persisted key blacklist) and the cohort that carries them: hfs 4.13.3, eslint-canon-be 3.10.1, eslint-canon-fe 9.6.6, eslint-grammar-core and eslint-grammar-offset-pop 0.16.6; no rule changed.
+
 ## 4.13.2 - 2026-10-31
 
 - Added: R344 `BE_AI_VIRTUAL_KEY` in the bundled rule catalog and on the `be.integrations` slot: an app's ai-router gateway has one client key, `STARCI_AI_KEY`, read by `integrations/ai`, and no admin token; `@starci/eslint-canon-be` `ai-virtual-key-name` enforces it (ruling be-ai-one-virtual-key).

package/codemod/main.d.mts

@@ -0,0 +1,16 @@
+/** The codemods `starci app codemod` runs, by name. */
+export declare const CODEMODS: readonly string[];
+/** The arguments of `starci app codemod spacing-roles`: --execute, --json, --format and --out; any other is refused. */
+export declare function spacingRolesArguments(argv: readonly string[]): {
+    write: boolean;
+    format: 'json' | 'markdown';
+    out?: string;
+};
+/**
+ * CLI boundary of `starci app codemod <name>`. Dry run by default; --execute writes only the safe rewrites. A codemod
+ * that leaves a case for a person exits 1 with the complete report.
+ */
+export declare function codemodMain(argv: string[], io: {
+    cwd: string;
+    stdout: (text: string) => unknown;
+}): number;

package/codemod/main.mjs

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { codemodMain as buttonIntentMain } from './button-intent.mjs';
+import { migrateSpacingRoles, spacingRolesMarkdown } from './spacing-roles.mjs';
+/** The codemods `starci app codemod` runs, by name. */
+export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles']);
+/** The arguments of `starci app codemod spacing-roles`: --execute, --json, --format and --out; any other is refused. */
+export function spacingRolesArguments(argv) {
+    const options = { write: false, format: 'markdown' };
+    const args = argv.values();
+    for (const arg of args) {
+        const [flag, inline] = arg.split(/=(.*)/s);
+        if (flag === '--execute' || flag === '--json') {
+            if (inline !== undefined && !['true', 'false'].includes(inline))
+                throw new Error(`${flag} expects true or false`);
+            const value = inline === undefined || inline === 'true';
+            if (flag === '--execute')
+                options.write = value;
+            else if (value)
+                options.format = 'json';
+        }
+        else if (flag === '--format' || flag === '--out') {
+            const value = inline ?? args.next().value;
+            if (!value || value.startsWith('--'))
+                throw new Error(`${flag} needs a value`);
+            if (flag === '--out')
+                options.out = value;
+            else if (value === 'json' || value === 'markdown')
+                options.format = value;
+            else
+                throw new Error('--format accepts json or markdown');
+        }
+        else
+            throw new Error(`unknown codemod option ${arg}`);
+    }
+    return options;
+}
+/**
+ * CLI boundary of `starci app codemod <name>`. Dry run by default; --execute writes only the safe rewrites. A codemod
+ * that leaves a case for a person exits 1 with the complete report.
+ */
+export function codemodMain(argv, io) {
+    const [name, ...rest] = argv;
+    if (name === 'button-intent')
+        return buttonIntentMain(argv, io);
+    if (name !== 'spacing-roles')
+        throw new Error(`starci app codemod takes ${CODEMODS.join(' or ')}`);
+    const options = spacingRolesArguments(rest);
+    if (options.out && !/\.(?:json|md)$/i.test(options.out))
+        throw new Error('--out needs a .json or .md report file');
+    const report = migrateSpacingRoles({ root: path.resolve(io.cwd), write: options.write });
+    const output = options.format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : spacingRolesMarkdown(report);
+    if (options.out) {
+        const target = path.resolve(io.cwd, options.out);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, output);
+    }
+    io.stdout(output);
+    return report.findings.length ? 1 : 0;
+}

package/codemod/spacing-roles.d.mts

@@ -0,0 +1,60 @@
+/** The TypeScript compiler API of the app's own install (loadTypescript), typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** One rewrite of the report: a layout element whose classes were only a flex column or row and its gap. */
+export interface SpacingChange {
+    file: string;
+    line: number;
+    column: number;
+    from: string;
+    to: string;
+    review?: string;
+}
+/** One spacing utility the codemod leaves for a person, with the role it suggests when it has one. */
+export interface SpacingFinding {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    utility: string;
+    suggestion: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod spacing-roles`). */
+export interface SpacingReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    /** Every spacing utility of the scanned source by family (gap, padding, margin, space), before the rewrite. */
+    counts: Record<string, number>;
+    changes: SpacingChange[];
+    findings: SpacingFinding[];
+}
+/** The role each Tailwind gap step names (the doctrine's mapping); `review` marks a step whose role a person confirms. */
+export declare const GAP_ROLES: Readonly<Record<string, {
+    role: string;
+    review?: string;
+}>>;
+/** The spacing utilities of one class string. */
+export declare const spacingUtilities: (text: string) => string[];
+/** Rewrite one source text: plain `div` flex columns and rows whose only spacing is one gap become Stack and Cluster. */
+export declare function transformSpacingRoles({ ts, text, file }: {
+    ts: Ts;
+    text: string;
+    file?: string;
+}): {
+    text: string;
+    changes: SpacingChange[];
+    findings: SpacingFinding[];
+    counts: Record<string, number>;
+};
+/** Preview or apply the safe rewrites in one app's FE tree; every utility left is in the report with its suggested role. */
+export declare function migrateSpacingRoles({ root, write, ts }: {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+}): SpacingReport;
+/** Render the migration and the utilities left for a person as Markdown; JSON consumers read the same report object. */
+export declare function spacingRolesMarkdown(report: SpacingReport): string;
+export {};

package/codemod/spacing-roles.mjs

@@ -0,0 +1,198 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { sourceLocation } from '../runtime/scripts/lib/ts-ast.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GRAMMAR = /^@starci\/grammar(?:\/(?:core|common|offset-pop))?$/;
+const GENERATED = new Set(['node_modules', '.next', '.turbo', 'dist', 'coverage', '.git']);
+const SPACING_UTILITY = /^-?(p|px|py|pt|pb|ps|pe|pl|pr|m|mx|my|mt|mb|ms|me|ml|mr|gap|gap-x|gap-y|space-x|space-y)-(.+)$/;
+/** The role each Tailwind gap step names (the doctrine's mapping); `review` marks a step whose role a person confirms. */
+export const GAP_ROLES = Object.freeze({
+    '1': { role: 'identity' },
+    '2': { role: 'inline' },
+    '3': { role: 'row' },
+    '4': { role: 'section' },
+    '6': { role: 'region' },
+    '8': { role: 'region', review: 'gap-8 and gap-6 both become region; confirm the two blocks are page regions with their own heading' },
+});
+/** Classes a Stack or Cluster already draws, so an element holding only these and one gap becomes the primitive. */
+const STACK_CLASSES = new Set(['flex', 'flex-col', 'min-w-0']);
+const CLUSTER_CLASSES = new Set(['flex', 'flex-row', 'flex-wrap', 'items-center', 'min-w-0']);
+const family = (utility) => {
+    const name = SPACING_UTILITY.exec(utility.replace(/^!|!$/g, ''))?.[1] ?? '';
+    return name.startsWith('gap') ? 'gap' : name.startsWith('space') ? 'space' : name.startsWith('p') ? 'padding' : 'margin';
+};
+/** The utility once its variants are dropped (`sm:gap-2` is `gap-2`); a variant marks a responsive or state choice. */
+const baseOf = (cls) => cls.slice(cls.lastIndexOf(':') + 1);
+/** The spacing utilities of one class string. */
+export const spacingUtilities = (text) => text.split(/\s+/).filter((cls) => SPACING_UTILITY.test(baseOf(cls).replace(/^!|!$/g, '')));
+/** What a person writes instead of one utility the codemod does not rewrite. */
+const suggestionFor = (utility) => {
+    const base = baseOf(utility);
+    const kind = family(base);
+    if (kind === 'gap' || kind === 'space') {
+        const step = /-(\d+)$/.exec(base)?.[1] ?? '';
+        const mapped = GAP_ROLES[step];
+        return mapped ? `gap="${mapped.role}" on a Stack or Cluster` : 'the role of the relation on a Stack, Cluster or Grid';
+    }
+    return kind === 'margin' ? "the parent's gap role" : 'the inset of the Grammar box that holds the content';
+};
+/** The Grammar import that binds Stack and Cluster in a file: the family specifier it already imports. */
+function grammarImport(ts, source) {
+    for (const node of source.statements) {
+        if (!ts.isImportDeclaration(node) || !ts.isStringLiteral(node.moduleSpecifier) || !GRAMMAR.test(node.moduleSpecifier.text))
+            continue;
+        const bindings = node.importClause?.namedBindings;
+        if (bindings === undefined || !ts.isNamedImports(bindings) || node.importClause?.isTypeOnly)
+            continue;
+        return { specifier: node.moduleSpecifier.text, node, names: new Set(bindings.elements.map((element) => element.name.text)) };
+    }
+    return null;
+}
+/** The static class string of an element, or null when it is computed. */
+function classText(ts, attribute) {
+    const value = attribute?.initializer;
+    if (value === undefined)
+        return null;
+    if (ts.isStringLiteral(value))
+        return value.text;
+    if (ts.isJsxExpression(value) && value.expression !== undefined && ts.isStringLiteralLike(value.expression))
+        return value.expression.text;
+    return null;
+}
+/** The primitive and its props an element's classes ask for, or why it stays for a person. */
+function primitiveFor(classes) {
+    const gaps = classes.filter((cls) => /^gap-\d+$/.test(cls));
+    if (gaps.length !== 1)
+        return { reason: 'the element holds no single plain gap utility' };
+    const step = (gaps[0] ?? '').slice(4);
+    const mapped = GAP_ROLES[step];
+    if (mapped === undefined)
+        return { reason: `gap-${step} names no role; choose the relation` };
+    const rest = classes.filter((cls) => cls !== gaps[0]);
+    const review = mapped.review === undefined ? {} : { review: mapped.review };
+    if (rest.includes('flex-col') && rest.every((cls) => STACK_CLASSES.has(cls)))
+        return { tag: 'Stack', props: `gap="${mapped.role}"`, ...review };
+    if (rest.includes('flex') && !rest.includes('flex-col') && rest.every((cls) => CLUSTER_CLASSES.has(cls))) {
+        if (mapped.role === 'region')
+            return { reason: 'a cluster never holds regions; a region gap belongs to a Stack or a Grid' };
+        return { tag: 'Cluster', props: `gap="${mapped.role}"${rest.includes('flex-wrap') ? '' : ' wrap={false}'}`, ...review };
+    }
+    return { reason: 'the element carries layout classes a Stack or Cluster does not draw; move them to a Grammar API first' };
+}
+/** Rewrite one source text: plain `div` flex columns and rows whose only spacing is one gap become Stack and Cluster. */
+export function transformSpacingRoles({ ts, text, file = 'component.tsx' }) {
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, /\.jsx$/i.test(file) ? ts.ScriptKind.JSX : ts.ScriptKind.TSX);
+    const changes = [];
+    const findings = [];
+    const counts = {};
+    const edits = [];
+    const needed = new Set();
+    const imported = grammarImport(ts, source);
+    const leave = (node, utility, code, reason) => {
+        findings.push({ file, ...sourceLocation(source, node), code, utility, suggestion: suggestionFor(utility), reason });
+    };
+    const visitString = (node) => {
+        for (const utility of spacingUtilities(node.text)) {
+            counts[family(baseOf(utility))] = (counts[family(baseOf(utility))] ?? 0) + 1;
+            leave(node, utility, 'class-string', 'a class string outside a plain layout element; name the relation where it is used');
+        }
+    };
+    const visitElement = (opening, element) => {
+        const attributes = opening.attributes.properties;
+        const classAttribute = attributes.find((entry) => ts.isJsxAttribute(entry) && entry.name.getText(source) === 'className');
+        const text = classText(ts, classAttribute);
+        if (text === null)
+            return;
+        const utilities = spacingUtilities(text);
+        for (const utility of utilities)
+            counts[family(baseOf(utility))] = (counts[family(baseOf(utility))] ?? 0) + 1;
+        if (utilities.length === 0)
+            return;
+        const classes = text.split(/\s+/).filter(Boolean);
+        const others = attributes.filter((entry) => entry !== classAttribute && !(ts.isJsxAttribute(entry) && entry.name.getText(source) === 'key'));
+        const isDiv = opening.tagName.getText(source) === 'div';
+        const target = primitiveFor(classes);
+        const reason = !isDiv ? 'only a plain div becomes a layout primitive' : others.length > 0 ? 'the element carries props a layout primitive does not take' : imported === null ? 'the file imports no Grammar family to bind the primitive from' : 'reason' in target ? target.reason : null;
+        if (reason !== null || 'reason' in target) {
+            for (const utility of utilities)
+                leave(opening, utility, 'layout-element', reason ?? 'the element stays for a person');
+            return;
+        }
+        needed.add(target.tag);
+        const key = attributes.find((entry) => ts.isJsxAttribute(entry) && entry.name.getText(source) === 'key');
+        const props = `${target.tag} ${target.props}${key === undefined ? '' : ` ${key.getText(source)}`}`;
+        edits.push({ start: opening.getStart(source), end: opening.end, replacement: ts.isJsxSelfClosingElement(opening) ? `<${props} />` : `<${props}>` });
+        if (ts.isJsxElement(element))
+            edits.push({ start: element.closingElement.getStart(source), end: element.closingElement.end, replacement: `</${target.tag}>` });
+        changes.push({ file, ...sourceLocation(source, opening), from: text, to: `<${target.tag} ${target.props}>`, ...(target.review === undefined ? {} : { review: target.review }) });
+    };
+    const visit = (node) => {
+        if (ts.isJsxElement(node))
+            visitElement(node.openingElement, node);
+        else if (ts.isJsxSelfClosingElement(node))
+            visitElement(node, node);
+        else if ((ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && !ts.isJsxAttribute(node.parent) && !ts.isImportDeclaration(node.parent) && !(ts.isJsxExpression(node.parent) && ts.isJsxAttribute(node.parent.parent)))
+            visitString(node);
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    if (imported !== null) {
+        const missing = [...needed].filter((name) => !imported.names.has(name)).sort();
+        const bindings = imported.node.importClause?.namedBindings;
+        if (missing.length > 0 && bindings !== undefined && ts.isNamedImports(bindings)) {
+            const names = [...bindings.elements.map((element) => element.getText(source)), ...missing];
+            edits.push({ start: bindings.getStart(source), end: bindings.end, replacement: `{ ${names.join(', ')} }` });
+        }
+    }
+    let output = text;
+    for (const edit of edits.sort((first, second) => second.start - first.start))
+        output = output.slice(0, edit.start) + edit.replacement + output.slice(edit.end);
+    return { text: output, changes, findings, counts };
+}
+function sourceFiles(directory) {
+    return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const target = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            return GENERATED.has(entry.name) ? [] : sourceFiles(target);
+        return entry.isFile() && /\.[jt]sx?$/i.test(entry.name) && !/\.(?:spec|test|d)\.[jt]sx?$/i.test(entry.name) ? [target] : [];
+    }).sort();
+}
+/** Preview or apply the safe rewrites in one app's FE tree; every utility left is in the report with its suggested role. */
+export function migrateSpacingRoles({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+    if (!ts)
+        throw new Error('spacing-roles needs TypeScript installed in the app or @starci/hfs development checkout');
+    const frontend = path.join(root, 'fe');
+    if (!fs.statSync(frontend, { throwIfNoEntry: false })?.isDirectory())
+        throw new Error('spacing-roles runs at an app root with a fe/ directory');
+    const report = { schema: 'starci/spacing-roles-codemod@1', root, write, filesScanned: 0, filesChanged: [], counts: {}, changes: [], findings: [] };
+    for (const target of sourceFiles(frontend)) {
+        const file = path.relative(root, target).split(path.sep).join('/');
+        const original = fs.readFileSync(target, 'utf8');
+        const result = transformSpacingRoles({ ts, text: original, file });
+        report.filesScanned += 1;
+        report.changes.push(...result.changes);
+        report.findings.push(...result.findings);
+        for (const [name, count] of Object.entries(result.counts))
+            report.counts[name] = (report.counts[name] ?? 0) + count;
+        if (result.text !== original) {
+            report.filesChanged.push(file);
+            if (write)
+                fs.writeFileSync(target, result.text);
+        }
+    }
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the migration and the utilities left for a person as Markdown; JSON consumers read the same report object. */
+export function spacingRolesMarkdown(report) {
+    const counts = Object.entries(report.counts).sort().map(([name, count]) => `${name} ${count}`).join(', ') || 'none';
+    return ['# Spacing roles migration', '',
+        `${report.write ? 'Applied' : 'Dry run'}: ${report.changes.length} rewrites in ${report.filesChanged.length} files of ${report.filesScanned}; ${report.findings.length} utilities left for a person.`, '',
+        `Spacing utilities before: ${counts}.`, '',
+        '## Rewrites', '', '| Location | Classes | Becomes | Review |', '| --- | --- | --- | --- |',
+        ...report.changes.map((change) => `| ${cell(`${change.file}:${change.line}:${change.column}`)} | ${cell(change.from)} | ${cell(change.to)} | ${cell(change.review ?? '')} |`), '',
+        '## Left for a person', '', '| Location | Utility | Suggestion | Reason |', '| --- | --- | --- | --- |',
+        ...report.findings.map((finding) => `| ${cell(`${finding.file}:${finding.line}:${finding.column}`)} | ${cell(finding.utility)} | ${cell(finding.suggestion)} | ${cell(finding.reason)} |`), ''].join('\n');
+}

package/lint/run.mjs

@@ -168,7 +168,7 @@ export async function runLinter({ cwd, pkg, bin, args, bound = null }) {
     return { results, ...(completed ? {} : { error: `${pkg} could not complete in ${path.basename(cwd)}/ (exit ${run.status}, signal ${run.signal ?? 'none'}): ${String(run.error?.message || run.stderr || run.stdout || '').trim().split('\n')[0]}` }) };
 }
 const eslintFindings = (results, appRoot) => results.flatMap((result) => (result.messages ?? []).map((message) => ({
-    engine: 'eslint', rule: message.ruleId ?? 'eslint-error', code: CODE_PREFIX.exec(message.message ?? '')?.[1] ?? null, severity: 'error',
+    engine: 'eslint', rule: message.ruleId ?? 'eslint-error', code: CODE_PREFIX.exec(message.message ?? '')?.[1] ?? null, severity: message.severity === 1 ? 'warning' : 'error',
     path: posix(path.relative(appRoot, result.filePath)), line: message.line ?? null, column: message.column ?? null, message: message.message,
 })));
 const stylelintFindings = (results, appRoot) => results.flatMap((result) => (result.warnings ?? []).map((warning) => ({
@@ -676,18 +676,27 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
         linterReport('eslint', raw.eslint, { root: repoRoot, sourceRoots, tracked }),
         linterReport('stylelint', raw.stylelint, { root: repoRoot, sourceRoots, tracked }),
     ]);
-    // Green under the threshold (gate-threshold.mjs): every finding is still reported, only the verdict changes.
-    const gate = gateVerdict(findings);
-    const report = { schema: LINT_SCHEMA, ok: gate.pass && errors.length === 0, repoRoot, changed: changed ? [...changed].sort(byCodeUnit) : null, workspace, ...(opts.side === undefined ? {} : { side: opts.side }), counts: { error: findings.length }, engines, errors, findings, gate };
+    // Green under the threshold (gate-threshold.mjs): every finding is still reported, only the verdict changes. A warning is a
+    // rule of the canon's counting cohort (eslint-canon-fe COUNTING): reported and counted per rule, never part of the verdict.
+    const failing = findings.filter((finding) => finding.severity !== 'warning');
+    const counting = {};
+    for (const finding of findings)
+        if (finding.severity === 'warning')
+            counting[finding.rule] = (counting[finding.rule] ?? 0) + 1;
+    const gate = gateVerdict(failing);
+    const report = { schema: LINT_SCHEMA, ok: gate.pass && errors.length === 0, repoRoot, changed: changed ? [...changed].sort(byCodeUnit) : null, workspace, ...(opts.side === undefined ? {} : { side: opts.side }), counts: { error: failing.length, warning: findings.length - failing.length }, counting, engines, errors, findings, gate };
     return { report, sonar, exit: errors.length ? 2 : gate.pass ? 0 : 1 };
 }
 export function printLintText(report, out) {
     for (const f of report.findings)
-        out(`${f.path ?? '-'}${f.line ? `:${f.line}${f.column ? `:${f.column}` : ''}` : ''}  ${f.engine}/${f.rule}  ${f.message}\n`);
+        out(`${f.path ?? '-'}${f.line ? `:${f.line}${f.column ? `:${f.column}` : ''}` : ''}  ${f.severity === 'warning' ? 'warn ' : ''}${f.engine}/${f.rule}  ${f.message}\n`);
     for (const e of report.errors)
         out(`ERROR ${e}\n`);
-    const per = Object.keys(report.engines).map((engine) => `${engine} ${report.findings.filter((f) => f.engine === engine).length}`).join(', ');
+    const per = Object.keys(report.engines).map((engine) => `${engine} ${report.findings.filter((f) => f.engine === engine && f.severity !== 'warning').length}`).join(', ');
     out(`\nstarci app lint: ${report.counts.error} finding${report.counts.error === 1 ? '' : 's'} (${per})${report.errors.length ? `, ${report.errors.length} tool error${report.errors.length === 1 ? '' : 's'}` : ''}\n`);
+    const counting = Object.entries((report.counting ?? {})).sort(([a], [b]) => a.localeCompare(b));
+    if (counting.length)
+        out(`counting (warn, not in the verdict): ${counting.map(([rule, count]) => `${rule} ${count}`).join(', ')}\n`);
     if (report.gate?.line)
         out(`${report.gate.line}\n`);
 }

package/package.json

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

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

@@ -31,42 +31,42 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.16.5
+    version: 0.18.0
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.10.0
+    version: 3.11.1
     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.6.5
+    version: 9.8.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.16.5
+    version: 0.18.0
     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.16.5
+    version: 0.18.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-offset-pop/package.json
     why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
   '@starci/stylelint-canon':
-    version: 2.3.0
+    version: 2.4.0
     group: starci
     install: registry
     side: fe
@@ -99,14 +99,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. A fake declared https (defineHttpFake) serves TLS with the run''s ephemeral in-memory fake CA and publishes its PEM as w.fake.<name>.ca for the app''s own client to trust; verification is never turned off. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/ai-router':
-    version: 0.4.1
+    version: 0.5.0
     group: starci
     install: registry
     side: be
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.13.2
+    version: 4.16.0
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -1407,7 +1407,7 @@ rules:
     witness:
       - {"path":"packages/eslint/be/legacy-sql-http-log-proof.spec.mjs","edition":"lite","codes":["BE_SQL_INTERPOLATED"]}
       - {"path":"packages/eslint/be/legacy-sql-http-log-proof.spec.mjs","edition":"full","codes":["BE_SQL_INTERPOLATED"]}
-    law: "SQL text carries no runtime substitution; values are numbered parameters. The one exception is R334's lite call statement in platform/database/database.client.ts, which splices only the name parts and parameter list its own validator checked."
+    law: "SQL text carries no runtime substitution; values are numbered parameters. The one exception is R334's call and LISTEN statements in platform/database/database.client.ts, which splice only the name parts and parameter list its own validator checked."
     kinds: [lint, codemod]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["BE_SQL_INTERPOLATED"]
@@ -5828,7 +5828,7 @@ rules:
         ruling: "Lite entities only map tables the migrations create, so each entity column is checked against the migrated schema by starci app db drift, which CI runs in the build job and the release gate runs as its db-drift row."
   - id: R334
     code: "BE_PERSISTENCE_NO_RAW_SQL"
-    law: "Lite domain, feature and test code reads and writes through TypeORM entities on an EntityManager (domain code the injected one, integration and e2e specs, builders and fixtures the world's `world.db.<connection>`) (find, findOne, findBy, count, exists, insert, save, update, delete, upsert, increment, and createQueryBuilder(Entity, alias) with named parameters for joins, aggregates, FOR UPDATE / SKIP LOCKED and jsonb or vector operators; never a table-name builder, a builder with no entity or a Repository); no .query( call and no sql template outside the two raw SQL owners, platform/database and the test world src/tests/world, which wraps only what entities cannot express (a trigger, a database function, a row-level-security probe, a pgmq queue) in a named, typed world helper specs call; a database function TypeORM cannot express is called, in domain and test code alike, through the callDbFunction, advisoryXactLock and notify helpers of platform/database/database.client.ts, and callDbFunction names only a function ruleParams.be.dbFunctions or hfs.json sides.be.dbFunctions lists with a reason: a function of a migration schema-qualified (public.job_claim), a pg built-in bare (pg_notify, called in pg_catalog). That file alone composes the call statement, from the name parts its validator checked and double-quotes and a numbered parameter list. Entities only map tables db/migrations created (synchronize stays false); entity-versus-schema drift is BE_ENTITY_SCHEMA_DRIFT of starci app db drift."
+    law: "Lite TypeScript holds no SQL text, outside the test world. A table is read and written through its TypeORM entity on an EntityManager (domain code the injected one; specs, builders, fixtures and the test world the world's `world.db.<connection>`): find, save, update, delete, upsert, a pessimistic `lock` option, `createQueryBuilder(Entity, \"alias\")` with named parameters; never a table-name builder or a Repository. Every table a migration creates has an entity. Anything else is a database function, called through `callDbFunction` of `platform/database/database.client.ts`, which names only a function that `ruleParams.be.dbFunctions` or hfs.json `sides.be.dbFunctions` lists with a reason: a function of a migration, schema-qualified (`public.job_claim`); an extension function, schema-qualified; a pg built-in of the canon's list, bare (`pg_notify`, called in pg_catalog). `database.client.ts` alone composes SQL text (the call statement and LISTEN), from parts its validator checked; `advisoryXactLock` and `notify` are `callDbFunction` calls of built-ins there. The only other `.query(` outside the world is the pass-through of a file that `ruleParams.be.sqlPassThrough` or hfs.json `sides.be.sqlPassThrough` lists with a reason, whose text is not the app's own (the tracked seed, a customer data-source read, an outside session's setup), with a plain string first argument, never a template or a `+`. The test world `src/tests/world` may hold raw SQL, as `sql`-tagged text with numbered `$n` parameters (and `<name>.sql.ts` files), only for what neither an entity nor a listed function expresses: a privilege or row-level-security probe, catalog, cron or trigger introspection, a pgmq queue table, a lock or failure probe; in the world too plain CRUD on an application table goes through its entity, an application function through `callDbFunction`, and seeded rows come from builders (R98). No `sql` template, `*.sql.ts`, `sql`/`ident` import or other `.query(` exists anywhere else."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["BE_PERSISTENCE_NO_RAW_SQL"]
@@ -6069,3 +6069,142 @@ rules:
         source: owner
         quote: "Xóa ai api key và openclaw ai key chỉnh thành starci ai key là key ảo"
         ruling: "Per app and environment the ai member holds the upstream provider keys and one random virtual key STARCI_AI_KEY that the gateway mounts and every client uses; the gateway has no admin API (ruling be-ai-one-virtual-key)."
+  - id: R345
+    code: "FE_PANE_GRID_CHILD_NOT_PANE"
+    law: "A child of a Grammar PaneGrid is a literal Pane element, written directly or returned by a conditional (`cond ? <Pane/> : null`, `cond && <Pane/>`) or a `.map`; a wrapper component, a raw element, a fragment or a variable is refused, because PaneGrid places each child by the area of a Pane and drops the rest, leaving its cell blank. A Freestyle subtree leaves the raw elements inside it alone."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_PANE_GRID_CHILD_NOT_PANE"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: pane-grid-children}
+    editions: [lite, full]
+    docs: [contexts/ui/components/pane-grid.md]
+    templateNa: "A template draws no pane grid; an app adds one with its multi-pane screens."
+    proves:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_GRID_CHILD_NOT_PANE]}
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_GRID_CHILD_NOT_PANE]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_GRID_CHILD_NOT_PANE]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "trò thiết kế hệ thống padding đồng nhất cho grammar chứ mỗi nơi 1 padding trò thấy k"
+        ruling: "A Pane owns its content inset and every band in it is a PaneSection; a PaneGrid holds Panes only, so the lint refuses a wrapper component that the grid would drop."
+  - id: R346
+    code: "FE_PANE_CHILD_NOT_SECTION"
+    law: "A Grammar Pane holds PaneSection elements or one nested PaneGrid; a raw element, or a Grammar component other than PaneSection, PaneGrid and Freestyle, placed directly in a Pane skips the inset the pane publishes to its bands. A project component is judged in its own file, and a Freestyle subtree leaves its raw elements alone."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_PANE_CHILD_NOT_SECTION"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: pane-children}
+    editions: [lite, full]
+    docs: [contexts/ui/components/pane-grid.md]
+    templateNa: "A template draws no pane grid; an app adds one with its multi-pane screens."
+    proves:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_CHILD_NOT_SECTION]}
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_CHILD_NOT_SECTION]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_CHILD_NOT_SECTION]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "trò thiết kế hệ thống padding đồng nhất cho grammar chứ mỗi nơi 1 padding trò thấy k"
+        ruling: "A Pane owns its content inset and every band in it is a PaneSection whose boxes align to that edge, so the lint refuses a band hand-built in a pane."
+  - id: R347
+    code: "FE_PANE_SECTION_PADDING"
+    law: "The outermost element a Grammar PaneSection renders, and the root of a same-file component returned as its child, carries no padding or margin utility (`p-*`, `px-*`, `py-*`, `ps/pe/pt/pb/pl/pr-*`, `m-*`, `mx/my/ms/me/mt/mb/ml/mr-*`, their negative forms, or an arbitrary padding or margin property; zero and auto values place or reset and are not one), because the Pane owns the content inset and the section applies it. A Freestyle subtree leaves its raw elements alone."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_PANE_SECTION_PADDING"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: no-pane-section-padding}
+    editions: [lite, full]
+    docs: [contexts/ui/components/pane-grid.md]
+    templateNa: "A template draws no pane grid; an app adds one with its multi-pane screens."
+    proves:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_SECTION_PADDING]}
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_SECTION_PADDING]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_SECTION_PADDING]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "trò thiết kế hệ thống padding đồng nhất cho grammar chứ mỗi nơi 1 padding trò thấy k"
+        ruling: "One padding system for everything placed in a PaneGrid: the Pane publishes the inset and the PaneSection applies it, so no band adds its own."
+  - id: R348
+    code: "FE_PANE_GRID_FRAME"
+    law: "A Grammar PaneGrid is the one child of `Page chrome=\"panes\"` or stands inside a Pane; a PaneGrid drawn in a FillViewport, a SurfaceCard, SurfaceListCard or SurfaceAccordionCard, a Page of another chrome, or wrapped inside `Page chrome=\"panes\"` re-decides the frame and the bottom edge that Page owns. A grid whose frame lives in another file is judged where the frame is, and a Freestyle subtree is not judged."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_PANE_GRID_FRAME"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: pane-grid-page}
+    editions: [lite, full]
+    docs: [contexts/ui/components/pane-grid.md]
+    templateNa: "A template draws no pane grid; an app adds one with its multi-pane screens."
+    proves:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_GRID_FRAME]}
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_GRID_FRAME]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/pane.spec.ts, editions: [lite, full], codes: [FE_PANE_GRID_FRAME]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "sao trang lan agent có gap 1 khoảng trên vậy??? … phải dính vào chứ"
+        ruling: "A tabbed app page's PaneGrid attaches flush under the tab line, full width and to the bottom, with no card, radius or gap: Page chrome=\"panes\"."
+  - id: R349
+    code: "FE_HAND_BUILT_PANES"
+    law: "A multi-pane frame is a Grammar PaneGrid of Panes, which draws the dividers between panes; a vertical Divider used as a column seam (among the plain columns of a flex row, or anywhere inside a SurfaceCard composition=\"joined\") and a joined SurfaceCard that holds a flex row of two or more plain columns are a pane frame drawn by hand and are refused. A short vertical separator between controls and a row whose classes cannot be read in the file are not judged."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_HAND_BUILT_PANES"]
+    enforcers:
+      - {kind: eslint-fe, id: no-hand-built-panes}
+    editions: [lite, full]
+    docs: [contexts/ui/components/pane-grid.md]
+    templateNa: "A template draws no multi-pane frame; an app adds one with its multi-pane screens."
+    proves:
+      - {path: packages/eslint-canon-fe/src/surface-rules.spec.ts, editions: [lite, full], codes: [FE_HAND_BUILT_PANES]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-fe/src/surface-rules.spec.ts, editions: [lite, full], codes: [FE_HAND_BUILT_PANES]}
+    witness:
+      - {path: packages/eslint-canon-fe/src/surface-rules.spec.ts, editions: [lite, full], codes: [FE_HAND_BUILT_PANES]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "sao trang lan agent có gap 1 khoảng trên vậy??? … phải dính vào chứ"
+        ruling: "A multi-pane frame is the Grammar's PaneGrid, never columns and a vertical Divider composed by hand inside a card."
+  - id: R350
+    code: "FE_SPACING_UTILITY"
+    law: "Every spacing value is the Grammar's, on its one scale 0 4 8 12 24 32: an app names the relation between the blocks it places through a role prop (Stack and Cluster gap identity, inline, row, section or region; Grid kind cards, form or main-rail; PaneSection; Page) and writes no padding, margin, gap or space utility and no arbitrary spacing value in a class string; a Grammar stylesheet writes no spacing length off the scale and no fluid spacing value."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_SPACING_UTILITY", "FE_SPACING_OFF_SCALE"]
+    enforcers:
+      - {kind: eslint-fe, id: no-spacing-utility}
+      - {kind: stylelint, id: spacing-scale}
+    editions: [lite, full]
+    docs: [contexts/ui/presentation.md]
+    templateNa: "A template's own layout is moved onto the role props by starci app codemod spacing-roles; the rule counts at warn for one cohort."
+    proves:
+      - {path: packages/eslint-canon-fe/src/spacing.spec.ts, editions: [lite, full], codes: [FE_SPACING_UTILITY]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-fe/src/spacing.spec.ts, editions: [lite, full], codes: [FE_SPACING_UTILITY]}
+    witness:
+      - {path: packages/eslint-canon-fe/src/spacing.spec.ts, editions: [lite, full], codes: [FE_SPACING_UTILITY]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "hay full 3 bỏ 4 đi!!! thầy nghĩ nên v"
+        ruling: "One spacing scale with no 16; every container holds its content 12 in, and an app names relations through role props, never spacing utilities."

package/runtime/knowledge/hfs/slots.yaml

@@ -467,6 +467,10 @@ ruleParams:
       - {name: public.event_bus_bury, reason: "platform/event-bus (add webhook, lite): the move of an exhausted or malformed message to its consumer's dead-letter queue"}
       - {name: public.event_bus_dead_letters, reason: "platform/event-bus (add webhook, lite): the operator read of a consumer's dead-letter queue"}
       - {name: public.event_bus_requeue, reason: "platform/event-bus (add webhook, lite): the operator requeue of one dead letter"}
+    # 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"}
 
     lite:
       schemaAuthority: sql
@@ -2070,7 +2074,7 @@ slots:
         own; use-test-world.ts exports useTestWorld({ modules: [...] }) -> world.db.<connection> (the shared EntityManager) and
         world.fake.<provider> (a network-edge fake of an external SaaS). There is no world.apps (no e2e) and no world.infra
         (no self-hosted service to cut)
-    allows: [global-setup.ts, global-teardown.ts, use-test-world.ts, "fakes/<provider>/server.ts", fakes/]   # jest globalSetup/globalTeardown default-export (Jest API); fakes/<provider>/server.ts is the fake server of a provider, a literal file name BE_SOURCE_FORM reads as its role; plus root files with a role suffix (test-world-files, R47)
+    allows: [global-setup.ts, global-teardown.ts, use-test-world.ts, "fakes/<provider>/server.ts", fakes/, "<name>.sql.ts"]   # jest globalSetup/globalTeardown default-export (Jest API); fakes/<provider>/server.ts is the fake server of a provider, a literal file name BE_SOURCE_FORM reads as its role; plus root files with a role suffix (test-world-files, R47)
     tests: none
     coverage: none
     why: >-

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

@@ -5634,12 +5634,12 @@ LITE_DB_MIGRATION:
   kind: check-finding
 
 BE_PERSISTENCE_NO_RAW_SQL:
-  title: "Lite domain, feature or test code runs raw SQL instead of TypeORM entities"
-  title_vi: "Mã domain, feature hoặc test của app lite chạy SQL thô thay vì entity TypeORM"
-  meaning_vi: "File `<path>` gọi `.query(` hoặc dùng template `sql` ngoài hai chủ của SQL thô là platform/database và test world src/tests/world, hoặc gọi callDbFunction với một hàm không có trong ruleParams.be.dbFunctions hay hfs.json sides.be.dbFunctions."
+  title: "Lite TypeScript runs or holds SQL text outside the test world"
+  title_vi: "TypeScript của app lite chạy hoặc chứa văn bản SQL ngoài test world"
+  meaning_vi: "File `<path>` gọi `.query(`, dùng template `sql`, là file `*.sql.ts`, import `sql`/`ident`/`SqlText`/`SqlIdent` ngoài src/tests/world (trừ bộ soạn câu lệnh của platform/database/database.client.ts và file có tên trong ruleParams.be.sqlPassThrough hay hfs.json sides.be.sqlPassThrough), gọi callDbFunction với một hàm không có trong ruleParams.be.dbFunctions hay hfs.json sides.be.dbFunctions, hoặc trong test world viết SQL thô cho điều entity hoặc hàm đã khai báo diễn đạt được (gọi hàm, ghi bảng ứng dụng)."
   causes_vi:
-    - "Vi phạm R334: dữ liệu của app lite, kể cả spec, builder và fixture, đi qua entity TypeORM trên EntityManager (find, save, update, upsert, createQueryBuilder); spec dùng world.db.<connection>."
-  nextStep_vi: "Đọc/ghi bằng entity trên EntityManager hoặc createQueryBuilder với tham số có tên (trong test là world.db.<connection>); hàm database TypeORM không diễn đạt được thì gọi qua callDbFunction với hàm đã khai kèm lý do; điều entity không diễn đạt được trong test (trigger, thăm dò row-level security, hàng đợi pgmq) thì gọi một helper có tên của src/tests/world."
+    - "Vi phạm R334: dữ liệu của app lite, kể cả spec, builder, fixture và test world, đi qua entity TypeORM trên EntityManager (find, save, update, upsert, createQueryBuilder); hàm database đi qua callDbFunction; SQL thô chỉ còn ở test world cho thăm dò (quyền, row-level security, catalog, cron, trigger, bảng pgmq, khóa/lỗi)."
+  nextStep_vi: "Đọc/ghi bằng entity trên EntityManager hoặc createQueryBuilder với tham số có tên (trong test là world.db.<connection>); hàm database thì gọi qua callDbFunction với hàm đã khai kèm lý do; file chỉ chuyển tiếp văn bản SQL không phải của app thì khai trong hfs.json sides.be.sqlPassThrough kèm lý do; thăm dò chỉ test world mới được viết SQL thô."
   owner: op-retry
   kind: check-finding
 

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

@@ -1,6 +1,6 @@
 import { isPlainObject } from '../../engine/plain-object.mjs';
 import { APP_KIND, connectionShapeProblems, NAME, PACKAGE_NAME, RUNTIME_KIND, SLOT_ID } from './manifest-shape.mjs';
-import { dbFunctionsOk } from './rule-params-shape.mjs';
+import { dbFunctionsOk, sqlPassThroughOk } from './rule-params-shape.mjs';
 import { kindShapeProblems, patternShapeProblems } from './declaration-slots.mjs';
 import { byCodeUnit } from '../lib/list.mjs';
 /** Shape problems of the optional hfs.json `db` block of a lite app: the environment variable naming its database, its image, forced RLS and its application role. */
@@ -91,10 +91,12 @@ function declarationSideProblems(side, value, names) {
     if (!isPlainObject(value))
         return [`${at} must be an object`];
     for (const key of Object.keys(value))
-        if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing', 'dbFunctions'].includes(key))
+        if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing', 'dbFunctions', 'sqlPassThrough'].includes(key))
             bad.push(`${at} has unknown key ${key}`);
     if (value.dbFunctions !== undefined && (side !== 'be' || !dbFunctionsOk(value.dbFunctions, { bare: true })))
         bad.push(`${at}.dbFunctions belongs to the be side and lists {name, reason} database functions, each schema-qualified (schema.name, never pg_catalog) or a bare pg built-in of the canon's list, with unique names`);
+    if (value.sqlPassThrough !== undefined && (side !== 'be' || !sqlPassThroughOk(value.sqlPassThrough)))
+        bad.push(`${at}.sqlPassThrough belongs to the be side and lists {file, reason} files relative to the side folder, forward slashes, unique, each with the reason its SQL text is not the app's own`);
     bad.push(...appShapeProblems(value.apps, at, side, names));
     if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot))))
         bad.push(`${at}.optionalSlots must be a unique list of slot ids`);

package/runtime/scripts/hfs/manifest-shape.d.mts

@@ -92,6 +92,11 @@ export interface DbFunction {
     name: string;
     reason: string;
 }
+/** A file whose `.query(` passes through SQL text that is not the app's own (ruleParams.be.sqlPassThrough, hfs.json sides.be.sqlPassThrough). */
+export interface SqlPassThrough {
+    file: string;
+    reason: string;
+}
 /** The rule parameters of one profile (ruleParams.common merged with ruleParams.<profile>); the keys not named here are parsed manifest data. */
 export interface RuleParams {
     [key: string]: Parsed;
@@ -107,6 +112,7 @@ export interface RuleParams {
     suffixes?: string[];
     bannedSuffixes?: string[];
     dbFunctions?: DbFunction[];
+    sqlPassThrough?: SqlPassThrough[];
 }
 /** ruleParams.be: the back end's own parameters, which the validators of this folder require. */
 export interface BeRuleParams extends RuleParams {

package/runtime/scripts/hfs/rule-params-shape.d.mts

@@ -6,5 +6,10 @@ import type { Parsed } from './manifest-shape.mjs';
 export declare const dbFunctionsOk: (list: Parsed, { bare }?: {
     bare?: boolean;
 }) => boolean;
+/**
+ * True for an absent list or a list of {file, reason} SQL pass-through files (R334): `file` is a forward-slash path relative to the
+ * side folder (no leading slash, no `..`), unique, and the reason names whose text the file passes through.
+ */
+export declare const sqlPassThroughOk: (list: Parsed) => boolean;
 /** The shape problems of `m.ruleParams`. */
 export declare function ruleParamsProblems(m: Parsed): string[];

package/runtime/scripts/hfs/rule-params-shape.mjs

@@ -73,6 +73,11 @@ const dbFunctionNameOk = (name, bare) => typeof name === 'string' && (/^[a-z_][a
  * a bare name, which only the canon's list (ruleParams.be.dbFunctions) uses, for the pg built-ins its helpers call.
  */
 export const dbFunctionsOk = (list, { bare = false } = {}) => list === undefined || (Array.isArray(list) && list.every((entry) => isPlainObject(entry) && Object.keys(entry).sort().join() === 'name,reason' && dbFunctionNameOk(entry.name, bare) && typeof entry.reason === 'string' && entry.reason.trim().length > 0) && new Set(list.map((entry) => entry.name)).size === list.length);
+/**
+ * True for an absent list or a list of {file, reason} SQL pass-through files (R334): `file` is a forward-slash path relative to the
+ * side folder (no leading slash, no `..`), unique, and the reason names whose text the file passes through.
+ */
+export const sqlPassThroughOk = (list) => list === undefined || (Array.isArray(list) && list.every((entry) => isPlainObject(entry) && Object.keys(entry).sort().join() === 'file,reason' && typeof entry.file === 'string' && /^[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.-]+)*$/.test(entry.file) && !entry.file.split('/').includes('..') && typeof entry.reason === 'string' && entry.reason.trim().length > 0) && new Set(list.map((entry) => entry.file)).size === list.length);
 /** The shape problems of `m.ruleParams`. */
 export function ruleParamsProblems(m) {
     const bad = [];
@@ -84,8 +89,8 @@ export function ruleParamsProblems(m) {
         // Edition lite: a side's optional `lite` map overrides keys of the same side (never `lite` itself) when the app declares edition lite.
         if (!sideOk(rp.common, []) || !fileLinesOk(rp.common.fileLines) || !blockOk(rp.common.duplicateBlock))
             bad.push('ruleParams.common needs fileLines {soft, hardGrowth} and duplicateBlock {lines >= 2, tokens >= 1}; optional functionLines and featureFiles must be positive integers');
-        if (!sideOk(rp.be, BE_OWN, ['schemaAuthority', 'lite', 'dbFunctions']) || (rp.be.schemaAuthority !== undefined && !SCHEMA_AUTHORITIES.includes(rp.be.schemaAuthority)) || !dbFunctionsOk(rp.be.dbFunctions, { bare: true }) || !liteOk(rp.be.lite, [...BE_OWN, ...SHARED_KEYS, 'schemaAuthority', 'dbFunctions']))
-            bad.push('ruleParams.be needs infraOwners, eventBus, specDoubles, paramNames, suffixes, bannedSuffixes, contractShape {helper}, unitRoles, logicRoles, thinRoles, patternScenarios, kindPatterns, addKinds and backing (shared parameters live in ruleParams.common, a side may override them); optional: schemaAuthority (' + SCHEMA_AUTHORITIES.join(' | ') + '), dbFunctions ([{name, reason}]: a pg built-in bare, every other function schema.name) and lite (overrides of the same keys)');
+        if (!sideOk(rp.be, BE_OWN, ['schemaAuthority', 'lite', 'dbFunctions', 'sqlPassThrough']) || (rp.be.schemaAuthority !== undefined && !SCHEMA_AUTHORITIES.includes(rp.be.schemaAuthority)) || !dbFunctionsOk(rp.be.dbFunctions, { bare: true }) || !sqlPassThroughOk(rp.be.sqlPassThrough) || !liteOk(rp.be.lite, [...BE_OWN, ...SHARED_KEYS, 'schemaAuthority', 'dbFunctions', 'sqlPassThrough']))
+            bad.push('ruleParams.be needs infraOwners, eventBus, specDoubles, paramNames, suffixes, bannedSuffixes, contractShape {helper}, unitRoles, logicRoles, thinRoles, patternScenarios, kindPatterns, addKinds and backing (shared parameters live in ruleParams.common, a side may override them); optional: schemaAuthority (' + SCHEMA_AUTHORITIES.join(' | ') + '), dbFunctions ([{name, reason}]: a pg built-in bare, every other function schema.name), sqlPassThrough ([{file, reason}]: a file whose SQL text is not written by the app) and lite (overrides of the same keys)');
         else
             bad.push(...unitRolesProblems(rp.be), ...roleListProblems(rp.be));
         bad.push(...beSpecificProblems(rp.be, m));

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

@@ -3,7 +3,7 @@ import type { Side } from './slot-manifest-shape.mjs';
 import type { AppRepo } from './slot-app-view.mjs';
 import { loadRuleCatalog } from './rule-catalog.mjs';
 import type { RuleCatalog } from './rule-catalog.mjs';
-import type { DbFunction, Parsed, RuleParams, Slot, SlotManifest, SlotTracking } from './manifest-shape.mjs';
+import type { DbFunction, Parsed, RuleParams, Slot, SlotManifest, SlotTracking, SqlPassThrough } from './manifest-shape.mjs';
 import type { ClassifiedPath, OwnerUnit } from './slot-classify.mjs';
 export type { Bindings } from './slot-match.mjs';
 export type { ClassifiedPath, OwnerUnit, PlacedPath, AmbiguousPath, UndeclaredPath } from './slot-classify.mjs';
@@ -41,6 +41,7 @@ export interface RepoView {
     providers?: readonly string[];
     reads: readonly string[];
     dbFunctions?: readonly DbFunction[];
+    sqlPassThrough?: readonly SqlPassThrough[];
     grammar?: string;
     extraPackages?: readonly {
         name: string;

package/runtime/scripts/hfs/slots.mjs

@@ -125,6 +125,7 @@ function sideDeclaration(manifest, declaration, name, edition, providers) {
         providers,
         reads: Object.freeze([...(s.reads ?? [])]),
         dbFunctions: Object.freeze((s.dbFunctions ?? []).map((entry) => Object.freeze({ ...entry }))),
+        sqlPassThrough: Object.freeze((s.sqlPassThrough ?? []).map((entry) => Object.freeze({ ...entry }))),
         ...(s.grammar === undefined ? {} : { grammar: s.grammar }),
         ...(s.extraPackages === undefined ? {} : { extraPackages: Object.freeze(s.extraPackages.map((entry) => Object.freeze({ ...entry }))) }),
         manifestVersion: manifest.version,
@@ -251,8 +252,8 @@ function createScopeResolver(manifest, repo) {
         trackingOf,
         /** True only for a path a slot owns and requires to be committed. */
         isTracked: (p) => trackingOf(p) === 'tracked',
-        // The app's own database functions (hfs.json sides.be.dbFunctions) join the canon's list (R334).
-        ruleParams: () => withDeclaredDbFunctions(ruleParams(manifest, profile, edition), repo.dbFunctions),
+        // The app's own database functions and SQL pass-through files (hfs.json sides.be.dbFunctions, sides.be.sqlPassThrough) join the canon's lists (R334).
+        ruleParams: () => withDeclaredLists(ruleParams(manifest, profile, edition), repo),
         allowedImports: (tier) => manifest.tiers[profile]?.[tier]?.mayImport ?? null,
     });
 }
@@ -274,9 +275,18 @@ export function createSlotResolver(manifest, repo) {
     const sides = Object.fromEntries(PROFILES.map((side) => [side, createScopeResolver(manifest, app.sides[side])]));
     return appResolver(app, root, sides);
 }
-/** The rule parameters with the app's declared database functions appended to `dbFunctions` (be only), frozen. */
-const withDeclaredDbFunctions = (params, declared = []) => (params.dbFunctions === undefined && !declared.length ? params
-    : Object.freeze({ ...params, dbFunctions: Object.freeze([...(params.dbFunctions ?? []), ...declared]) }));
+/** The rule parameters with the app's declared database functions and SQL pass-through files appended to `dbFunctions` and `sqlPassThrough` (be only), the result frozen. */
+const withDeclaredLists = (params, repo) => {
+    const functions = repo.dbFunctions ?? [];
+    const passThrough = repo.sqlPassThrough ?? [];
+    if ((params.dbFunctions === undefined && !functions.length) && (params.sqlPassThrough === undefined && !passThrough.length))
+        return params;
+    return Object.freeze({
+        ...params,
+        ...(params.dbFunctions === undefined && !functions.length ? {} : { dbFunctions: [...(params.dbFunctions ?? []), ...functions] }),
+        ...(params.sqlPassThrough === undefined && !passThrough.length ? {} : { sqlPassThrough: [...(params.sqlPassThrough ?? []), ...passThrough] }),
+    });
+};
 /** The rule parameters of one profile (be: infraOwners, suffixes, bannedSuffixes and the rest over the shared ruleParams.common fileLines and duplicateBlock; fe: common alone or with its overrides; runtime: ruleParams.runtime of a runtime manifest), as a frozen deep copy. Under `edition` lite the `lite` overrides of ruleParams.<profile> merge over the base (the `lite` key itself is never returned). */
 export function ruleParams(manifest, profile, edition = 'full') {
     const profiles = manifestKind(manifest) === RUNTIME_KIND ? [RUNTIME_KIND] : PROFILES;

package/src/main.mjs

@@ -129,7 +129,7 @@ import { BOOLEAN as CI_BOOLEAN, COMMANDS as CI_COMMANDS } from '../ci/cli.mjs';
 import { LOCAL_FLAGS as CI_LOCAL_FLAGS } from '../ci/local.mjs';
 import { USAGE as COVERAGE_USAGE } from '../coverage/cli.mjs';
 import { SYNC_USAGE } from '../sync/cli.mjs';
-import { codemodMain } from '../codemod/button-intent.mjs';
+import { codemodMain } from '../codemod/main.mjs';
 /** A value flag as parse stores it: the string given, else undefined. */
 const valueFlag = (opts, flag) => { const given = opts[flag]; return typeof given === 'string' ? given : undefined; };
 /** A boolean flag as parse stores it: true when given, else undefined. */
@@ -192,7 +192,7 @@ const DATABASE_USAGE = [['new', '<kebab-name>', DB_NEW_FLAGS], ['baseline', '',
 const VERB_USAGE = {
     ...Object.fromEntries(Object.entries(PARSED).map(([verb, spec]) => [verb, spec.forms.map((form) => line(`starci app ${verb}`, form.operands, specUsage(form.only ?? (form.flags === undefined ? spec : { value: form.flags })), spec.edition && form.edition !== false ? flagUsage('--edition', { value: true }) : ''))])),
     lint: ['starci app lint [--changed <file>...] [--workspace <dir>] [--side be|fe] [--fix] [--full] [--full] [--json] [--out <file>]'],
-    codemod: ['starci app codemod button-intent [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]'],
+    codemod: ['starci app codemod button-intent [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]', 'starci app codemod spacing-roles [--execute] [--json] [--format json|markdown] [--out <file.json|file.md>]'],
     upgrade: ['starci app upgrade [--execute]'],
     sync: [SYNC_USAGE.sync],
     world: ['starci app world <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--edition full|lite]'],

package/templates/be/skeleton-lite/src/modules/platform/database/database.client.spec.ts

@@ -74,23 +74,42 @@ describe("callDbFunction", () => {
 })
 
 describe("advisoryXactLock", () => {
-    it("locks the 64-bit hash of the key for the transaction", async () => {
+    it("hashes the key, then locks the hash for the transaction, both as function calls", async () => {
         const client = await setup()
-        const manager = mockEntityManager({ query: ["SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [{}]] })
+        const manager = mockEntityManager({
+            query: [
+                ['SELECT * FROM "pg_catalog"."hashtextextended"($1, $2)', [{ hashtextextended: "42" }]],
+                ['SELECT * FROM "pg_catalog"."pg_advisory_xact_lock"($1)', [{}]],
+            ],
+        })
 
         await expect(client.advisoryXactLock(manager, "jobs:mail")).resolves.toBeUndefined()
 
-        expect(manager.query).toHaveBeenCalledWith("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", ["jobs:mail"])
+        expect(manager.query).toHaveBeenNthCalledWith(1, 'SELECT * FROM "pg_catalog"."hashtextextended"($1, $2)', ["jobs:mail", 0])
+        expect(manager.query).toHaveBeenNthCalledWith(2, 'SELECT * FROM "pg_catalog"."pg_advisory_xact_lock"($1)', ["42"])
+    })
+
+    it.each([
+        ["no row", []],
+        ["a row with no hash", [{}]],
+        ["a hash that is not a number", [{ hashtextextended: null }]],
+    ])("refuses %s before it locks", async (_case, rows) => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ['SELECT * FROM "pg_catalog"."hashtextextended"($1, $2)', rows] })
+
+        await expect(client.advisoryXactLock(manager, "jobs:mail")).rejects.toMatchObject({ code: DatabaseErrorCode.ReturningRowRejected })
+
+        expect(manager.query).toHaveBeenCalledTimes(1)
     })
 })
 
 describe("notify", () => {
-    it("sends the payload on the channel", async () => {
+    it("sends the payload on the channel as a function call", async () => {
         const client = await setup()
-        const manager = mockEntityManager({ query: ["SELECT pg_notify($1, $2)", [{}]] })
+        const manager = mockEntityManager({ query: ['SELECT * FROM "pg_catalog"."pg_notify"($1, $2)', [{}]] })
 
         await expect(client.notify(manager, "jobs", '{"id":"job-1"}')).resolves.toBeUndefined()
 
-        expect(manager.query).toHaveBeenCalledWith("SELECT pg_notify($1, $2)", ["jobs", '{"id":"job-1"}'])
+        expect(manager.query).toHaveBeenCalledWith('SELECT * FROM "pg_catalog"."pg_notify"($1, $2)', ["jobs", '{"id":"job-1"}'])
     })
 })

package/templates/be/skeleton-lite/src/modules/platform/database/database.client.ts

@@ -82,12 +82,22 @@ export const callDbFunction = <T>(manager: EntityManager, name: string, args: Re
     return manager.query<Array<T>>(`SELECT * FROM "${target.schema}"."${target.name}"(${parameters})`, [...args])
 }
 
-/** Takes a transaction-scoped advisory lock on the 64-bit hash of `key`; it is released when the manager's transaction ends. */
+/** The refusal of a hash answer that is not the number the lock takes. */
+const hashRejected = (key: string): DatabaseError =>
+    new DatabaseError({ code: DatabaseErrorCode.ReturningRowRejected, params: { name: "hashtextextended", key } })
+
+/**
+ * Takes a transaction-scoped advisory lock on the 64-bit hash of `key`; it is released when the manager's transaction ends.
+ * Both steps are `callDbFunction` calls of listed pg built-ins, so no SQL text is written here (R334).
+ */
 export const advisoryXactLock = async (manager: EntityManager, key: string): Promise<void> => {
-    await manager.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [key])
+    const rows = await callDbFunction<Record<string, unknown>>(manager, "hashtextextended", [key, 0])
+    const hash = rows[0]?.["hashtextextended"]
+    if (typeof hash !== "string" && typeof hash !== "number" && typeof hash !== "bigint") throw hashRejected(key)
+    await callDbFunction(manager, "pg_advisory_xact_lock", [hash])
 }
 
 /** Sends one NOTIFY on `channel` with `payload`, delivered when the manager's transaction commits. */
 export const notify = async (manager: EntityManager, channel: string, payload: string): Promise<void> => {
-    await manager.query("SELECT pg_notify($1, $2)", [channel, payload])
+    await callDbFunction(manager, "pg_notify", [channel, payload])
 }