@starci/eslint-canon-be 3.14.1 → 3.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.15.0 - 2026-11-03
4
+
5
+ - Changed: `throw-domain-error` and `error-home` judge a root workspace package by the error base its `package.json` declares (`starci.errorBase: { name, file }`), the way they judge an app by `DomainError` of `platform/errors`; a raw `Error` and an undeclared `Error` subclass stay refused, and a malformed declaration stops the lint. Specs: `src/packages-config.spec.ts`.
6
+ - Changed: the runtime copies carry the root-packages view (`readPackageContract`, the `modules` declaration), the R187 build-context law, the seed rules (R375, R332) and the canon pins of this release.
7
+ - 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.
8
+
3
9
  ## 3.14.1 - 2026-11-03
4
10
 
5
11
  - 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.
package/README.md CHANGED
@@ -37,7 +37,7 @@ A sample, not the list:
37
37
 
38
38
  | Area | What the rules hold |
39
39
  |---|---|
40
- | **Errors** | A `catch` rethrows, calls a method on a `Logger` receiver (typed, from `platform/logging`) or returns an outcome carrying its cause; a `DomainError` subclass lives only in `errors/<capability>.error.ts` of its owner, and that file is one code enum, one `Record<Code, ErrorKind>` table and one empty class; a `throw` throws a `DomainError`, never a bare `Error`, a framework exception or a platform error out of a domain (`catch-must-account`, `error-home`, `throw-domain-error`, `error-family-shape`) |
40
+ | **Errors** | A `catch` rethrows, calls a method on a `Logger` receiver (typed, from `platform/logging`) or returns an outcome carrying its cause; a `DomainError` subclass lives only in `errors/<capability>.error.ts` of its owner, and that file is one code enum, one `Record<Code, ErrorKind>` table and one empty class; a `throw` throws a `DomainError`, never a bare `Error`, a framework exception or a platform error out of a domain; a root workspace package throws the error base its `package.json` declares (`starci.errorBase`) (`catch-must-account`, `error-home`, `throw-domain-error`, `error-family-shape`) |
41
41
  | **Schema authority** | Migrations only: every DataSource or TypeORM options object states the literal `synchronize: false` (found by the contextual type), no `migrationsRun`, no DDL string outside a migration, no entity glob; no `@Entity` type reachable from a transport signature, a handler `execute`, a contract or a message, and no GraphQL or validator import in an entity file (`no-runtime-schema`, `no-entity-in-contract`) |
42
42
  | **Config and secrets** | `process.env` (any form) is allowed in the `platform/config` file declaring `EnvSource`, the test world (slot `be.tests.world`) and the app bootstrap roles `apps/<app>/src/main.ts` and its matching `<app>.env.ts`; only those two app roles may read `EnvSource` or capability parse helpers. Compose groups and `<app>.options.ts` never read `process.env` or `EnvSource`. `@nestjs/config` and `dotenv` are forbidden config paths. A function exported by a `<capability>.config.ts` keeps its existing name and is called only from these bootstrap roles, its own config file or spec, the test world and a provider contract spec (`config-parsed-in-main`). Secrets use `EnvSource.secret()`: `<NAME>_FILE` takes priority for `.starcistacks` custody, and plain `<NAME>` is read only when the file key is absent; a declared file supplies exact contents and an empty or unreadable path fails startup without fallback. No default of any kind for a value typed `Secret` or `Url`; secrets compare with `timingSafeEqual` (`no-direct-env-read`, `config-parsed-in-main`, `no-secret-default`, `secret-compare-timing-safe`) |
