@starci/eslint-canon-fe 9.6.5 → 9.7.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 9.7.0 - 2026-10-31
+
+- Added: R349 `no-hand-built-panes` (`FE_HAND_BUILT_PANES`, surface rules, slot-free): a multi-pane frame is a `PaneGrid`, so a vertical Grammar `Divider` used as a column seam (among the plain columns of a flex row, or anywhere inside a `SurfaceCard composition="joined"`) and a joined card that holds a flex row of two or more plain columns are refused.
+- Changed: `Pane` and `PaneSection` are surfaces for `no-list-panel-padding` (R318), so wrapper padding around a `ListBox` in a pane is caught in the file. The bundled runtime copies follow @starci/hfs 4.15.0 and the 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.
+
+## 9.6.7 - 2026-10-31
+
+- Changed: the bundled runtime copies follow @starci/hfs 4.14.0 (R334 one style, `ruleParams.be.sqlPassThrough`) and the 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, with @starci/ai-router 0.5.0; no rule changed.
+
+## 9.6.6 - 2026-10-31
+
+- Changed: the bundled 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.
+
 ## 9.6.5 - 2026-10-31
 
 - Changed: the bundled runtime copies follow @starci/hfs 4.13.2 (R344 on the `be.integrations` slot) and the canon pins name hfs 4.13.2, eslint-canon-be 3.10.0, eslint-canon-fe 9.6.5, eslint-grammar-core and eslint-grammar-offset-pop 0.16.5; no rule changed.

package/README.md

