@starci/eslint-canon-fe 9.12.0 → 9.13.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 9.13.0 - 2026-11-03
+
+- Changed: `one-outcome-union` accepts in a root workspace package only the result union its `package.json` names (`starci.outcome: { name, file }`); every other result union stays refused. Specs: `src/packages-config.spec.ts`.
+- Changed: the runtime copies carry the root-packages view, the `modules` declaration and the canon pins of this release (no release-age wording).
+- Changed: the package's slot manifest places any root workspace package `packages/<name>/` in `app.packages` (a block library such as `packages/blocks-core` beside the agent SDK and the module packages), so the root packages config lints it.
+
+## 9.12.1 - 2026-11-03
+
+- Changed: the runtime copies carry the canon pins of `@starci/auth` 0.2.1, `@starci/auth-oidc` 0.1.1, the Grammar family 0.21.16 and `@starci/hfs` 5.4.0.
+
 ## 9.12.0 - 2026-11-03
 
 - Changed: the runtime copies carry R368's acceptance of the module-definition helpers, the module-per-transport confinement of the helpers and the `@starci/nest-kit` and `@starci/next-i18n` pins; `i18n-stack-in-one-module` refuses every product-source call of a next-intl layer builder (the stack is `@starci/next-i18n`'s).

package/dist/lib/hfs-view.d.ts

@@ -71,4 +71,16 @@ export interface HfsView {
     ownerOf(file: string): string | null;
     allows(file: string): HfsAllowance | null;
     slot(id: string): HfsSlot | null;
+    /** The vocabulary the root package of a file declares in the `starci` key of its manifest (the view of the root packages only), or null outside a package. */
+    readonly packageContract?: (file: string) => HfsPackageContract | null;
+}
+/** A type a root package declares: its name and the app-root relative file that declares it. */
+export interface HfsPackageDeclaredType {
+    readonly name: string;
+    readonly file: string;
+}
+/** The error base and the outcome union a root package declares for itself, since it cannot import the app's `platform/errors` or `GraphQLResponse<T>`. */
+export interface HfsPackageContract {
+    readonly errorBase?: HfsPackageDeclaredType;
+    readonly outcome?: HfsPackageDeclaredType;
 }

package/dist/lib/scope.d.ts

@@ -55,6 +55,11 @@ export declare const isApiLayer: (context: AnyContext) => boolean;
 export declare const isApiRest: (context: AnyContext) => boolean;
 /** The file that may declare the one result vocabulary (`GraphQLResponse`): the file of the slot the manifest marks `outcomeHome`. */
 export declare const isOutcomeModule: (context: AnyContext) => boolean;
+/**
+ * The one result union a root workspace package declares for itself (`starci.outcome` of its manifest: a package cannot import the app's
+ * `GraphQLResponse<T>`) when the linted file is its declared file, or null: only the alias of that name in that file is its outcome home.
+ */
+export declare const packageOutcomeOf: (context: AnyContext) => string | null;
 /** The basename of a path without directories. */
 export declare const baseName: (filename: string) => string;
 /** The file name with its extension removed. */

package/dist/lib/scope.js

@@ -77,6 +77,15 @@ export const isOutcomeModule = (context) => {
     const slot = slotOfFile(context);
     return slot !== null && hfs.slot(slot)?.outcomeHome === true;
 };
+/**
+ * The one result union a root workspace package declares for itself (`starci.outcome` of its manifest: a package cannot import the app's
+ * `GraphQLResponse<T>`) when the linted file is its declared file, or null: only the alias of that name in that file is its outcome home.
+ */
+export const packageOutcomeOf = (context) => {
+    const hfs = hfsOf(context);
+    const outcome = hfs.packageContract?.(context.filename)?.outcome;
+    return outcome !== undefined && hfs.relative(context.filename) === outcome.file ? outcome.name : null;
+};
 /** The basename of a path without directories. */
 export const baseName = (filename) => normalizePath(filename).split("/").pop() ?? "";
 /** The file name with its extension removed. */

package/dist/next-conventions.d.ts