43
43
  | **Model calls** (R326, R327, R344) | Every model call goes through the `@starci/ai-router` gateway: an upstream provider key variable (`PROVIDER_KEY_VARIABLES` of `src/ai-gateway.ts`, with its `_FILE` twin) is named only in the gateway's custody owner `integrations/ai-gateway`, specs and the test world included; code builds only `ChatOpenAI` and `OpenAIEmbeddings` of `@langchain/openai`, each from an inline options object whose `configuration.baseURL` is read from a `<c>.options.ts` type and whose `apiKey` is a `platform/config` `Secret` revealed; `integrations/ai` reads exactly `STARCI_AI_KEY`, the one virtual key of every client, and the custody owner passes the gateway no `adminToken`. Which owner may import LangChain, `openai`, a provider SDK or an agent framework is the infrastructure table (`provider-key-custody`, `ai-client-through-gateway`, `ai-virtual-key-name`, `infra-import-owner`) |
@@ -16,12 +16,16 @@
16
16
  * (`AbstractException`, a framework `HttpException` subclass, a bare `extends Error`) is refused.
17
17
  * - `throw-domain-error` refuses a `throw` whose type does not derive from `DomainError` (`throw new Error`, the Nest
18
18
  * `HttpException` family, a thrown string or object), and a domain owner that throws a platform error outward.
19
+ *
20
+ * The error base of a file is `DomainError` of `platform/errors`; a root workspace package, which cannot import an app owner, declares
21
+ * its own base in its manifest (`starci.errorBase`: `{ name, file }`), and both rules read that class, in that file, as its `DomainError`:
22
+ * the base itself is its host and a package has no owner layout to place its subclasses in.
19
23
  * - `error-family-shape` holds the one shape of `errors/<c>.error.ts`: a `<C>ErrorCode` string enum, a
20
24
  * `<C>_ERROR_KINDS: Record<<C>ErrorCode, ErrorKind>` table, and an empty `<C>Error extends DomainError<<C>ErrorCode>`.
21
25
  * Code uniqueness across the repository is the architecture machine's job, not a single file's.
22
26
  */
23
27
  import { nameOrValue, some, walk } from "./lib/ast.js";
24
- import { derives, derivesFromBuiltinError, derivesFromDomainError, errorHomeOf, isOwnedBy, isOwnedType, ownerName, partsOf, typeOf, } from "./lib/declared.js";
28
+ import { derives, derivesFromBuiltinError, derivesFromErrorBase, errorHomeOf, isOwnedBy, isOwnedType, ownerName, packageErrorBaseOf, partsOf, typeOf, } from "./lib/declared.js";
25
29
  import { hfsOf } from "./lib/hfs.js";
26
30
  import { normalizePath } from "./lib/path.js";
27
31
  import { typed } from "./lib/types.js";
@@ -241,7 +245,7 @@ export const errorHome = {
241
245
  schema: [],
242
246
  messages: {
243
247
  place: "`{{name}}` derives from `DomainError` but is not declared in `errors/{{owner}}.error.ts` of its owner. An owner has one error class, in that file; move it there.",
244
- mustExtendDomainError: "`{{name}}` derives from the built-in `Error` without deriving from `DomainError` (`AbstractException`, a framework exception or a bare `extends Error`). Extend `DomainError` from `platform/errors` in the owner's `errors/<capability>.error.ts`.",
248
+ mustExtendDomainError: "`{{name}}` derives from the built-in `Error` without deriving from `DomainError` (`AbstractException`, a framework exception or a bare `extends Error`). Extend `DomainError` from `platform/errors` in the owner's `errors/<capability>.error.ts`; in a root workspace package, extend the error base its `package.json` declares (`starci.errorBase`).",
245
249
  },
246
250
  },
