@starci/eslint-canon-fe 9.9.9 → 9.9.11

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 9.9.11
+
+- Changed: Recognize declared module hook roles through real hook-call provenance.
+
+## 9.9.10
+
+- Changed: Refresh shared repository identity and release-aligned canon data.
+
+- Fixed: Preserve generated-contract provenance in front-end tier and bounds checks.
+
 ## 9.9.9
 
 - Changed: Preserve mounted RootPage children through selected native body layouts only when their metadata constraints, immutable props and required context are proven. Retain exact body and import identity, and refresh the generated canon pins.

package/dist/hooks-folder.js

@@ -28,6 +28,7 @@
 import { defineRule } from "./lib/rule.js";
 import { importedReduxHook } from "./lib/redux-hook-origin.js";
 import { importedOwnHook } from "./lib/own-hook-origin.js";
+import { builtinHook, isLibrarySource, namedOrigin, OWN_HOOK } from "./lib/hook-library-origin.js";
 import { hfsOf } from "./lib/hfs.js";
 import { walk } from "./lib/ast.js";
 import { functionOf, isFn, unwrap, variableOf } from "./lib/bindings.js";
@@ -75,55 +76,11 @@ const exportedEntries = (node) => {
     }
     return [];
 };
-/** Actual React hook APIs and SWR public entry points, rather than an arbitrary `use*` spelling. */
-const REACT_HOOKS = new Set([
-    "use", "useState", "useReducer", "useEffect", "useLayoutEffect", "useInsertionEffect", "useRef", "useImperativeHandle",
-    "useMemo", "useCallback", "useContext", "useDebugValue", "useDeferredValue", "useTransition", "useId",
-    "useSyncExternalStore", "useActionState", "useOptimistic",
-]);
-const SWR_HOOKS = new Map([
-    ["swr", new Set(["useSWR", "useSWRConfig"])],
-    ["swr/immutable", new Set(["useSWRImmutable"])],
-    ["swr/infinite", new Set(["useSWRInfinite"])],
-    ["swr/mutation", new Set(["useSWRMutation"])],
-    ["swr/subscription", new Set(["useSWRSubscription"])],
-]);
-const SWR_DEFAULTS = new Map([["swr", "useSWR"], ["swr/immutable", "useSWRImmutable"], ["swr/infinite", "useSWRInfinite"], ["swr/mutation", "useSWRMutation"], ["swr/subscription", "useSWRSubscription"]]);
-/**
- * The canonical library hooks a composite hook may call (R56, FE-THEME): next-intl, next/navigation,
- * next-themes, react-hook-form and zustand's React entry points. A name outside the list is not a hook by its spelling.
- */
-const LIBRARY_HOOKS = new Map([
-    ["next-intl", new Set(["useTranslations", "useLocale", "useFormatter", "useNow", "useTimeZone", "useMessages"])],
-    ["next/navigation", new Set(["useRouter", "usePathname", "useSearchParams", "useParams", "useSelectedLayoutSegment", "useSelectedLayoutSegments"])],
-    ["next-themes", new Set(["useTheme"])],
-    ["react-hook-form", new Set(["useForm", "useFormContext", "useWatch", "useController", "useFieldArray", "useFormState"])],
-    ["zustand", new Set(["useStore"])],
-    ["zustand/react/shallow", new Set(["useShallow"])],
-]);
-const OWN_HOOK = "own-hooks";
-/** True when `set` holds `name`. */
-const hasName = (set, name) => set !== undefined && typeof name === "string" && set.has(name);
-const builtinHook = (origin) => {
-    if (origin === null)
-        return false;
-    return origin.source === OWN_HOOK || hasName(LIBRARY_HOOKS.get(origin.source), origin.name) || origin.source === "react-redux" || (origin.source === "react" ? hasName(REACT_HOOKS, origin.name) : hasName(SWR_HOOKS.get(origin.source), origin.name));
-};
 const propertyName = (node) => {
     if (!node.computed && node.property.type === "Identifier")
         return node.property.name;
     return node.property.type === "Literal" ? node.property.value : null;
 };