@@ -41,7 +41,9 @@ family that publishes the shared HeroUI surface and field API: `nested-control-v
 variants on layer-aware fields and primary Tabs inside painted Grammar surfaces (`FE_NESTED_VARIANT`),
 `no-app-surface-paint` keeps surface paint in Grammar (`FE_GRAMMAR_LAYOUT_ONLY`) and
 `no-list-panel-padding` refuses horizontal padding wrappers around Grammar lists and section captions
-within the nearest painted surface (`FE_LIST_PANEL_PADDING`). The R65 budget law's
+within the nearest painted surface, a `Pane` or a `PaneSection` included (`FE_LIST_PANEL_PADDING`), and
+`no-hand-built-panes` refuses a multi-pane frame drawn by hand, a vertical divider as a column seam or
+columns inside a joined card, where `PaneGrid` owns both (`FE_HAND_BUILT_PANES`). The R65 budget law's
 `no-app-relative-clock` leaves live relative time and countdowns to Grammar's shared clock.
 
 The [button intent law](docs/button-intent.md) (CTA-6) requires every app Button and IconButton to

package/dist/lib/config.js

@@ -96,7 +96,7 @@ export const SLOT_FREE_RULES = Object.freeze([
     "no-native-anchor", "no-inline-parameter-type", "no-hand-rolled-polling", "no-copy-in-call", "no-alert", "no-failure-collapse",
     "outcome-kinds-exhaustive", "no-await-in-loop", "prefer-code-point", "prefer-string-raw", "no-nested-conditional", "no-void-operator", "no-unused-import",
     "prefer-export-from", "no-unused-prop-types", "media-has-caption", "max-params",
-    "nested-control-variant", "no-list-panel-padding", "no-app-surface-paint", "divider-full-bleed", "control-height", "selection-fill-no-check", "no-grammar-shim",
+    "nested-control-variant", "no-list-panel-padding", "no-hand-built-panes", "no-app-surface-paint", "divider-full-bleed", "control-height", "selection-fill-no-check", "no-grammar-shim",
     "button-intent-required", "button-no-variant", "destructive-confirm-in-dialog", "single-commit-per-render", "no-commit-in-collection-item",
 ]);
 /** The source of a plain front-end tree: its `src/`. */

package/dist/lib/why.d.ts

@@ -32,6 +32,11 @@ export declare const why: {
         en: string;
         fix: string;
     };
+    "no-hand-built-panes": {
+        code: string;
+        en: string;
+        fix: string;
+    };
     "button-intent-required": {
         code: string;
         en: string;

package/dist/lib/why.js

@@ -32,6 +32,11 @@ export const why = {
         en: "`<file>` insets a horizontal Grammar divider with wrapper padding.",
         fix: "Move horizontal padding to the sibling content bands so the divider reaches both surface edges.",
     },
+    "no-hand-built-panes": {
+        code: "FE_HAND_BUILT_PANES",
+        en: "`<file>` draws a multi-pane frame by hand: a vertical Divider between columns of a flex row, or a flex row of columns inside a joined SurfaceCard.",
+        fix: "Compose the columns as Panes of a PaneGrid (areas per breakpoint, collapse=\"drawer\" for a side pane), mounted as Page chrome=\"panes\" on a tabbed app page.",
+    },
     "button-intent-required": {
         code: "FE_BUTTON_INTENT_REQUIRED",
         en: "`<file>` renders a Button or IconButton without the command's intent.",

package/dist/surface-rules.d.ts

@@ -7,10 +7,13 @@ export declare const noAppSurfacePaint: import("./lib/rule.js").Rule<"surface",
 export declare const noListPanelPadding: import("./lib/rule.js").Rule<"padding", []>;
 /** BOUNDARY-1 case-5: only content bands carry inset; horizontal separators reach the surface edges. */
 export declare const dividerFullBleed: import("./lib/rule.js").Rule<"padding", []>;
+/** A multi-pane frame is a PaneGrid: a vertical divider between columns, or columns inside a joined card, is a pane frame drawn by hand. */
+export declare const noHandBuiltPanes: import("./lib/rule.js").Rule<"seam" | "joined", []>;
 /** The surface laws ship at error in every composing source tree. */
 export declare const rules: {
     "divider-full-bleed": import("./lib/rule.js").Rule<"padding", []>;
     "nested-control-variant": import("./lib/rule.js").Rule<"variant" | "tabs", []>;
+    "no-hand-built-panes": import("./lib/rule.js").Rule<"seam" | "joined", []>;
     "no-list-panel-padding": import("./lib/rule.js").Rule<"padding", []>;
     "no-app-surface-paint": import("./lib/rule.js").Rule<"surface", []>;
 };

package/dist/surface-rules.js

@@ -1,4 +1,4 @@
-/** Grammar owns surface nesting and the single content edge of a panel list (ANATOMY-2, PADDING-0). */
+/** Grammar owns surface nesting, the single content edge of a panel list (ANATOMY-2, PADDING-0) and the column seams of a pane frame (PaneGrid). */
 import { attributeValue, stringOf, walk } from "./lib/ast.js";
 import { functionOf, importOf, isFn, patternPath, unwrap, variableOf } from "./lib/bindings.js";
 import { typedClassStrings, typedPropertyStrings } from "./lib/typed-class-values.js";
@@ -15,7 +15,7 @@ const GRAMMAR_ENTRY = /^@starci\/grammar(?:\/(?:common|core|offset-pop))?$/;
 const SURFACES = new Set([
     "SurfaceCard", "SurfaceListCard", "SurfaceAccordionCard", "Sidebar",
     "Dialog", "Drawer", "AlertDialog", "Popover",
-    "WorkspaceShell", "TopBar", "NavigationFeatureNav",
+    "WorkspaceShell", "TopBar", "NavigationFeatureNav", "Pane", "PaneSection",
 ]);
 const FIELDS = new Set([
     "Input", "TextField", "Textarea", "TextArea", "SearchField", "NumberField", "DateField", "TimeField",
@@ -486,7 +486,116 @@ export const dividerFullBleed = defineRule({
         };
     },
 });
+/** True for a plain element (`div`), as opposed to a component. */
+const rawElement = (opening) => opening.name.type === "JSXIdentifier" && /^[a-z]/.test(opening.name.name);
+/** The elements one JSX child can render, through fragments, conditionals and `&&`; anything else renders none this rule can name. */
+const elementsOfChild = (child) => {
+    if (!child)
+        return [];
+    if (child.type === "JSXElement")
+        return [child];
+    if (child.type === "JSXFragment")
+        return child.children.flatMap((entry) => elementsOfChild(entry));
+    if (child.type === "JSXExpressionContainer")
+        return elementsOfChild(child.expression);
+    if (child.type === "ConditionalExpression")
+        return [...elementsOfChild(child.consequent), ...elementsOfChild(child.alternate)];
+    if (child.type === "LogicalExpression")
+        return child.operator === "&&" ? elementsOfChild(child.right) : [...elementsOfChild(child.left), ...elementsOfChild(child.right)];
+    return [];
+};
+/** The children that render: whitespace-only text and empty expressions are left out. */
+const renderedChildren = (element) => element.children.filter((child) => child.type === "JSXText" ? child.value.trim() !== "" : child.type !== "JSXExpressionContainer" || child.expression.type !== "JSXEmptyExpression");
+/** A column of a hand-built split: a plain block element (`div`, `aside`) or a Grammar `Region`. */
+const isColumn = (context, element) => rawElement(element.openingElement) || grammarName(context, element.openingElement.name)?.[0] === "Region";
+/** How a plain element lays out its children, read from its authored classes: `row`, `stack` (a column), `none` (not flex or grid), or `unknown` (no static class). */
+const flowOf = (context, opening) => {
+    const texts = opening.attributes.flatMap((entry) => ["className", "class"].flatMap((name) => propStrings(context, entry, name).map((value) => value.text)));
+    if (texts.length === 0)
+        return "unknown";
+    const tokens = texts.flatMap((text) => text.split(/\s+/)).filter((token) => token !== "");
+    if (!tokens.some((token) => /^(?:flex|inline-flex|grid|inline-grid)$/.test(token.slice(token.lastIndexOf(":") + 1))))
+        return "none";
+    const column = tokens.some((token) => token === "flex-col" || token === "flex-col-reverse");
+    const row = tokens.some((token) => /(?:^|:)flex-row(?:-reverse)?$/.test(token));
+    return column && !row ? "stack" : "row";
+};
+/** True when the opening element is a vertical Grammar Divider or Separator. */
+const verticalDivider = (context, opening) => {
+    const name = grammarName(context, opening.name);
+    if (name?.length !== 1 || !isOneOf(["Divider", "Separator"], name[0]))
+        return false;
+    return opening.attributes.some((entry) => propStrings(context, entry, "orientation", "variant").some((value) => value.text === "vertical"));
+};
+/** True when the opening element is a Grammar SurfaceCard composed `joined`. */
+const joinedCard = (context, opening) => {
+    const name = grammarName(context, opening.name);
+    return name?.length === 1 && name[0] === "SurfaceCard" && opening.attributes.some((entry) => propStrings(context, entry, "composition", "variant").some((value) => value.text === "joined"));
+};
+/** The columns a plain flex row holds side by side, or none when the element is not a row of two or more. */
+const rowColumns = (context, element) => {
+    if (!rawElement(element.openingElement) || flowOf(context, element.openingElement) !== "row")
+        return [];
+    const columns = renderedChildren(element).flatMap((child) => elementsOfChild(child)).filter((child) => isColumn(context, child));
+    return columns.length >= 2 ? columns : [];
+};
+/** The joined card element a node stands in, in this file, or null. */
+const enclosingJoinedCard = (context, node) => {
+    for (let current = node.parent; current; current = current.parent) {
+        if (current.type === "JSXElement" && joinedCard(context, current.openingElement))
+            return current;
+    }
+    return null;
+};
+/** True when a joined card holds a plain row of columns as one of its own children: a pane frame drawn by hand. */
+const holdsColumnRow = (context, card) => renderedChildren(card).flatMap((child) => elementsOfChild(child)).some((child) => rowColumns(context, child).length > 0);
+/** True when a vertical divider stands between plain columns of one flex row: directly, or inside a wrapper element that holds only it. */
+const isColumnSeam = (context, divider) => {
+    let unit = divider;
+    const wrapper = divider.parent;
+    if (wrapper.type === "JSXElement" && rawElement(wrapper.openingElement) && renderedChildren(wrapper).length === 1)
+        unit = wrapper;
+    const container = unit.parent;
+    if (container.type !== "JSXElement" || !rawElement(container.openingElement))
+        return false;
+    if (!["row", "unknown"].includes(flowOf(context, container.openingElement)))
+        return false;
+    return renderedChildren(container).flatMap((child) => elementsOfChild(child)).some((sibling) => sibling !== unit && isColumn(context, sibling));
+};
+/** A multi-pane frame is a PaneGrid: a vertical divider between columns, or columns inside a joined card, is a pane frame drawn by hand. */
+export const noHandBuiltPanes = defineRule({
+    meta: {
+        type: "problem",
+        docs: { description: "PaneGrid owns the columns of a multi-pane frame and the dividers between them." },
+        schema: [],
+        messages: {
+            seam: "FE_HAND_BUILT_PANES: a vertical Divider between columns draws a pane seam by hand, so the divider, the column widths and the collapse below medium are this file's to keep in step. Compose the columns as `Pane`s of a `PaneGrid` (areas per breakpoint, `collapse=\"drawer\"` for a side pane), which draws the dividers itself.",
+            joined: "FE_HAND_BUILT_PANES: this joined SurfaceCard holds a flex row of columns, a pane frame drawn by hand inside a card. `joined` stacks bands divided by horizontal separators; side-by-side panes are a `PaneGrid` of `Pane`s, which a tabbed app page mounts as `Page chrome=\"panes\"`.",
+        },
+    },
+    create(context) {
+        return {
+            JSXOpeningElement(node) {
+                const element = node.parent;
+                if (element.type !== "JSXElement")
+                    return;
+                if (joinedCard(context, node)) {
+                    if (holdsColumnRow(context, element))
+                        context.report({ node, messageId: "joined" });
+                    return;
+                }
+                if (!verticalDivider(context, node))
+                    return;
+                const card = enclosingJoinedCard(context, node);
+                if (card !== null && holdsColumnRow(context, card))
+                    return;
+                if (card !== null || isColumnSeam(context, element))
+                    context.report({ node, messageId: "seam" });
+            },
+        };
+    },
+});
 /** The surface laws ship at error in every composing source tree. */