@@ -12,7 +12,7 @@
  */
 import { type Recommended, type Rules } from "./lib/rule.js";
 /** Next 16 names the request interceptor `proxy.ts`; `middleware.ts` is forbidden. */
-export declare const noMiddlewareFile: import("./lib/rule.js").Rule<"export" | "file", []>;
+export declare const noMiddlewareFile: import("./lib/rule.js").Rule<"file" | "export", []>;
 /** The locale segment is `[locale]`. */
 export declare const localeSegmentIsLocale: import("./lib/rule.js").Rule<"segment", []>;
 /** Exactly one i18n stack: next-intl. */

package/dist/transport.d.ts

@@ -56,7 +56,9 @@ export declare const noHandTypedWire: import("./lib/rule.js").Rule<"document" |
 export declare const outcomeKindsExhaustive: import("./lib/rule.js").Rule<"missing", []>;
 /**
  * A result vocabulary is declared once per repository: `GraphQLResponse` in the file of the slot the manifest marks `outcomeHome`
- * (`fe.transport.outcome`: `modules/api/graphql/types.ts`, or `fe.package.api.outcome`: the api package's `src/graphql/types.ts`).
+ * (`fe.transport.outcome`: `modules/api/graphql/types.ts`, or `fe.package.api.outcome`: the api package's `src/graphql/types.ts`). A root
+ * workspace package, which cannot import it, declares its one union in its manifest (`starci.outcome`: `{ name, file }`): that alias, in
+ * that file, is its outcome home and every other result union of the package is refused.
  *
  * A union type alias is a result union when its members are object types that ALL carry the same literal-typed discriminant, in the
  * result vocabulary: `success` or `ok` (both `true` and `false` among the members) or `kind` (a member of kind `"ok"` beside at least one failure

package/dist/transport.js

@@ -23,7 +23,7 @@ import { isNode } from "./lib/ast.js";
 import { hfsOf } from "./lib/hfs.js";
 import { forbiddingConcern, packageNameOf } from "./lib/fe-stack.js";
 import { defineRule } from "./lib/rule.js";
-import { globalReferences, inSlot, isApiClient, isApiLayer, isApiRest, isOutcomeModule } from "./lib/scope.js";
+import { globalReferences, inSlot, isApiClient, isApiLayer, isApiRest, isOutcomeModule, packageOutcomeOf } from "./lib/scope.js";
 import { typed } from "./lib/types.js";
 /**
  * The canonical transport libraries and the one place each may be imported (fe-stack graphql, rest and realtime): Apollo in
@@ -811,7 +811,9 @@ const aliasDeclaration = (tsNode) => {
 };
 /**
  * A result vocabulary is declared once per repository: `GraphQLResponse` in the file of the slot the manifest marks `outcomeHome`
- * (`fe.transport.outcome`: `modules/api/graphql/types.ts`, or `fe.package.api.outcome`: the api package's `src/graphql/types.ts`).
+ * (`fe.transport.outcome`: `modules/api/graphql/types.ts`, or `fe.package.api.outcome`: the api package's `src/graphql/types.ts`). A root
+ * workspace package, which cannot import it, declares its one union in its manifest (`starci.outcome`: `{ name, file }`): that alias, in
+ * that file, is its outcome home and every other result union of the package is refused.
  *
  * A union type alias is a result union when its members are object types that ALL carry the same literal-typed discriminant, in the
  * result vocabulary: `success` or `ok` (both `true` and `false` among the members) or `kind` (a member of kind `"ok"` beside at least one failure
@@ -834,11 +836,12 @@ export const oneOutcomeUnion = defineRule({
     create(context) {
         if (isOutcomeModule(context))
             return {};
+        const declaredOutcome = packageOutcomeOf(context);
         const { checker, toTs } = typed(context);
         return {
             TSTypeAliasDeclaration(node) {
                 // typescript-eslint 6 and later produce no TSParenthesizedType node: a parenthesised type is its inner node.
-                if (node.typeAnnotation.type !== "TSUnionType")
+                if (node.typeAnnotation.type !== "TSUnionType" || node.id.name === declaredOutcome)
                     return;
                 const mapped = toTs(node);
                 if (!mapped)

package/docs/transport.md

@@ -171,7 +171,7 @@ switch (outcome.kind) {
 
 ## `starci-fe/one-outcome-union`
 
-A result union (`success` / `ok` / `kind` discriminant) is declared only in the outcome-home slot (`outcomeHome: true` in the slot manifest: `modules/api/graphql/types.ts`, or the api package's `src/graphql/types.ts`); elsewhere the code composes `GraphQLResponse<T>`.
+A result union (`success` / `ok` / `kind` discriminant) is declared only in the outcome-home slot (`outcomeHome: true` in the slot manifest: `modules/api/graphql/types.ts`, or the api package's `src/graphql/types.ts`); elsewhere the code composes `GraphQLResponse<T>`. A root workspace package, which cannot import it, names its one union in its `package.json` (`"starci": { "outcome": { "name": "AgentResult", "file": "src/workbench/outcome.ts" } }`): that alias, in that file, is its outcome home, and every other result union of the package is refused.
 
 A union type alias is a result union when its resolved members are all object types that carry the same literal-typed discriminant in the result vocabulary: `success` or `ok` (each member pins it to one value, `true` and `false` both present) or `kind` (at least one literal of the Outcome vocabulary: `ok`, `refused`, `forbidden`, `invalid`, `not-found`, `unavailable`). The members are read through the type checker, so `Ok<T> | Failure` and intersections are seen as what they are; no name (`*Outcome`, `*Result`) decides anything. UI state unions (`status`, `state`, `type`, a `kind` of tree nodes or menu items) are not result vocabulary and pass; so does an alias that only composes the one union (`type Read = Outcome<Course>`, `Exclude<Outcome<T>, ...>`). `Outcome<T> | { ok: false; kind: "conflict" }` adds an arm to the one union and is refused.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.12.0",
+  "version": "9.13.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

@@ -38,7 +38,7 @@ pins:
     source: packages/next-data/package.json
     why: 'the SWR data helpers of every front end (fe-stack data, owner:next-data-package): pollingRestart, the viewer and tenant key helpers, viewerSwrConfig and the viewer cache; each operation hook stays in the app and the package holds no component.'
   '@starci/grammar':
-    version: 0.21.15
+    version: 0.21.17
     group: starci
     install: registry
     side: fe
@@ -52,28 +52,28 @@ pins:
     source: packages/next-i18n/package.json
     why: 'the next-intl stack of every front end (fe-stack i18n, owner:next-i18n-package): defineI18n over the locales of the app, the locale-negotiating proxy, the locale-aware navigation, the request config that loads the catalogs of the app and the locale read of the [locale] layout; the app keeps its message catalogs and writes none of the stack.'
   '@starci/eslint-canon-be':
-    version: 3.14.0
+    version: 3.15.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.12.0
+    version: 9.13.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.21.15
+    version: 0.21.17
     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.15
+    version: 0.21.17
     group: starci
     install: registry
     side: fe
@@ -99,7 +99,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.6.2
+    version: 2.7.0
     group: starci
     install: registry
     side: be
@@ -127,14 +127,14 @@ pins:
     source: packages/nest-kit/package.json
     why: 'the module definition of every back-end module: defineConfigurableModule and defineCapabilityModule return the module base class, the options token and the options types with their types stated, so a <x>.module-definition.ts is one call that the lint on stated export types (R368) and the duplicate-code check (R21) both accept; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/auth':
-    version: 0.2.0
+    version: 0.3.0
     group: starci
     install: registry
     side: both
     source: packages/auth/package.json
     why: 'the lite sign-in: the NestJS module (EdDSA access tokens with a multi-key JWKS, passwords, Google OAuth with state and PKCE, rotating refresh sessions, the sign-in budget, the refresh cookie), the front-end client and its React bindings, the door contracts and test doubles; the one importer of the identity libraries, reached by a back end only through integrations/passport; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/auth-oidc':
-    version: 0.1.0
+    version: 0.1.2
     group: starci
     install: registry
     side: both
@@ -155,7 +155,7 @@ pins:
     source: packages/mail/package.json
     why: 'outgoing mail of a back end: a NestJS module and the Mailer port over SMTP (connect, greeting, socket and total timeouts, STARTTLS required by default, recipient, message and attachment checks, a shared SMTP target policy, coded errors, typed escaping render helpers returning { subject, text, html }), with @starci/mail/testing for its specs; the only importer of nodemailer (R90).'
   '@starci/hfs':
-    version: 5.3.0
+    version: 5.5.0
     group: starci
     install: registry
     side: both
@@ -592,7 +592,7 @@ pins:
     version: 3.1150.0
     group: framework
     side: be
-    why: 'the S3 transport inside @starci/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces), which depends on it at exactly this version and which no app file imports; 3.1150.0 is the release of 2026-10-12, chosen over newer ones that had not aged two weeks.'
+    why: 'the S3 transport inside @starci/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces), which depends on it at exactly this version and which no app file imports; 3.1150.0 is the release of 2026-10-12.'
   '@aws-sdk/s3-request-presigner':
     version: 3.1150.0
     group: framework
@@ -602,7 +602,7 @@ pins:
     version: 10.1.7
     group: framework
     side: be
-    why: 'the SMTP client inside @starci/mail, which depends on it at exactly this version and which no app file imports; 10.1.7 is the release of 2026-10-18, chosen over newer ones that had not aged two weeks.'
+    why: 'the SMTP client inside @starci/mail, which depends on it at exactly this version and which no app file imports; 10.1.7 is the release of 2026-10-18.'
   '@apollo/server':
     version: 5.5.1
     group: framework
@@ -652,7 +652,7 @@ pins:
     version: 6.29.0
     group: framework
     side: be
-    why: 'the Agent of platform/http (its one owner, R90): FetchHttpClient hands fetch a pool that trusts HttpOptions.trustedCa beside the bundled roots (a test world''s per-run fake CA); the 6 line is the undici the Node 22 runtime of the app images bundles, and its Agent also serves the fetch of Node 24; 6.29.0 is the release of 2026-09-25, chosen over newer ones that had not aged two weeks.'
+    why: 'the Agent of platform/http (its one owner, R90): FetchHttpClient hands fetch a pool that trusts HttpOptions.trustedCa beside the bundled roots (a test world''s per-run fake CA); the 6 line is the undici the Node 22 runtime of the app images bundles, and its Agent also serves the fetch of Node 24; 6.29.0 is the release of 2026-09-25.'
   # --- lite identity (integrations/passport, ruling lite-self-hosted-postgres-passport-minio)
   '@nestjs/passport':
     version: 11.0.5

package/runtime/knowledge/hfs/slots.yaml

@@ -859,10 +859,10 @@ slots:
   - id: app.packages
     since: 3.17.0
     profiles: [app]
-    editionWhy: Lite and full share the slot; a product's agent SDK and its agent modules are workspace packages in both.
-    # A workspace package of the app ROOT (packages/agent-sdk, packages/module-<name>): first-party source that both sides import through its
+    editionWhy: Lite and full share the slot; every root workspace package of a product (its agent SDK, a block library, a module package, a reviewed plugin package) is one in both.
+    # A workspace package of the app ROOT (packages/<name>: the agent SDK, a block library, packages/module-<name>): first-party source that both sides import through its
     # package entry points and never past them (ARCH_INTERNAL_IMPORT_OUTSIDE), linted by the root eslint config by subpath.
-    path: "packages/{agent-sdk,module-<name>}/"
+    path: "packages/<name>/"
     presence: optional
     tracked: tracked
     tier: none

package/runtime/scripts/hfs/architecture/root-packages.mjs

@@ -1,4 +1,4 @@
-// root-packages.mjs - the workspace packages of an app ROOT (packages/agent-sdk, packages/module-<name>, the managed packages/modules).
+// root-packages.mjs - the workspace packages of an app ROOT (packages/<name>: the agent SDK, a block library, a module package, the managed packages/modules).
 // They lie outside both side folders and belong to no side; both sides import them by package name, through their package entry points
 // (the `exports` of the manifest), so the import graph reads them as first-party packages and the back-end canon never reads them as
 // a third-party library. The app root's one package.json lists them in `workspaces`; the patterns that start with a side folder

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

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

package/runtime/scripts/hfs/slots.mjs

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

package/runtime/scripts/hfs/view.mjs

@@ -2,6 +2,7 @@
 // their rules (`settings.starci.hfs`). Both @starci/eslint-canon-be and @starci/eslint-canon-fe ship a byte copy of this file in their
 // runtime/ bundle (scripts/hfs/sync-runtime.mjs), so a path-scoped rule in either package asks the SAME resolver the
 // architecture machine and `starci app check` use, and never tests a path with a regular expression of its own.
+import fs from 'node:fs';
 import path from 'node:path';
 import { allowsFile } from './allows.mjs';
 import { openHfs } from './slots.mjs';
@@ -70,6 +71,36 @@ export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root
  * @returns {object} The frozen view.
  */
 export const declaredHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => hfsView(openHfs({ root: runtimeRoot, declaration, side }), repoRoot);