-/** SWR request hooks are default exports; its root also names useSWRConfig. */
-const namedOrigin = (source, name) => {
-    if (source === "react")
-        return { source, name };
-    if (hasName(LIBRARY_HOOKS.get(source), name))
-        return { source, name };
-    if (name === "default" && SWR_DEFAULTS.has(source))
-        return { source, name: SWR_DEFAULTS.get(source) };
-    return source === "swr" && name === "useSWRConfig" ? { source, name } : null;
-};
 /** A runtime import records whether its value is a hook or its module namespace. */
 const importOrigin = (definition) => {
     const specifier = definition.node;
@@ -132,14 +89,14 @@ const importOrigin = (definition) => {
     const source = String(definition.parent.source.value);
     if (definition.parent.importKind === "type" || ("importKind" in specifier && specifier.importKind === "type"))
         return null;
-    if (source !== "react" && !SWR_HOOKS.has(source) && !LIBRARY_HOOKS.has(source))
+    if (!isLibrarySource(source))
         return null;
     if (source === "next-themes" && specifier.type === "ImportDefaultSpecifier")
         return null;
     if (specifier.type === "ImportSpecifier")
         return namedOrigin(source, spelled(specifier.imported));
-    if (specifier.type === "ImportDefaultSpecifier" && SWR_DEFAULTS.has(source))
-        return { source, name: SWR_DEFAULTS.get(source) };
+    if (specifier.type === "ImportDefaultSpecifier")
+        return source === "react" ? { source, name: null } : namedOrigin(source, "default") ?? { source, name: null };
     return { source, name: null };
 };
 /** Resolve a constant alias, including destructuring a React/SWR namespace. */

package/dist/lib/hook-library-origin.d.ts

@@ -0,0 +1,13 @@
+/** The marker for an app hook proven by symbol provenance. */
+export declare const OWN_HOOK = "own-hooks";
+/** Where a hook comes from: the module and the export it names (null for the module object itself; any key a member reads). */
+export interface HookOrigin {
+    readonly source: string;
+    readonly name: unknown;
+}
+/** Judge an origin against the canonical library hook catalog. */
+export declare const builtinHook: (origin: HookOrigin | null) => boolean;
+/** SWR request hooks are default exports; its root also names useSWRConfig. */
+export declare const namedOrigin: (source: string, name: unknown) => HookOrigin | null;
+/** A library with a known hook entry. */
+export declare const isLibrarySource: (source: string) => boolean;

package/dist/lib/hook-library-origin.js

@@ -0,0 +1,48 @@
+/** Actual React hook APIs and SWR public entry points, rather than an arbitrary `use*` spelling. */
+const REACT_HOOKS = new Set([
+    "use", "useState", "useReducer", "useEffect", "useLayoutEffect", "useInsertionEffect", "useRef", "useImperativeHandle",
+    "useMemo", "useCallback", "useContext", "useDebugValue", "useDeferredValue", "useTransition", "useId",
+    "useSyncExternalStore", "useActionState", "useOptimistic",
+]);
+const SWR_HOOKS = new Map([
+    ["swr", new Set(["useSWR", "useSWRConfig"])],
+    ["swr/immutable", new Set(["useSWRImmutable"])],
+    ["swr/infinite", new Set(["useSWRInfinite"])],
+    ["swr/mutation", new Set(["useSWRMutation"])],
+    ["swr/subscription", new Set(["useSWRSubscription"])],
+]);
+const SWR_DEFAULTS = new Map([["swr", "useSWR"], ["swr/immutable", "useSWRImmutable"], ["swr/infinite", "useSWRInfinite"], ["swr/mutation", "useSWRMutation"], ["swr/subscription", "useSWRSubscription"]]);
+/**
+ * The canonical library hooks a composite hook may call (R56, FE-THEME): next-intl, next/navigation,
+ * next-themes, react-hook-form and zustand's React entry points. A name outside the list is not a hook by its spelling.
+ */
+const LIBRARY_HOOKS = new Map([
+    ["next-intl", new Set(["useTranslations", "useLocale", "useFormatter", "useNow", "useTimeZone", "useMessages"])],
+    ["next/navigation", new Set(["useRouter", "usePathname", "useSearchParams", "useParams", "useSelectedLayoutSegment", "useSelectedLayoutSegments"])],
+    ["next-themes", new Set(["useTheme"])],
+    ["react-hook-form", new Set(["useForm", "useFormContext", "useWatch", "useController", "useFieldArray", "useFormState"])],
+    ["zustand", new Set(["useStore"])],
+    ["zustand/react/shallow", new Set(["useShallow"])],
+]);
+/** The marker for an app hook proven by symbol provenance. */
+export const OWN_HOOK = "own-hooks";
+/** True when `set` holds `name`. */
+const hasName = (set, name) => set !== undefined && typeof name === "string" && set.has(name);
+/** Judge an origin against the canonical library hook catalog. */
+export const builtinHook = (origin) => {
+    if (origin === null)
+        return false;
+    return origin.source === OWN_HOOK || hasName(LIBRARY_HOOKS.get(origin.source), origin.name) || origin.source === "react-redux" || (origin.source === "react" ? hasName(REACT_HOOKS, origin.name) : hasName(SWR_HOOKS.get(origin.source), origin.name));
+};
+/** SWR request hooks are default exports; its root also names useSWRConfig. */
+export const namedOrigin = (source, name) => {
+    if (source === "react")
+        return { source, name };
+    if (hasName(LIBRARY_HOOKS.get(source), name))
+        return { source, name };
+    if (name === "default" && SWR_DEFAULTS.has(source))
+        return { source, name: SWR_DEFAULTS.get(source) };
+    return source === "swr" && name === "useSWRConfig" ? { source, name } : null;
+};
+/** A library with a known hook entry. */
+export const isLibrarySource = (source) => source === "react" || SWR_HOOKS.has(source) || LIBRARY_HOOKS.has(source);

package/dist/lib/own-hook-origin.js

@@ -1,5 +1,7 @@
 import ts from "typescript";
 import { programFor } from "./program-for.js";
+import { hfsOf } from "./hfs.js";
+import { builtinHook, namedOrigin } from "./hook-library-origin.js";
 const HOOKS_FOLDER = /(^|\/)hooks\//;
 const isHookName = (name) => /^use[A-Z0-9]/.test(name);
 /** The program that holds the import target: the project program has it; a program rooted at the linted file alone (its disk text may differ from the linted text) is widened with it. */
@@ -23,6 +25,133 @@ const inAppHooksFolder = (file) => {
     const fileName = file.fileName.replaceAll("\\", "/");
     return !fileName.includes("/node_modules/") && !file.isDeclarationFile && HOOKS_FOLDER.test(fileName);
 };
+/** A type-only alias never supplies a runtime hook. */
+const runtimeAlias = (declaration) => {
+    if (ts.isImportSpecifier(declaration))
+        return !declaration.isTypeOnly && !declaration.parent.parent.isTypeOnly;
+    if (ts.isImportClause(declaration))
+        return !declaration.isTypeOnly;
+    if (ts.isExportSpecifier(declaration))
+        return !declaration.isTypeOnly && !declaration.parent.parent.isTypeOnly;
+    if (ts.isNamespaceExport(declaration))
+        return !declaration.parent.isTypeOnly;
+    return false;
+};
+/** Follow every alias separately, so a type-only link or cycle never becomes a runtime binding. */
+function runtimeSymbol(checker, start) {
+    let symbol = start;
+    const seen = new Set();
+    while ((symbol.flags & ts.SymbolFlags.Alias) !== 0) {
+        if (seen.has(symbol))
+            return null;
+        seen.add(symbol);
+        const declarations = symbol.declarations ?? [];
+        if (declarations.length !== 1 || !declarations.every(runtimeAlias))
+            return null;
+        const next = checker.getImmediateAliasedSymbol(symbol);
+        if (!next)
+            return null;
+        symbol = next;
+    }
+    return symbol;
+}
+/** The module hook role is slot-defined and belongs to the same app as the caller. */
+function moduleHookRole(context, file) {
+    const hfs = hfsOf(context);
+    const found = hfs.classify(file.fileName);
+    const caller = hfs.classify(context.filename);
+    return !file.isDeclarationFile && !file.fileName.replaceAll("\\", "/").includes("/node_modules/") &&
+        found.status === "owned" && found.slot?.startsWith("fe.modules.") === true && found.role === "hooks" &&
+        found.bindings?.app !== undefined && found.bindings.app === caller.bindings?.app && hfs.allows(file.fileName)?.allowed === true;
+}
+/** A known library import is proven by its own runtime import declaration and canonical exported name. */
+function libraryImport(declaration) {
+    if (!runtimeAlias(declaration))
+        return false;
+    if (ts.isImportSpecifier(declaration)) {
+        const module = declaration.parent.parent.parent.moduleSpecifier;
+        return ts.isStringLiteral(module) && builtinHook(namedOrigin(module.text, (declaration.propertyName ?? declaration.name).text));
+    }
+    if (ts.isExportSpecifier(declaration)) {
+        const module = declaration.parent.parent.moduleSpecifier;
+        return module !== undefined && ts.isStringLiteral(module) && builtinHook(namedOrigin(module.text, (declaration.propertyName ?? declaration.name).text));
+    }
+    return false;
+}
+/** Follow runtime re-exports until a known library import itself proves the binding. */
+function librarySymbol(checker, start) {
+    let symbol = start;
+    const visited = new Set();
+    while (!visited.has(symbol)) {
+        visited.add(symbol);
+        const declarations = symbol.declarations ?? [];
+        if (declarations.length !== 1)
+            return false;
+        const declaration = declarations[0];
+        if (!declaration)
+            return false;
+        if (libraryImport(declaration))
+            return true;
+        if ((symbol.flags & ts.SymbolFlags.Alias) === 0 || !runtimeAlias(declaration))
+            return false;
+        const next = checker.getImmediateAliasedSymbol(symbol);
+        if (!next)
+            return false;
+        symbol = next;
+    }
+    return false;
+}
+/** Resolve calls through lexical symbols, constant aliases and runtime import/re-export chains. */
+function moduleHookBody(context, checker, declaration, seen) {
+    if (!moduleHookRole(context, declaration.getSourceFile()))
+        return false;
+    if (ts.isVariableDeclaration(declaration) && (declaration.parent.flags & ts.NodeFlags.Const) === 0)
+        return false;
+    const body = ts.isFunctionDeclaration(declaration) ? declaration.body : ts.isVariableDeclaration(declaration) && declaration.initializer &&
+        (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer)) ? declaration.initializer.body : undefined;
+    if (!body)
+        return false;
+    const proves = (expression, visited) => {
+        if (!ts.isIdentifier(expression))
+            return false;
+        const symbol = checker.getSymbolAtLocation(expression);
+        if (!symbol || visited.has(symbol))
+            return false;
+        const nextSeen = new Set([...visited, symbol]);
+        if (librarySymbol(checker, symbol))
+            return true;
+        const resolved = runtimeSymbol(checker, symbol);
+        if (!resolved || nextSeen.has(resolved) && resolved !== symbol)
+            return false;
+        const actual = resolved.declarations ?? [];
+        if (actual.length !== 1)
+            return false;
+        const target = actual[0];
+        if (!target)
+            return false;
+        if (hookValue(target) && inAppHooksFolder(target.getSourceFile()) && isHookName(resolved.name)) {
+            const hfs = hfsOf(context);
+            const app = hfs.classify(context.filename).bindings?.app;
+            const found = hfs.classify(target.getSourceFile().fileName);
+            return app !== undefined && found.status === "owned" && found.slot?.startsWith("fe.hooks") === true && found.bindings?.app === app;
+        }
+        if (ts.isVariableDeclaration(target) && (target.parent.flags & ts.NodeFlags.Const) !== 0 && target.initializer && ts.isIdentifier(target.initializer))
+            return proves(target.initializer, nextSeen);
+        return moduleHookBody(context, checker, target, nextSeen);
+    };
+    let found = false;
+    const visit = (node) => {
+        if (found || node !== body && ts.isFunctionLike(node))
+            return;
+        if (ts.isCallExpression(node) && proves(node.expression, seen)) {
+            found = true;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+    return found;
+}
 /** True when the import binding is a runtime `use*` import that resolves to a hook declared in a `hooks/` folder of the app. */
 export function importedOwnHook(context, definition) {
     const specifier = definition.node;
@@ -47,6 +176,11 @@ export function importedOwnHook(context, definition) {
     const exported = moduleSymbol ? checker.getExportsOfModule(moduleSymbol).find((symbol) => symbol.name === name) : undefined;
     if (!exported)
         return false;
-    const symbol = (exported.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(exported) : exported;
-    return (symbol.declarations ?? []).some((declaration) => hookValue(declaration) && inAppHooksFolder(declaration.getSourceFile()));
+    const original = (exported.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(exported) : exported;
+    if ((original.declarations ?? []).some((declaration) => hookValue(declaration) && inAppHooksFolder(declaration.getSourceFile())))
+        return true;
+    const symbol = runtimeSymbol(checker, exported);
+    if (!symbol)
+        return false;
+    return (symbol.declarations ?? []).some((declaration) => hookValue(declaration) && moduleHookBody(context, checker, declaration, new Set([symbol])));
 }

package/dist/swr-family.js

@@ -1,7 +1,9 @@
 /** R285: API operations are wrapped by the SWR family before product code calls them. */
 import { hfsOf } from "./lib/hfs.js";
 import { readFileSync, readdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { join } from "node:path";
+import ts from "typescript";
+import { isBoundsExport } from "#runtime/scripts/hfs/architecture/contract-bounds.mjs";
 import { stringOf, walk } from "./lib/ast.js";
 import { functionOf } from "./lib/bindings.js";
 import { defineRule } from "./lib/rule.js";
@@ -152,36 +154,6 @@ const isOperationSource = (context, value, only) => {
         return found.some((entry) => entry.slot === only);
     return found.some((entry) => OPERATION_SLOTS.includes(entry.slot));
 };
-/** The generated input-bounds module holds constants and a pure reader derived from the contract, never an operation. */
-const BOUNDS_MODULE = /(?:^|\/)__generated__\/input-bounds\.ts$/;
-const RE_EXPORT = /export\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g;
-const ENTRY = /^\s*(type\s+)?([\w$]+)(?:\s+as\s+([\w$]+))?\s*$/;
-/** True when the named export of `target` is, through a chain of relative named re-exports, defined by a generated input-bounds module. */
-const isBoundsExport = (target, name, depth = 0) => {
-    if (depth > 4)
-        return false;
-    for (const file of [`${target}.ts`, `${target}/index.ts`, target]) {
-        if (BOUNDS_MODULE.test(file.replaceAll("\\", "/")))
-            return true;
-        let text;
-        try {
-            text = readFileSync(file, "utf8");
-        }
-        catch {
-            continue;
-        }
-        for (const [, list, source] of text.matchAll(RE_EXPORT)) {
-            if (list === undefined || source === undefined || !source.startsWith("."))
-                continue;
-            for (const entry of list.split(",")) {
-                const [, kind, origin, exported] = ENTRY.exec(entry) ?? [];
-                if (origin !== undefined && kind === undefined && (exported ?? origin) === name && isBoundsExport(resolve(dirname(file), source), origin, depth + 1))
-                    return true;
-            }
-        }
-    }
-    return false;
-};
 /** The specifiers of an import or a re-export; the other inspected nodes have none. */
 const specifiersOf = (node) => node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" ? node.specifiers : undefined;
 /** An import of named values that all come from a generated input-bounds module is data, not an operation. */
@@ -192,9 +164,16 @@ const importsOnlyBounds = (context, node, value) => {
     const target = resolveImport(context, value);
     if (target === null)
         return false;
+    const hfs = hfsOf(context);
+    const owner = hfs.ownerOf(target);
+    const ownsGenerated = (file) => {
+        const found = hfs.classify(file);
+        return owner !== null && hfs.ownerOf(file) === owner && found.status === "owned" &&
+            (found.slot === "fe.transport.generated" || found.slot === "fe.package.api");
+    };
     return specifiers.every((s) => {
         const name = s.type === "ImportSpecifier" ? exportName(s.imported) : s.type === "ExportSpecifier" ? exportName(s.local) : undefined;
-        return name !== undefined && isBoundsExport(target, name);
+        return name !== undefined && isBoundsExport(ts, target, name, ownsGenerated);
     });
 };
 const unwrap = (start) => {

package/package.json

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

package/runtime/bundle.json

@@ -43,8 +43,8 @@
     "scripts/hfs/architecture/canon-jsx-clones.mjs",
     "scripts/hfs/architecture/client-reaches-server.mjs",
     "scripts/hfs/architecture/clones.mjs",
-    "scripts/hfs/architecture/config-unread.mjs",
     "scripts/hfs/architecture/component-tiers.mjs",
+    "scripts/hfs/architecture/config-unread.mjs",
     "scripts/hfs/architecture/config.mjs",
     "scripts/hfs/architecture/connection-map.mjs",
     "scripts/hfs/architecture/constructor-deps.mjs",
@@ -53,6 +53,7 @@
     "scripts/hfs/architecture/context-owner.mjs",
     "scripts/hfs/architecture/context-platform-tables.mjs",
     "scripts/hfs/architecture/context-transaction.mjs",
+    "scripts/hfs/architecture/contract-bounds.mjs",
     "scripts/hfs/architecture/contract-fixture-guard.mjs",
     "scripts/hfs/architecture/contracts-readonly.mjs",
     "scripts/hfs/architecture/contracts.mjs",

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.21.9
+    version: 0.21.11
     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.11.16
+    version: 3.11.18
     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.9.9
+    version: 9.9.11
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.21.9
+    version: 0.21.11
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.21.9
+    version: 0.21.11
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     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: 5.0.5
+    version: 5.0.7
     group: starci
     install: registry
     side: both

package/runtime/scripts/hfs/architecture/contract-bounds.mjs

@@ -0,0 +1,72 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/** The generated input-bounds owner is contract data, not an operation. */
+const BOUNDS_MODULE = /(?:^|\/)__generated__\/input-bounds\.ts$/;
+/** Directly exported declarations with the requested name; multiple declarations are ambiguous. */
+function declaredExports(ts, source, name) {
+    let count = 0;
+    for (const statement of source.statements) {
+        if (!ts.canHaveModifiers(statement) || !ts.getModifiers(statement)?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        if (ts.isVariableStatement(statement)) {
+            count += statement.declarationList.declarations.filter(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === name).length;
+        }
+        else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement) ||
+            ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) && statement.name?.text === name)
+            count += 1;
+    }
+    return count;
+}
+/** The concrete file a relative module specifier resolves to, in the same order as the rule's owner resolver. */
+function readSource(ts, target) {
+    for (const file of [`${target}.ts`, `${target}/index.ts`, target]) {
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+        if (source.parseDiagnostics.length)
+            return null;
+        return { file, source };
+    }
+    return null;
+}
+/** True only for an unambiguous named export proven through actual declarations to a generated contract declaration. */
+export function isBoundsExport(ts, target, name, ownsGenerated, seen = new Set()) {
+    const found = readSource(ts, target);
+    if (!found)
+        return false;
+    const { file, source } = found;
+    const key = `${file}#${name}`;
+    if (seen.has(key) || seen.size >= 32)
+        return false;
+    const direct = declaredExports(ts, source, name);
+    const matches = [];
+    let wildcard = false;
+    for (const statement of source.statements) {
+        if (!ts.isExportDeclaration(statement))
+            continue;
+        const module = statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
+        if (!statement.exportClause) {
+            wildcard = true;
+            continue;
+        }
+        if (!ts.isNamedExports(statement.exportClause))
+            continue;
+        for (const item of statement.exportClause.elements)
+            if (item.name.text === name) {
+                matches.push({ origin: (item.propertyName ?? item.name).text, module });
+            }
+    }
+    if (wildcard || direct + matches.length !== 1)
+        return false;
+    if (BOUNDS_MODULE.test(file.replaceAll('\\', '/')))
+        return ownsGenerated(file) && direct === 1 && matches.length === 0;
+    const match = matches[0];
+    if (direct || !match || !match.module?.startsWith('.'))
+        return false;
+    return isBoundsExport(ts, resolve(dirname(file), match.module), match.origin, ownsGenerated, new Set([...seen, key]));
+}

package/runtime/scripts/hfs/architecture/index.mjs

@@ -243,7 +243,7 @@ function runHfsMachine(config, context, paths, injectedTypeScript, base, fast, v
         return hfsChecks;
     const graph = buildHfsGraph(config, hfsContext);
     const input = { config, context: hfsContext, graph, base };
-    const runs = { tiers: () => checkTiers(graph), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
+    const runs = { tiers: () => checkTiers(graph, hfsContext.ts), reachability: () => checkReachability(input), deadExports: () => checkDeadExports(input),
         requiredFiles: () => checkRequiredFiles(input), clones: () => checkClones(input), symbols: () => checkSymbols(input), docLanguage: () => checkDocLanguage(input) };
     if (graph.profile === 'be')
         for (const [name, [check]] of Object.entries(BACKEND_MACHINE))

package/runtime/scripts/hfs/architecture/tiers.mjs

@@ -1,4 +1,6 @@
 import { byCodeUnit } from '../../lib/list.mjs';
+import { dirname, relative } from 'node:path';
+import { isBoundsExport } from './contract-bounds.mjs';
 import { registryListImport, registrySlot } from './entity-registry.mjs';
 /**
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
@@ -139,14 +141,53 @@ function reportReasonedTierViolation(graph, edge, answer, tierRule, counts, viol
         message,
     });
 }
-function inspectTierEdge(graph, edge, tierRule, counts, violations, coverage) {
+/** A public API entry may expose generated contract data without exposing operations to a hook. */
+function contractMetadataEdge(graph, ts, edge, verdict) {
+    if (graph.profile !== 'fe' || verdict.reason !== 'tierDirection')
+        return false;
+    const from = graph.files.get(edge.from);
+    const to = graph.files.get(edge.to);
+    if (from?.tier !== 'hooks' || to?.tier !== 'transport' || to.slot !== 'fe.modules.api' || !to.owner || to.owner.slot !== 'fe.modules' || to.owner.bindings.capability !== 'api')
+        return false;
+    // The tier verdict precedes private-entry checks, so prove both app isolation and the owner entry here.
+    const fromApp = graph.resolver.classifyPath(edge.from).bindings?.app;
+    const toApp = graph.resolver.classifyPath(edge.to).bindings?.app;
+    if (!fromApp || fromApp !== toApp || edge.to !== `${to.owner.root}/index.ts`)
+        return false;
+    const declaration = edge.edge.declaration;
+    let names;
+    if (ts.isImportDeclaration(declaration)) {
+        const clause = declaration.importClause;
+        if (!clause || clause.name || !clause.namedBindings || !ts.isNamedImports(clause.namedBindings))
+            return false;
+        names = clause.namedBindings.elements.map(item => (item.propertyName ?? item.name).text);
+    }
+    else if (ts.isExportDeclaration(declaration)) {
+        if (!declaration.exportClause || !ts.isNamedExports(declaration.exportClause))
+            return false;
+        names = declaration.exportClause.elements.map(item => (item.propertyName ?? item.name).text);
+    }
+    else
+        return false;
+    const apiOwner = to.owner;
+    const dirnameOfEntry = dirname(to.abs);
+    const ownsGenerated = (file) => {
+        const rel = `${apiOwner.root}/${relative(dirnameOfEntry, file).replaceAll('\\', '/')}`;
+        const classified = graph.resolver.classifyPath(rel);
+        const owner = graph.resolver.ownerOf(rel);
+        return classified.status === 'owned' && classified.slot === 'fe.transport.generated' &&
+            owner?.slot === apiOwner.slot && owner.root === apiOwner.root;
+    };
+    return names.length > 0 && names.every(name => isBoundsExport(ts, to.abs, name, ownsGenerated));
+}
+function inspectTierEdge(graph, ts, edge, tierRule, counts, violations, coverage) {
     const verdict = graph.resolver.importAllowed(edge.from, edge.to);
     if (verdict.reason === 'unowned' || verdict.reason?.startsWith('slot')) {
         coverage.unclassifiedEdges += 1;
         return;
     }
     coverage.edgesChecked += 1;
-    if (verdict.reason === 'tierDirection' && registryListImport(graph.resolver, edge))
+    if (verdict.reason === 'tierDirection' && (registryListImport(graph.resolver, edge) || contractMetadataEdge(graph, ts, edge, verdict)))
         return;
     reportReasonedTierViolation(graph, edge, verdict, tierRule, counts, violations);
 }
@@ -197,14 +238,14 @@ function addOwnerCycleViolations(adjacency, witness, violations) {
     }
     return components.length;
 }
-export function checkTiers(graph) {
+export function checkTiers(graph, ts) {
     const { resolver, profile } = graph;
     const violations = [];
     const tierRule = profile === 'be' ? 'BE_TIER_DIRECTION' : 'FE_TIER_DIRECTION';
     const coverage = { edgesChecked: 0, unclassifiedEdges: 0 };
     const counts = { tierDirection: 0, layerOrder: 0, crossApp: 0 };
     for (const edge of graph.edges)
-        inspectTierEdge(graph, edge, tierRule, counts, violations, coverage);
+        inspectTierEdge(graph, ts, edge, tierRule, counts, violations, coverage);
     // Owner cycles: nodes are owner units, edges the imports between two distinct units.
     const { adjacency, witness } = ownerAdjacency(graph, resolver);
     const cycles = addOwnerCycleViolations(adjacency, witness, violations);

package/runtime/scripts/hfs/repo-identity.mjs

@@ -5,10 +5,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { revParseQuery } from '../api/git/rev-parse-query.mjs';
 import { remote as gitRemote } from '../api/git/remote.mjs';
-import { gitOutputOf } from '../lib/git.mjs';
+import { gitOutputOf, withoutGitLocalEnv } from '../lib/git.mjs';
 import { trimTrailingSlashes } from './trailing-slashes.mjs';
 /** One git call (a scripts/api/git call file) in `root`: its trimmed stdout; throws unless git exits 0. */
-const git = (call, root, args) => gitOutputOf(call(args, { cwd: root })).trim(); // gitOutputOf threw unless git exited 0, whose stdout is text
+const git = (call, root, args, env) => gitOutputOf(call(args, { cwd: root, env: identityQueryEnvironment(env) })).trim(); // gitOutputOf threw unless git exited 0, whose stdout is text
+/** Identity queries need repository configuration, never age identities or selected service connection credentials. */
+export function identityQueryEnvironment(parent, privateNames = []) {
+    const selected = new Set(privateNames.map((name) => name.toUpperCase()));
+    return Object.fromEntries(Object.entries(withoutGitLocalEnv(parent)).filter(([name]) => !selected.has(name.toUpperCase()) && !/^(?:SOPS_AGE_KEY(?:_FILE)?|SONAR_.*)$/iu.test(name)));
+}
 const real = (p) => { try {
     return fs.realpathSync(p);
 }
@@ -26,20 +31,20 @@ catch {
     return null;
 } };
 /** { repositoryRoot, inWorkTree, home } for `root`: home is the main checkout folder when root is a repository top level. */
-function identityOf(root) {
+function identityOf(root, env = process.env) {
     const state = stateOf(root);
     if (state === null)
-        return askGit(root);
+        return askGit(root, env);
     if (!known.has(state))
-        known.set(state, askGit(root));
+        known.set(state, askGit(root, env));
     return known.get(state);
 }
-function askGit(root) {
+function askGit(root, env) {
     let inWorkTree = false, repositoryRoot = false, home = null;
     try {
         // Identity comes from Git only when root IS a repository (or worktree) top level, never a folder inside one.
         // One git call answers both questions: the top level on the first line, the common git dir on the second.
-        const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir']).split(String.fromCodePoint(10)).map((line) => line.trim());
+        const [top, commonDir] = git(revParseQuery, root, ['--show-toplevel', '--git-common-dir'], env).split(String.fromCodePoint(10)).map((line) => line.trim());
         repositoryRoot = real(top) === real(root);
         inWorkTree = true;
         const common = path.resolve(root, commonDir);
@@ -55,11 +60,11 @@ function askGit(root) {
  * name outside Git, else the folder name. A folder inside a larger repository (a nested product, an example) is named by
  * its own folder.
  */
-export function repositoryName(root) {
-    const { inWorkTree, repositoryRoot, home } = identityOf(root);
+export function repositoryName(root, { env = process.env } = {}) {
+    const { inWorkTree, repositoryRoot, home } = identityOf(root, env);
     if (repositoryRoot) {
         try {
-            const remote = trimTrailingSlashes(git(gitRemote, root, ['get-url', 'origin'])).replace(GIT_SUFFIX, '');
+            const remote = trimTrailingSlashes(git(gitRemote, root, ['get-url', 'origin'], env)).replace(GIT_SUFFIX, '');
             const name = remote.split(/[/:]/u).pop();
             if (name)
                 return name;