-export const rules = { "divider-full-bleed": dividerFullBleed, "nested-control-variant": nestedControlVariant, "no-list-panel-padding": noListPanelPadding, "no-app-surface-paint": noAppSurfacePaint };
+export const rules = { "divider-full-bleed": dividerFullBleed, "nested-control-variant": nestedControlVariant, "no-hand-built-panes": noHandBuiltPanes, "no-list-panel-padding": noListPanelPadding, "no-app-surface-paint": noAppSurfacePaint };
 /** No app can lower or omit a surface law. */
 export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]));

package/docs/surface-rules.md

@@ -26,7 +26,7 @@ Finding code: `FE_GRAMMAR_LAYOUT_ONLY`. App classes carry layout. A raw `bg-surf
 
 ## `starci-fe/no-list-panel-padding`
 
-Finding code: `FE_LIST_PANEL_PADDING`. Within the nearest painted Grammar surface, a wrapper around `ListBox` or its section caption cannot add horizontal padding through `p-*`, `px-*`, `ps-*`, `pe-*`, `pl-*`, `pr-*` or arbitrary `padding-inline` properties. These insets add to the list's own padding. Page gutters outside that surface and lists outside any surface retain their layout padding. Unpainted containers such as `Rail` pass the parent context through.
+Finding code: `FE_LIST_PANEL_PADDING`. Within the nearest painted Grammar surface (`Pane` and `PaneSection` included), a wrapper around `ListBox` or its section caption cannot add horizontal padding through `p-*`, `px-*`, `ps-*`, `pe-*`, `pl-*`, `pr-*` or arbitrary `padding-inline` properties. These insets add to the list's own padding. Page gutters outside that surface and lists outside any surface retain their layout padding. Unpainted containers such as `Rail` pass the parent context through.
 
 Invalid:
 
@@ -41,3 +41,36 @@ Valid:
 import { SurfaceCard, ListBox } from "@starci/grammar/core"
 const Panel = () => <div className="px-4"><SurfaceCard><ListBox inset="panel" label="Members" items={members} /></SurfaceCard></div>
 ```