+const CONTRACT_KEYS = ['errorBase', 'outcome'];
+/**
+ * The contract of the package at `packageDir` (app-root relative, `packages/<pkg>`), read from the `starci` key of its manifest. A
+ * declaration that is not `{ name, file }` with an identifier name and a file inside `src/` stops the lint, because a rule must not guess.
+ *
+ * @param {string} repoRoot - The absolute app root.
+ * @param {string} packageDir - The package folder, relative to the app root.
+ * @returns {object} The declared error base and outcome union, each with its file relative to the app root.
+ */
+export const readPackageContract = (repoRoot, packageDir) => {
+    const manifestPath = path.join(repoRoot, packageDir, 'package.json');
+    const manifest = (fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : null);
+    const declared = manifest?.starci;
+    if (declared === undefined)
+        return {};
+    if (typeof declared !== 'object' || declared === null)
+        throw new Error(`${packageDir}/package.json: "starci" is an object ({ errorBase, outcome })`);
+    const contract = {};
+    for (const key of CONTRACT_KEYS) {
+        const entry = declared[key];
+        if (entry === undefined)
+            continue;
+        const { name, file } = (typeof entry === 'object' && entry !== null ? entry : {});
+        if (typeof name !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(name) || typeof file !== 'string' || !/^src\/(?:[\w.-]+\/)*[\w.-]+\.ts$/.test(file)) {
+            throw new Error(`${packageDir}/package.json: "starci.${key}" is { "name": "<Identifier>", "file": "src/<path>.ts" }`);
+        }
+        contract[key] = Object.freeze({ name, file: `${packageDir}/${file}` });
+    }
+    return Object.freeze(contract);
+};
 /**
  * The view of the root workspace packages of an app (`packages/<pkg>/src/**`, slots app.packages and app.module-registry), as the lint of one
  * side sees them: the rule parameters, the apps and the Grammar of `side` (a package is judged by the laws of the side whose subpath a file
@@ -103,6 +134,15 @@ function packagesView(opened, repoRoot, side) {
         const relative = rel(file);
         return slot !== undefined && ROOT_PACKAGE_SLOTS.has(slot) ? relative.split('/').slice(0, 2).join('/') : null;
     };
+    const contracts = new Map();
+    const packageContract = (file) => {
+        const dir = packageOf(file);
+        if (dir === null)
+            return null;
+        if (!contracts.has(dir))
+            contracts.set(dir, readPackageContract(repoRoot, dir));
+        return contracts.get(dir);
+    };
     return Object.freeze({
         repoRoot,
         profile: side,
@@ -121,6 +161,7 @@ function packagesView(opened, repoRoot, side) {
         ownerOf: () => null,
         allows: (file) => allowsFile(opened, rel(file)),
         slot: (id) => opened.slot(id),
+        packageContract,
     });
 }
 /**