247
251
  create(context) {
@@ -253,11 +257,13 @@ export const errorHome = {
253
257
  const type = typeOf(context, node.id);
254
258
  if (!type)
255
259
  return;
256
- const isDomainErrorHost = node.id.name === "DomainError" && isOwnedBy(hfs, filename, "platform", "errors");
257
- if (isDomainErrorHost)
260
+ const packageBase = packageErrorBaseOf(hfs, filename);
261
+ const isErrorBaseHost = (node.id.name === "DomainError" && isOwnedBy(hfs, filename, "platform", "errors")) ||
262
+ (packageBase !== null && node.id.name === packageBase.name && hfs.relative(filename) === packageBase.file);
263
+ if (isErrorBaseHost)
258
264
  return;
259
- if (derivesFromDomainError(context, type)) {
260
- if (isWorldErrorHome(hfs, filename))
265
+ if (derivesFromErrorBase(context, type)) {
266
+ if (packageBase !== null || isWorldErrorHome(hfs, filename))
261
267
  return;
262
268
  // A spec-local subclass of the abstract base is a test double for code that takes any DomainError, not an error family.
263
269
  if (isSpecLocalClass(filename, node))
@@ -308,7 +314,7 @@ export const throwDomainError = {
308
314
  messages: {
309
315
  bareError: "`throw new Error(...)` carries a sentence and no code, so nothing downstream can group or map it. Throw the `<C>Error` of the owning capability with one of its codes.",
310
316
  framework: "`throw new {{name}}(...)` carries an HTTP status and no identity. Throw the `<C>Error` of the owning capability; the one filter of `platform/errors` maps its code to a status.",
311
- notDomainError: "This `throw` does not throw a `DomainError`. Throw the `<C>Error` of the owning capability with one of its codes, or return an `Outcome` and let the transport unwrap it.",
317
+ notDomainError: "This `throw` does not throw a `DomainError`. Throw the `<C>Error` of the owning capability with one of its codes, or return an `Outcome` and let the transport unwrap it; a root workspace package throws the error base its `package.json` declares (`starci.errorBase`).",
312
318
  platformThrown: "A domain owner throws `{{name}}`, an error of a platform owner. Translate it into the error of this capability so platform details do not cross the boundary.",
313
319
  },
314
320
  },
@@ -326,7 +332,7 @@ export const throwDomainError = {
326
332
  return;
327
333
  const type = typeOf(context, thrown);
328
334
  const parts = partsOf(type);
329
- const foreign = parts.find((part) => !derivesFromDomainError(context, part));
335
+ const foreign = parts.find((part) => !derivesFromErrorBase(context, part));
330
336
  if (parts.length === 0 || foreign) {
331
337
  if (foreign && isHttpException(foreign)) {
332
338
  context.report({ node: thrown, messageId: "framework", data: { name: foreign.getSymbol()?.name ?? "HttpException" } });
@@ -6,7 +6,7 @@
6
6
  import ts from "typescript";
7
7
  import type { TSESTree } from "@typescript-eslint/utils";
8
8
  import type { Context, Node } from "./rule.js";
9
- import type { HfsView } from "./hfs.js";
9
+ import type { HfsPackageDeclaredType, HfsView } from "./hfs.js";
10
10
  import type { TypeOrigin } from "./types.js";
11
11
  /** The last segment of an owner root (`src/modules/platform/errors` gives `errors`), or null when there is no owner. */
12
12
  export declare const ownerName: (root: string | null | undefined) => string | null | undefined;
@@ -60,8 +60,13 @@ export declare const presentParts: (type: ts.Type | null | undefined) => ts.Type
60
60
  */
61
61
  export declare const derives: (checker: ts.TypeChecker, type: ts.Type | null | undefined, test: (name: string, file: string) => boolean, depth?: number) => boolean;
62
62
  export declare const derivesFromBuiltinError: (context: Context, type: ts.Type | null | undefined) => boolean;
63
- /** True when the type is (or extends) `DomainError` as declared by the repository's `platform/errors` owner. */
64
- export declare const derivesFromDomainError: (context: Context, type: ts.Type | null | undefined) => boolean;
63
+ /** The error base a root package declares for the linted file (`starci.errorBase` of its manifest), or null outside a package or without one. */
64
+ export declare const packageErrorBaseOf: (hfs: HfsView, filename: string) => HfsPackageDeclaredType | null;
65
+ /**
66
+ * True when the type is (or extends) the error base of the linted file: `DomainError` as declared by the repository's `platform/errors`
67
+ * owner, or, in a root workspace package (which cannot import `platform/errors`), the error base its manifest declares, in its declared file.
68
+ */
69
+ export declare const derivesFromErrorBase: (context: Context, type: ts.Type | null | undefined) => boolean;
65
70
  /**
66
71
  * The owner-relative `errors/<capability>.error.ts` home of an error family, or null for a file that is not one.
67
72
  *
@@ -5,6 +5,7 @@
5
5
  */
6
6
  import ts from "typescript";
7
7
  import { hfsOf } from "./hfs.js";
8
+ import { normalizePath } from "./path.js";
8
9
  import { typeOrigins, typed } from "./types.js";
9
10
  /** The last segment of an owner root (`src/modules/platform/errors` gives `errors`), or null when there is no owner. */
10
11
  export const ownerName = (root) => (root ? root.split("/").at(-1) : null);
@@ -119,11 +120,17 @@ export const derivesFromBuiltinError = (context, type) => {
119
120
  return source ? program.isSourceFileDefaultLibrary(source) : false;
120
121
  });
121
122
  };
122
- /** True when the type is (or extends) `DomainError` as declared by the repository's `platform/errors` owner. */
123
- export const derivesFromDomainError = (context, type) => {
123
+ /** The error base a root package declares for the linted file (`starci.errorBase` of its manifest), or null outside a package or without one. */
124
+ export const packageErrorBaseOf = (hfs, filename) => hfs.packageContract?.(filename)?.errorBase ?? null;
125
+ /**
126
+ * True when the type is (or extends) the error base of the linted file: `DomainError` as declared by the repository's `platform/errors`
127
+ * owner, or, in a root workspace package (which cannot import `platform/errors`), the error base its manifest declares, in its declared file.
128
+ */
129
+ export const derivesFromErrorBase = (context, type) => {
124
130
  const hfs = hfsOf(context);
125
131
  const { checker } = typed(context);
126
- return derives(checker, type, (name, file) => name === "DomainError" && isOwnedBy(hfs, file, "platform", "errors"));
132
+ const own = packageErrorBaseOf(hfs, normalizePath(context.filename));
133
+ return derives(checker, type, (name, file) => (name === "DomainError" && isOwnedBy(hfs, file, "platform", "errors")) || (own !== null && name === own.name && hfs.relative(file) === own.file));
127
134
  };
128
135
  /**
129
136
  * The owner-relative `errors/<capability>.error.ts` home of an error family, or null for a file that is not one.
@@ -140,4 +140,16 @@ export interface HfsView {
140
140
  allows(file: string): HfsAllowsVerdict | null;
141
141
  /** A slot definition by id. */
142
142
  slot(id: string): HfsSlot | undefined;
143
+ /** 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. */
144
+ readonly packageContract?: (file: string) => HfsPackageContract | null;
145
+ }
146
+ /** A type a root package declares: its name and the app-root relative file that declares it. */
147
+ export interface HfsPackageDeclaredType {
148
+ readonly name: string;
149
+ readonly file: string;
150
+ }
151
+ /** 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>`. */
152
+ export interface HfsPackageContract {
153
+ readonly errorBase?: HfsPackageDeclaredType;
154
+ readonly outcome?: HfsPackageDeclaredType;
143
155
  }
package/dist/lib/hfs.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import type { HfsView } from "./hfs-view.js";
2
2
  import type { Context } from "./rule.js";
3
- export type { HfsAllowsVerdict, HfsApp, HfsClassification, HfsConnection, HfsParamName, HfsRuleParams, HfsSlot, HfsSpecDouble, HfsUnitRole, HfsView, } from "./hfs-view.js";
3
+ export type { HfsAllowsVerdict, HfsApp, HfsClassification, HfsConnection, HfsPackageContract, HfsPackageDeclaredType, HfsParamName, HfsRuleParams, HfsSlot, HfsSpecDouble, HfsUnitRole, HfsView, } from "./hfs-view.js";
4
4
  /**
5
5
  * The HFS view of the side whose `eslint.config.mjs` (in be/) calls this.
6
6
  *
@@ -77,7 +77,7 @@ const dependenciesOf = (hfs) => {
77
77
  throw new Error("third-party-import-owner needs the app-root package.json beside be/ to derive SDK ownership");
78
78
  const declaration = JSON.parse(readFileSync(manifest, "utf8"));
79
79
  const dependencies = new Map();
80
- // The app's own workspace packages (packages/agent-sdk, packages/module-<name>) are first-party source, not third-party libraries: whatever
80
+ // The app's own workspace packages (packages/<name>: the agent SDK, a block library, a module package) are first-party source, not third-party libraries: whatever
81
81
  // version range the root manifest writes for one of them, it names no SDK to own. What such a package imports is judged in the package.
82
82
  const own = rootPackageNames(dirname(manifest));
83
83
  for (const section of ["dependencies", "optionalDependencies", "peerDependencies", "devDependencies"]) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.14.1",
3
+ "version": "3.15.0",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -38,7 +38,7 @@ pins:
38
38
  source: packages/next-data/package.json
39
39
  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.'
40
40
  '@starci/grammar':
41
- version: 0.21.16
41
+ version: 0.21.17
42
42
  group: starci
43
43
  install: registry
44
44
  side: fe
@@ -52,28 +52,28 @@ pins:
52
52
  source: packages/next-i18n/package.json
53
53
  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.'
54
54
  '@starci/eslint-canon-be':
55
- version: 3.14.1
55
+ version: 3.15.0
56
56
  group: starci
57
57
  install: registry
58
58
  side: be
59
59
  source: packages/eslint-canon-be/package.json
60
60
  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.'
61
61
  '@starci/eslint-canon-fe':
62
- version: 9.12.1
62
+ version: 9.13.0
63
63
  group: starci
64
64
  install: registry
65
65
  side: fe
66
66
  source: packages/eslint-canon-fe/package.json
67
67
  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.'
68
68
  '@starci/eslint-grammar-core':
69
- version: 0.21.16
69
+ version: 0.21.17
70
70
  group: starci
71
71
  install: registry
72
72
  side: fe
73
73
  source: packages/eslint-grammar-core/package.json
74
74
  why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
75
75
  '@starci/eslint-grammar-offset-pop':
76
- version: 0.21.16
76
+ version: 0.21.17
77
77
  group: starci
78
78
  install: registry
79
79
  side: fe
@@ -99,7 +99,7 @@ pins:
99
99
  side: both
100
100
  source: packages/prettier-config/package.json
101
101
  '@starci/jest-preset':
102
- version: 2.6.2
102
+ version: 2.7.0
103
103
  group: starci
104
104
  install: registry
105
105
  side: be
@@ -127,14 +127,14 @@ pins:
127
127
  source: packages/nest-kit/package.json
128
128
  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.'
129
129
  '@starci/auth':
130
- version: 0.2.1
130
+ version: 0.3.0
131
131
  group: starci
132
132
  install: registry
133
133
  side: both
134
134
  source: packages/auth/package.json
135
135
  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.'
136
136
  '@starci/auth-oidc':
137
- version: 0.1.1
137
+ version: 0.1.2
138
138
  group: starci
139
139
  install: registry
140
140
  side: both
@@ -155,7 +155,7 @@ pins:
155
155
  source: packages/mail/package.json
156
156
  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).'
157
157
  '@starci/hfs':
158
- version: 5.4.0
158
+ version: 5.5.0
159
159
  group: starci
160
160
  install: registry
161
161
  side: both
@@ -592,7 +592,7 @@ pins:
592
592
  version: 3.1150.0
593
593
  group: framework
594
594
  side: be
595
- 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.'
595
+ 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.'
596
596
  '@aws-sdk/s3-request-presigner':
597
597
  version: 3.1150.0
598
598
  group: framework
@@ -602,7 +602,7 @@ pins:
602
602
  version: 10.1.7
603
603
  group: framework
604
604
  side: be
605
- 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.'
605
+ 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.'
606
606
  '@apollo/server':
607
607
  version: 5.5.1
608
608
  group: framework
@@ -652,7 +652,7 @@ pins:
652
652
  version: 6.29.0
653
653
  group: framework
654
654
  side: be
655
- 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.'
655
+ 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.'
656
656
  # --- lite identity (integrations/passport, ruling lite-self-hosted-postgres-passport-minio)
657
657
  '@nestjs/passport':
658
658
  version: 11.0.5
@@ -3299,7 +3299,7 @@ rules:
3299
3299
  code: "HFS_DOCKER_BUILD_CONTEXT"
3300
3300
  editions: [lite, full]
3301
3301
  docs: [docs/application-stacks.md#r187]
3302
- law: "Every app image is built from the app root: the header comment of an app's Dockerfile states `starci docker build <app>` for its own path, and no COPY or ADD source leaves the build context (a `..` segment or an absolute path)."
3302
+ law: "Every app image is built from the app root: the header comment of an app's Dockerfile states `starci docker build <app>` for its own path, no COPY or ADD source leaves the build context (a `..` segment or an absolute path), and the image of a Next app whose front end reads be/contracts/ copies that folder exactly when the app holds it (a COPY of a missing folder fails the build, a missing COPY leaves the codegen without its contract)."
3303
3303
  kinds: [check]
3304
3304
  gates: [settle, land, ci]
3305
3305
  failureCodes: ["HFS_DOCKER_BUILD_CONTEXT"]
@@ -5791,7 +5791,7 @@ rules:
5791
5791
  ruling: "Lite storage is the MinIO already running on the Tay Son host, reached through the one S3 integration."
5792
5792
  - id: R332
5793
5793
  code: "LITE_DB_MIGRATION"
5794
- law: "A lite app's schema lives only in db/: every schema change is one db/migrations/<ts14>_<kebab>.sql (archive db/migrations/archive/, seed db/seed.sql), and the tree holds no supabase/ folder and no SQL file outside db/ but a .starcistacks seed."
5794
+ law: "A lite app's schema lives only in db/: every schema change is one db/migrations/<ts14>_<kebab>.sql (archive db/migrations/archive/, the managed db/bootstrap.sql), every other SQL file under db/ is refused, and the tree holds no supabase/ folder and no SQL file outside db/ but the sql/ entries of its seed levels (R375)."
5795
5795
  kinds: [check]
5796
5796
  gates: [settle, land, ci]
5797
5797
  failureCodes: ["LITE_DB_MIGRATION"]
@@ -6628,3 +6628,16 @@ rules:
6628
6628
  - {path: contexts/project/stacks.md#project-stacks-11-a-customised-service-is-an-image-the-app-builds-the-same-in-every-environment, editions: [lite, full]}
6629
6629
  proves:
6630
6630
  - {path: packages/hfs/src/stacks-service-images.spec.mjs, editions: [lite, full]}
6631
+ - id: R375
6632
+ code: "HFS_SEEDS_SHAPE"
6633
+ law: "Seed data lives only in the seed levels of `.starcistacks/`, where `seeds/` is applied in every environment first and `<env>/seeds/` in the one environment the stack declaration names `<env>`; each level is a `seeds.yaml` manifest (schema starci/seeds@1) whose entries list every file of its `sql/`, `data/` and `files/` folders; a seed is never a migration (no statement that creates, alters, drops, truncates, grants, revokes or comments on an object), never custody, a data document validates against the schema its entry names, a level a production environment applies holds no test data but the one test account an environment declares (a test-account entry with its reason), and a document names a secret only as a reference to a sealed seeds-<name> member of its environment."
6634
+ kinds: [check]
6635
+ gates: [settle, land, ci]
6636
+ failureCodes: ["HFS_SEEDS_SHAPE", "HFS_SEED_MANIFEST", "HFS_SEED_DDL", "HFS_SEED_DATA_SCHEMA", "HFS_SEED_TEST_DATA", "HFS_SEED_SECRET_REF"]
6637
+ enforcers:
6638
+ - {kind: hfs, id: seeds-shape, at: scripts/hfs/rules/seeds.mjs}
6639
+ editions: [lite, full]
6640
+ docs:
6641
+ - {path: contexts/project/stacks.md#project-stacks-12-seed-data-lives-in-the-seed-levels-of-the-stack, editions: [lite, full]}
6642
+ proves:
6643
+ - {path: packages/hfs/src/hfs-seeds-shape.spec.mjs, editions: [lite, full]}
@@ -859,10 +859,10 @@ slots:
859
859
  - id: app.packages
860
860
  since: 3.17.0
861
861
  profiles: [app]
862
- editionWhy: Lite and full share the slot; a product's agent SDK and its agent modules are workspace packages in both.
863
- # A workspace package of the app ROOT (packages/agent-sdk, packages/module-<name>): first-party source that both sides import through its
862
+ 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.
863
+ # 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
864
864
  # package entry points and never past them (ARCH_INTERNAL_IMPORT_OUTSIDE), linted by the root eslint config by subpath.
865
- path: "packages/{agent-sdk,module-<name>}/"
865
+ path: "packages/<name>/"
866
866
  presence: optional
867
867
  tracked: tracked
868
868
  tier: none
@@ -1,4 +1,4 @@
1
- // root-packages.mjs - the workspace packages of an app ROOT (packages/agent-sdk, packages/module-<name>, the managed packages/modules).
1
+ // 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).
2
2
  // They lie outside both side folders and belong to no side; both sides import them by package name, through their package entry points
3
3
  // (the `exports` of the manifest), so the import graph reads them as first-party packages and the back-end canon never reads them as
4
4
  // a third-party library. The app root's one package.json lists them in `workspaces`; the patterns that start with a side folder
@@ -140,7 +140,7 @@ function observeBlockProblems(observe) {
140
140
  bad.push('observe.reporter must name the optional error reporter');
141
141
  return bad;
142
142
  }
143
- const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'lexicon', 'observe']);
143
+ const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'modules', 'lexicon', 'observe']);
144
144
  const RUNTIME_DECLARATION_KEYS = new Set(['hfs', 'kind', 'project']);
145
145
  function productDeclarationProblems(declaration, profiles) {
146
146
  const bad = [];
@@ -150,6 +150,8 @@ function productDeclarationProblems(declaration, profiles) {
150
150
  bad.push(...dbBlockProblems(declaration.db), ...lexiconBlockProblems(declaration.lexicon), ...observeBlockProblems(declaration.observe));
151
151
  if (declaration.browser !== undefined && declaration.browser !== true)
152
152
  bad.push('browser is `true` when the app has a browser journey (slot app.browser), and is left out otherwise');
153
+ if (declaration.modules !== undefined && declaration.modules !== 'data')
154
+ bad.push('modules is `"data"` when the app keeps its modules as data (seeds, no rendered registry package), and is left out otherwise');
153
155
  if (declaration.kind !== APP_KIND)
154
156
  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)`);
155
157
  if (!isPlainObject(declaration.sides) || Object.keys(declaration.sides).sort(byCodeUnit).join() !== profiles.join()) {
@@ -177,6 +177,7 @@ export function resolveRepoDeclaration(manifest, declaration, { file = HFS_DECLA
177
177
  // tsconfig.json that type-checks it, both switched on by `browser: true`.
178
178
  apps: Object.freeze([]),
179
179
  optionalSlots: Object.freeze(declaration.browser === true ? ['app.browser', 'app.browser-config'] : []),
180
+ modules: declaration.modules === 'data' ? 'data' : 'packages',
180
181
  connections: Object.freeze([]),
181
182
  providers,
182
183
  reads: Object.freeze([]),
@@ -2,6 +2,7 @@
2
2
  // their rules (`settings.starci.hfs`). Both @starci/eslint-canon-be and @starci/eslint-canon-fe ship a byte copy of this file in their
3
3
  // runtime/ bundle (scripts/hfs/sync-runtime.mjs), so a path-scoped rule in either package asks the SAME resolver the
4
4
  // architecture machine and `starci app check` use, and never tests a path with a regular expression of its own.
5
+ import fs from 'node:fs';
5
6
  import path from 'node:path';
6
7
  import { allowsFile } from './allows.mjs';
7
8
  import { openHfs } from './slots.mjs';
@@ -70,6 +71,36 @@ export const openHfsView = ({ runtimeRoot, repoRoot }) => hfsView(openHfs({ root
70
71
  * @returns {object} The frozen view.
71
72
  */
72
73
  export const declaredHfsView = ({ runtimeRoot, declaration, repoRoot, side }) => hfsView(openHfs({ root: runtimeRoot, declaration, side }), repoRoot);
74
+ const CONTRACT_KEYS = ['errorBase', 'outcome'];
75
+ /**
76
+ * The contract of the package at `packageDir` (app-root relative, `packages/<pkg>`), read from the `starci` key of its manifest. A
77
+ * declaration that is not `{ name, file }` with an identifier name and a file inside `src/` stops the lint, because a rule must not guess.
78
+ *
79
+ * @param {string} repoRoot - The absolute app root.
80
+ * @param {string} packageDir - The package folder, relative to the app root.
81
+ * @returns {object} The declared error base and outcome union, each with its file relative to the app root.
82
+ */
83
+ export const readPackageContract = (repoRoot, packageDir) => {
84
+ const manifestPath = path.join(repoRoot, packageDir, 'package.json');
85
+ const manifest = (fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : null);
86
+ const declared = manifest?.starci;
87
+ if (declared === undefined)
88
+ return {};
89
+ if (typeof declared !== 'object' || declared === null)
90
+ throw new Error(`${packageDir}/package.json: "starci" is an object ({ errorBase, outcome })`);
91
+ const contract = {};
92
+ for (const key of CONTRACT_KEYS) {
93
+ const entry = declared[key];
94
+ if (entry === undefined)
95
+ continue;
96
+ const { name, file } = (typeof entry === 'object' && entry !== null ? entry : {});
97
+ if (typeof name !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(name) || typeof file !== 'string' || !/^src\/(?:[\w.-]+\/)*[\w.-]+\.ts$/.test(file)) {
98
+ throw new Error(`${packageDir}/package.json: "starci.${key}" is { "name": "<Identifier>", "file": "src/<path>.ts" }`);
99
+ }
100
+ contract[key] = Object.freeze({ name, file: `${packageDir}/${file}` });
101
+ }
102
+ return Object.freeze(contract);
103
+ };
73
104
  /**
74
105
  * 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
75
106
  * 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) {
103
134
  const relative = rel(file);
104
135
  return slot !== undefined && ROOT_PACKAGE_SLOTS.has(slot) ? relative.split('/').slice(0, 2).join('/') : null;
105
136
  };
137
+ const contracts = new Map();
138
+ const packageContract = (file) => {
139
+ const dir = packageOf(file);
140
+ if (dir === null)
141
+ return null;
142
+ if (!contracts.has(dir))
143
+ contracts.set(dir, readPackageContract(repoRoot, dir));
144
+ return contracts.get(dir);
145
+ };
106
146
  return Object.freeze({
107
147
  repoRoot,
108
148
  profile: side,
@@ -121,6 +161,7 @@ function packagesView(opened, repoRoot, side) {
121
161
  ownerOf: () => null,
122
162
  allows: (file) => allowsFile(opened, rel(file)),
123
163
  slot: (id) => opened.slot(id),
164
+ packageContract,
124
165
  });
125
166
  }
126
167
  /**