+
+## `starci-fe/no-hand-built-panes`
+
+Finding code: `FE_HAND_BUILT_PANES`. A multi-pane frame is a `PaneGrid` of `Pane`s, which draws the dividers between panes, sizes the columns and collapses a side pane below medium. A vertical `Divider` used as a column seam is a pane frame drawn by hand: a vertical `Divider` (or the plain wrapper element that holds only it) standing among plain column elements (`div`, `aside`, `Region`) of a flex row, or a vertical `Divider` anywhere inside a `SurfaceCard composition="joined"`; and a joined card that holds a plain flex row of two or more columns as one of its own children. `joined` stacks bands divided by horizontal separators. A short vertical separator between controls of a toolbar, a `flex-col` stack, and a row whose classes cannot be read in the file are not judged. Typed app lint follows imported colocated class declarations.
+
+Invalid:
+
+```tsx
+import { Divider, SurfaceCard } from "@starci/grammar/core"
+const Frame = () => (
+  <SurfaceCard composition="joined" height="fill">
+    <div className="flex h-full">
+      <div className="w-72">{rail}</div>
+      <div className="flex"><Divider orientation="vertical" /></div>
+      <div className="flex-1">{body}</div>
+    </div>
+  </SurfaceCard>
+)
+```
+
+Valid:
+
+```tsx
+import { Page, Pane, PaneGrid, PaneSection } from "@starci/grammar/core"
+const Frame = () => (
+  <Page chrome="panes" header={header}>
+    <PaneGrid areas={areas}>
+      <Pane area="rail"><PaneSection>{rail}</PaneSection></Pane>
+      <Pane area="main"><PaneSection>{body}</PaneSection></Pane>
+    </PaneGrid>
+  </Page>
+)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.6.5",
+  "version": "9.7.0",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",

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

@@ -31,35 +31,35 @@ 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.17.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.0
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.6.5
+    version: 9.7.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.17.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.17.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.15.0
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/slots.yaml

@@ -460,6 +460,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
@@ -2027,7 +2031,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/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/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.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;