@starci/hfs 2.0.2 → 4.0.0

package/runtime/scripts/checks/architecture/test-world-files.mjs

@@ -3,25 +3,30 @@ import { allowsFile } from '../../lib/hfs-allows.mjs';
 import { DEFAULT_ENVIRONMENT, STACKS_DIRECTORY, STATEFUL_KINDS, namesOfService, readStack } from '../../lib/stack-services.mjs';
 
 /**
- * R47 `test-world-files` (BE_TEST_TOPOLOGY). Two judgements over the test world, read through slots, the repository's own
+ * R47 `test-world-files` (BE_TEST_TOPOLOGY). Judgements over the test world, read through slots, the repository's own
  * stack definition (`.starcistacks/<env>`, scripts/lib/stack-services.mjs) and the world's declaration
- * (`test-world.config.ts` of the test-world library), never through a path or a name list:
+ * (`test-world.config.ts`, read in the shape @starci/test-world defines), never through a path or a name list:
  *
  * 1. Files. `src/tests/world/` is the only test infrastructure location, and it holds only what its slot `allows`
  *    (knowledge/hfs/slots.yaml be.tests.world: global-setup.ts, global-teardown.ts, use-test-world.ts, and fakes/; kit/ is
  *    its own slot, be.tests.world.kit) plus files at its root whose role suffix is in ruleParams.be.suffixes
  *    (`stripe.client.ts`, `checkout.contracts.ts`, `test-world.config.ts`, ...). Every tracked file below the world root is
  *    matched by the slot's own entries through `allowsFile`.
- * 2. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world;
- *    `fakes/<provider>/` holds a network-edge fake of an external SaaS the team does not operate. A `fakes/<provider>/` that
- *    fakes a stack service (its own name, its image repository or a well-known alias of the image) is refused, except the one
- *    owner-approved exception: a stack service that is stateless compute needing special hardware or an external model
- *    (GPU inference, a self-hosted embedding model) and that the config declares in `fakedBy`:
- *    `fakedBy: { "<stack service>": { fake: "<fakes/ folder>", reason: "<non-empty>" } }`. A stack service of a stateful
- *    kind (database, cache, identity, storage, mail, queue, search) or with a persistent volume is never accepted, and a
- *    `fakedBy` entry that names a stack service or a fake folder that does not exist, or has no reason, is refused as stale
- *    or empty. The config's `stacks` names the stack environments the world runs (default `dev`); the machine reads the
- *    literal object of the config through the TypeScript AST and nothing else of it.
+ * 2. The declaration. `test-world.config.ts` declares the world in ONE form, the named export R89 allows:
+ *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })` (an exported `const` initialized by a
+ *    `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
+ *    read) is refused: the world it declares could not be judged.
+ * 3. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world; a fake
+ *    (a `fakes/<provider>/` folder, or a `fakes` entry of the declaration such as `smtp: smtpFake()`) is a network-edge fake
+ *    of an external SaaS the team does not operate. A fake of a stack service (its own name, its image repository or a
+ *    well-known alias of the image) is refused, except the one owner-approved exception: a stack service that is stateless
+ *    compute needing special hardware or an external model (GPU inference, a self-hosted embedding model) whose `stacks` entry
+ *    declares it faked: `stacks: { "<stack service>": { fakedBy: "<fake>", reason: "<non-empty>" } }`. A stack service of a
+ *    stateful kind (database, cache, identity, storage, mail, queue, search) or with a persistent volume is never accepted, and
+ *    an entry that names a stack service or a fake (a `fakes` entry or a `fakes/` folder) that does not exist, or has no
+ *    reason, is refused as stale or empty. The declaration's `stack` (`".starcistacks/<env>"`) names the stack environment the
+ *    world runs (default `dev`); the machine reads the literal object of the declaration through the TypeScript AST and
+ *    nothing else of it.
  */
 export const TEST_WORLD_FILES_RULE_IDS = ['BE_TEST_TOPOLOGY'];
 
@@ -29,6 +34,8 @@ const RULE = 'BE_TEST_TOPOLOGY';
 const WORLD_SLOT = 'be.tests.world';
 const FAKES_DIRECTORY = 'fakes/';
 const CONFIG_FILE = 'test-world.config.ts';
+const DEFINE = 'defineTestWorld';
+const NAMED_FORM = `export const { useTestWorld, useSandbox } = ${DEFINE}({ ... })`;
 const defaultEnvironment = DEFAULT_ENVIRONMENT;
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
@@ -39,51 +46,70 @@ const unwrap = (ts, node) => {
   return current;
 };
 const propertyOf = (ts, literal, key) => literal.properties.find(property => ts.isPropertyAssignment(property) && nameOf(ts, property.name) === key)?.initializer ?? null;
+const isExported = (ts, statement) => (statement.modifiers ?? []).some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword);
+const positionOf = (sourceFile, node) => {
+  const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return { line: position.line + 1, column: position.character + 1 };
+};
+
+/** The object literal of `defineTestWorld(<object literal>)`, or null. */
+function defineLiteral(ts, expression) {
+  const call = unwrap(ts, expression);
+  if (!call || !ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || call.expression.text !== DEFINE) return null;
+  const [first] = call.arguments;
+  const literal = first ? unwrap(ts, first) : null;
+  return literal && ts.isObjectLiteralExpression(literal) ? literal : null;
+}
 
-/** The object literal a config file declares: `export default { ... }` or `export default defineTestWorld({ ... })`. */
+/** The declaration of the world: the object literal of an exported `const` initialized by `defineTestWorld({ ... })`, or null. */
 function configLiteral(ts, sourceFile) {
   for (const statement of sourceFile.statements) {
-    if (!ts.isExportAssignment(statement)) continue;
-    const expression = unwrap(ts, statement.expression);
-    if (ts.isObjectLiteralExpression(expression)) return expression;
-    if (ts.isCallExpression(expression)) {
-      const [first] = expression.arguments;
-      const literal = first ? unwrap(ts, first) : null;
-      if (literal && ts.isObjectLiteralExpression(literal)) return literal;
+    if (!ts.isVariableStatement(statement) || !isExported(ts, statement)) continue;
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      const literal = declaration.initializer ? defineLiteral(ts, declaration.initializer) : null;
+      if (literal) return literal;
     }
   }
   return null;
 }
 
-/** `stacks` as a list of environment names: an array of strings, or the keys of an object literal. */
-function stacksOf(ts, literal) {
-  const node = literal ? propertyOf(ts, literal, 'stacks') : null;
+/** `stack` as the environment it names: the last segment of `".starcistacks/<env>"`; null when absent or not a literal. */
+function environmentOf(ts, literal) {
+  const node = literal ? propertyOf(ts, literal, 'stack') : null;
   const value = node ? unwrap(ts, node) : null;
-  if (!value) return null;
-  if (ts.isArrayLiteralExpression(value)) return value.elements.filter(element => ts.isStringLiteralLike(element)).map(element => element.text);
-  if (ts.isObjectLiteralExpression(value)) return value.properties.map(property => nameOf(ts, property.name)).filter(Boolean);
-  return null;
+  if (!value || !ts.isStringLiteralLike(value)) return null;
+  return value.text.split(/[\\/]+/u).filter(Boolean).at(-1) ?? null;
 }
 
-/** `fakedBy` entries: [{service, fake, reason, line, column}]; a value the reader cannot read statically has an empty fake and reason. */
+/** The keys of the declaration's `fakes` object literal, with their positions. */
+function fakeEntriesOf(ts, sourceFile, literal) {
+  const node = literal ? propertyOf(ts, literal, 'fakes') : null;
+  const value = node ? unwrap(ts, node) : null;
+  if (!value || !ts.isObjectLiteralExpression(value)) return [];
+  return value.properties
+    .map(property => ({ name: nameOf(ts, property.name), ...positionOf(sourceFile, property) }))
+    .filter(entry => entry.name);
+}
+
+/** The `stacks` entries that declare `fakedBy`: [{service, fake, reason, line, column}]; a value the reader cannot read statically has an empty fake and reason. */
 function fakedByOf(ts, sourceFile, literal) {
-  const node = literal ? propertyOf(ts, literal, 'fakedBy') : null;
+  const node = literal ? propertyOf(ts, literal, 'stacks') : null;
   const value = node ? unwrap(ts, node) : null;
   if (!value || !ts.isObjectLiteralExpression(value)) return [];
   const entries = [];
   for (const property of value.properties) {
     if (!ts.isPropertyAssignment(property)) continue;
-    const service = nameOf(ts, property.name);
     const body = unwrap(ts, property.initializer);
-    const fake = ts.isObjectLiteralExpression(body) ? propertyOf(ts, body, 'fake') : null;
-    const reason = ts.isObjectLiteralExpression(body) ? propertyOf(ts, body, 'reason') : null;
-    const position = sourceFile.getLineAndCharacterOfPosition(property.getStart(sourceFile));
+    if (!body || !ts.isObjectLiteralExpression(body)) continue;
+    const fake = propertyOf(ts, body, 'fakedBy');
+    if (!fake) continue;
+    const reason = propertyOf(ts, body, 'reason');
     entries.push({
-      service,
-      fake: fake && ts.isStringLiteralLike(fake) ? fake.text : '',
+      service: nameOf(ts, property.name),
+      fake: ts.isStringLiteralLike(fake) ? fake.text : '',
       reason: reason && ts.isStringLiteralLike(reason) ? reason.text.trim() : '',
-      line: position.line + 1,
-      column: position.character + 1,
+      ...positionOf(sourceFile, property),
     });
   }
   return entries;
@@ -123,7 +149,13 @@ export function checkTestWorldFiles(input) {
   const configPath = worldRoot === null ? null : `${worldRoot}${CONFIG_FILE}`;
   const configFile = configPath === null ? null : graph.files.get(configPath) ?? null;
   const literal = configFile ? configLiteral(ts, configFile.sourceFile) : null;
-  const environments = (literal ? stacksOf(ts, literal) : null) ?? [defaultEnvironment];
+  if (configFile && !literal) {
+    violations.push({
+      ruleId: RULE, path: configPath, line: 1, column: 1, slot: WORLD_SLOT,
+      message: `${configPath} declares no world the machine can read. Declare it in the one named form \`${NAMED_FORM}\` (an exported const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
+    });
+  }
+  const environments = [(literal ? environmentOf(ts, literal) : null) ?? defaultEnvironment];
   const services = [];
   for (const environment of environments) {
     let stack = null;
@@ -132,14 +164,15 @@ export function checkTestWorldFiles(input) {
   }
   const stackHint = `${STACKS_DIRECTORY}/${environments.join(', ')}`;
   const statefulWhy = service => (STATEFUL_KINDS.has(service.kind) ? `a ${service.kind} holds data the app reads back` : service.persistent ? 'the stack gives it a persistent volume' : null);
-  const declared = configFile ? fakedByOf(ts, configFile.sourceFile, literal) : [];
+  const declared = literal ? fakedByOf(ts, configFile.sourceFile, literal) : [];
+  const fakeEntries = literal ? fakeEntriesOf(ts, configFile.sourceFile, literal) : [];
 
   for (const entry of declared) {
     const service = services.find(candidate => candidate.name === entry.service);
     const problems = [];
     if (!service) problems.push(`${stackHint} declares no service ${entry.service}`);
     else if (statefulWhy(service)) problems.push(`${service.name} is stateful (${statefulWhy(service)}) and always runs real`);
-    if (!fakeProviders.has(entry.fake)) problems.push(`there is no fakes/${entry.fake || '<fake>'}/ folder`);
+    if (!fakeProviders.has(entry.fake) && !fakeEntries.some(fake => fake.name === entry.fake)) problems.push(`there is no fakes entry and no fakes/${entry.fake || '<fake>'}/ folder of that name`);
     if (entry.reason === '') problems.push('the reason is empty');
     if (problems.length > 0) {
       violations.push({
@@ -149,14 +182,19 @@ export function checkTestWorldFiles(input) {
     }
   }
 
-  for (const [provider, file] of [...fakeProviders].sort(([a], [b]) => a.localeCompare(b))) {
-    const service = services.find(candidate => namesOfService(candidate).includes(provider));
+  // Every fake the world runs: the repository's fakes/<provider>/ folders and the fakes entries of the declaration.
+  const fakes = [
+    ...[...fakeProviders].map(([provider, file]) => ({ name: provider, path: file, line: 1, column: 1, what: `fakes/${provider}/` })),
+    ...fakeEntries.filter(entry => !fakeProviders.has(entry.name)).map(entry => ({ name: entry.name, path: configPath, line: entry.line, column: entry.column, what: `the fakes entry ${entry.name}` })),
+  ].sort((a, b) => a.name.localeCompare(b.name));
+  for (const fake of fakes) {
+    const service = services.find(candidate => namesOfService(candidate).includes(fake.name));
     if (!service) continue;
-    if (declared.some(entry => entry.service === service.name && entry.fake === provider)) continue; // judged on its config entry above
+    if (declared.some(entry => entry.service === service.name && entry.fake === fake.name)) continue; // judged on its stacks entry above
     const why = statefulWhy(service);
     violations.push({
-      ruleId: RULE, path: file, line: 1, column: 1, slot: WORLD_SLOT,
-      message: `fakes/${provider}/ fakes ${service.name} (${service.image}), which ${stackHint} declares: a service of the repository's own stack runs real in the test world. ${why ? `${service.name} is stateful (${why}), so no exception applies. ` : `Only stateless compute that needs special hardware or an external model may be faked, and only when ${configPath ?? `${CONFIG_FILE} in the world`} declares it in fakedBy with a reason. `}Delete the fake and let the world run the real service; fakes/ is otherwise only for external SaaS the team does not operate.`,
+      ruleId: RULE, path: fake.path, line: fake.line, column: fake.column, slot: WORLD_SLOT,
+      message: `${fake.what} fakes ${service.name} (${service.image}), which ${stackHint} declares: a service of the repository's own stack runs real in the test world. ${why ? `${service.name} is stateful (${why}), so no exception applies. ` : `Only stateless compute that needs special hardware or an external model may be faked, and only when ${configPath ?? `${CONFIG_FILE} in the world`} declares it in its stacks entry ({ fakedBy, reason }). `}Delete the fake and let the world run the real service; fakes are otherwise only for external SaaS the team does not operate.`,
     });
   }
   return { violations, coverage: { status: 'checked', files } };

package/runtime/scripts/checks/architecture/typescript.mjs

@@ -5,6 +5,7 @@ import { canonical, isInside, slash } from './config.mjs';
 import { sameOrUnder } from '../../lib/path-key.mjs';
 import { createTypeScriptProgram, readTypeScriptProject, resolveTypeScriptModule, sharedInProgramRun, typeScriptProjectReferencePath } from '../typescript-programs.mjs';
 import { readJsonFile } from '../../lib/json.mjs';
+import { locateDeclaration } from '../../lib/hfs-slots.mjs';
 
 const CODE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/i;
 const TEST_FILE = /(?:^|[.-])(?:spec|test)\.[cm]?[jt]sx?$/i;
@@ -16,14 +17,14 @@ export const GENERATED_SEGMENTS = new Set(['.next', '.turbo', '.vercel', '.outpu
 export function isGeneratedPath(root, fileName) {
   return slash(path.relative(root, fileName)).split('/').slice(0, -1).some(segment => GENERATED_SEGMENTS.has(segment));
 }
-// A `<tool>.config.*` or `<tool>.setup.*` module beside a package manifest (next.config.ts,
-// postcss.config.mjs) is build tooling a broad `**/*.ts` include pulls in; a `*.config.ts` inside a source tree
-// (src/config/database.config.ts) has no manifest beside it and stays source. The architecture program still
-// reads tooling modules (a profile may declare one as source); check-scoped-lint does not make one a canon
-// lint subject unless the profile's sourceGlobs name it.
+// A `<tool>.config.*` or `<tool>.setup.*` module at the root of a project (beside a package manifest or a tsconfig.json:
+// next.config.ts and postcss.config.mjs of an app, which has no package.json of its own) is build tooling a broad `**/*.ts`
+// include pulls in; a `*.config.ts` inside a source tree (src/config/database.config.ts) has neither beside it and stays source.
+// The architecture program still reads tooling modules (a profile may declare one as source); the lint (hfs lint) judges one only
+// through the repository's own eslint.config.
 const TOOLING_MODULE = /^[^/]+\.(?:config|setup)\.[cm]?[jt]sx?$/i;
 export function isToolingModule(fileName) {
-  return TOOLING_MODULE.test(path.basename(fileName)) && fs.existsSync(path.join(path.dirname(fileName), 'package.json'));
+  return TOOLING_MODULE.test(path.basename(fileName)) && ['package.json', 'tsconfig.json'].some((manifest) => fs.existsSync(path.join(path.dirname(fileName), manifest)));
 }
 
 function diagnosticMessage(ts, diagnostic) {
@@ -48,9 +49,12 @@ function compilerError(ts, root, diagnostic, project, ruleId = 'ARCH_TSCONFIG_IN
   };
 }
 
-/** Load TypeScript through the target package boundary, never through StarCi's own dependency graph. */
+/**
+ * Load TypeScript through the target package boundary, never through StarCi's own dependency graph. A side folder of an app has no
+ * package.json of its own: the app root's one manifest is the boundary its TypeScript is installed under.
+ */
 export function loadTargetTypeScript(repositoryRoot) {
-  const packageFile = path.join(repositoryRoot, 'package.json');
+  const packageFile = path.join(locateDeclaration(repositoryRoot).appRoot, 'package.json');
   if (!fs.existsSync(packageFile)) throw Error('ARCH_TYPESCRIPT_MISSING: target package.json is required to resolve target-installed TypeScript.');
   const targetRequire = createRequire(packageFile);
   let resolved;
@@ -184,12 +188,13 @@ function workspaceMetadata(config) {
     const root = path.join(config.root, ...relative.split('/'));
     const pkg = readJson(path.join(root, 'package.json'));
     const routeRoots = config.frontend.routes.map(item => path.join(config.root, ...item.split('/')));
-    return { root: canonical(root), relative, name: typeof pkg.name === 'string' ? pkg.name : null, exports: pkg.exports,
+    return { root: canonical(root), relative, name: typeof pkg.name === 'string' ? pkg.name : null, exports: pkg.exports, manifest: pkg, workspace: true,
       app: routeRoots.some(route => isInside(root, route))
         || backendAppRoots.some(appRoot => isInside(appRoot, root) || isInside(root, appRoot)) };
   };
   const roots = config.workspaces.map(create);
-  const rootPackage = readJson(path.join(config.root, 'package.json'));
+  // A side of an app has no package.json: the app root's one manifest names the package the side's root files belong to.
+  const rootPackage = readJson(path.join(config.packageRoot ?? config.root, 'package.json')) ?? {};
   roots.push({ root: canonical(config.root), relative: '.', name: typeof rootPackage.name === 'string' ? rootPackage.name : null, exports: rootPackage.exports,
     app: config.frontend.routes.some(item => isInside(config.root, path.join(config.root, ...item.split('/')))) || config.kinds.includes('backend') });
   return roots.sort((a, b) => b.root.length - a.root.length);
@@ -212,18 +217,19 @@ function exportTargetStrings(value) {
   return [];
 }
 
-function packageExported(workspace, specifier, actualTarget) {
-  if (!workspace.name || !sameOrUnder(specifier, workspace.name)) return false;
+/** The package-relative export targets a request (`.` or `./sub`) of a workspace package declares, from exports, else types/main. */
+function exportCandidates(workspace, specifier) {
+  if (!workspace.name || !sameOrUnder(specifier, workspace.name)) return [];
   const request = specifier === workspace.name ? '.' : `.${specifier.slice(workspace.name.length)}`;
   const declaration = workspace.exports;
   let candidates = [];
   if (typeof declaration === 'string' || Array.isArray(declaration)) {
-    if (request !== '.') return false;
+    if (request !== '.') return [];
     candidates = exportTargetStrings(declaration);
   } else if (declaration && typeof declaration === 'object') {
     const keys = Object.keys(declaration);
     if (!keys.some(key => key.startsWith('.'))) {
-      if (request !== '.') return false;
+      if (request !== '.') return [];
       candidates = exportTargetStrings(declaration);
     } else {
       for (const key of keys) {
@@ -232,10 +238,80 @@ function packageExported(workspace, specifier, actualTarget) {
       }
     }
   }
-  return candidates.some(target => {
+  return candidates;
+}
+
+const SOURCE_EXTENSIONS = { '.d.ts': ['.ts', '.tsx'], '.d.mts': ['.mts'], '.d.cts': ['.cts'], '.js': ['.ts', '.tsx'], '.jsx': ['.tsx'], '.mjs': ['.mts'], '.cjs': ['.cts'] };
+
+/** rootDir and outDir of a workspace package's build tsconfig (tsconfig.build.json, else tsconfig.json), extends followed; null when it declares none. */
+function workspaceBuildLayout(ts, workspace) {
+  if (workspace.layout !== undefined) return workspace.layout;
+  workspace.layout = null;
+  for (const name of ['tsconfig.build.json', 'tsconfig.json']) {
+    const file = path.join(workspace.root, name);
+    if (!fs.existsSync(file)) continue;
+    const read = ts.readConfigFile(file, ts.sys.readFile);
+    if (read.error) continue;
+    const { options } = ts.parseJsonConfigFileContent(read.config, ts.sys, workspace.root, undefined, file);
+    if (options.outDir) { workspace.layout = { rootDir: options.rootDir ? path.resolve(options.rootDir) : path.join(workspace.root, 'src'), outDir: path.resolve(options.outDir) }; break; }
+  }
+  return workspace.layout;
+}
+
+/** The source file a built export target (`./dist/sub/index.js`, `.d.ts`) stands for: outDir back to rootDir, else the dist-to-src layout; null when none exists. */
+function sourceOfTarget(ts, workspace, target) {
+  const absolute = path.resolve(workspace.root, target);
+  const layout = workspaceBuildLayout(ts, workspace);
+  const extension = Object.keys(SOURCE_EXTENSIONS).filter(item => absolute.endsWith(item)).sort((a, b) => b.length - a.length)[0];
+  const sourceRoots = [];
+  if (layout && isInside(layout.outDir, absolute)) sourceRoots.push([layout.outDir, layout.rootDir]);
+  const first = slash(path.relative(workspace.root, absolute)).split('/')[0];
+  if (first) sourceRoots.push([path.join(workspace.root, first), path.join(workspace.root, 'src')]);
+  if (!extension) return null;
+  for (const [from, to] of sourceRoots) {
+    const stem = path.join(to, path.relative(from, absolute)).slice(0, -extension.length);
+    for (const candidate of SOURCE_EXTENSIONS[extension]) if (fs.existsSync(stem + candidate)) return canonical(stem + candidate);
+  }
+  return null;
+}
+
+/** The source entry a workspace import resolves to without a build: its export targets mapped back to source, `src/index.ts` for the package root. */
+function workspaceSourceEntry(ts, workspace, specifier) {
+  if (!workspace.workspace || !workspace.name || !sameOrUnder(specifier, workspace.name)) return null;
+  let candidates = exportCandidates(workspace, specifier);
+  if (specifier === workspace.name && !workspace.exports) candidates = [workspace.manifest?.types, workspace.manifest?.typings, workspace.manifest?.module, workspace.manifest?.main].filter(item => typeof item === 'string');
+  for (const target of candidates) {
+    if (!target.startsWith('./') || target.includes('..')) continue;
+    const source = sourceOfTarget(ts, workspace, target);
+    if (source) return source;
+  }
+  if (specifier === workspace.name) {
+    for (const name of ['index.ts', 'index.tsx']) if (fs.existsSync(path.join(workspace.root, 'src', name))) return canonical(path.join(workspace.root, 'src', name));
+  }
+  return null;
+}
+
+/** Every source file the package.json `exports` of a workspace package maps (each non-wildcard subpath, dist back to source): its public entries. */
+export function workspaceExportSources(ts, workspace) {
+  const declaration = workspace.exports;
+  if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration)) return [];
+  const sources = new Set();
+  for (const [key, value] of Object.entries(declaration)) {
+    if (!key.startsWith('.') || key.includes('*')) continue;
+    for (const target of exportTargetStrings(value)) {
+      if (!target.startsWith('./') || target.includes('..')) continue;
+      const source = sourceOfTarget(ts, workspace, target);
+      if (source) sources.add(source);
+    }
+  }
+  return [...sources];
+}
+
+function packageExported(ts, workspace, specifier, actualTarget) {
+  return exportCandidates(workspace, specifier).some(target => {
     if (!target.startsWith('./') || target.includes('..')) return false;
     const expected = canonical(path.resolve(workspace.root, target));
-    return expected === canonical(actualTarget);
+    return expected === canonical(actualTarget) || sourceOfTarget(ts, workspace, target) === canonical(actualTarget);
   });
 }
 
@@ -344,20 +420,29 @@ function typeScriptContext(config, loaded, paths) {
       .map(item => compilerError(ts, config.root, item, relative, 'ARCH_SYNTAX_INVALID')));
     projects.push({ relative, program, options: parsed.options });
   }
-  const fileMap = new Map();
-  const checkerByFile = new Map();
   const occurrences = new Map();
+  const sourceIn = new Map();
   for (const project of projects) {
     for (const sourceFile of project.program.getSourceFiles().filter(file => isProductionSource(config.root, file))) {
       const name = canonical(sourceFile.fileName);
-      if (!fileMap.has(name)) {
-        fileMap.set(name, sourceFile);
-        checkerByFile.set(name, project.program.getTypeChecker());
-      }
       if (!occurrences.has(name)) occurrences.set(name, []);
       occurrences.get(name).push(project);
+      sourceIn.set(`${project.relative}|${name}`, sourceFile);
     }
   }
+  // The deepest project directory holding a file owns it: its source file, its checker and its resolution. A side or repository
+  // root tsconfig without paths must not shadow the app project whose aliases (`@/*`) the file actually uses.
+  const owningProject = (candidates, file) => candidates.filter(item => isInside(path.dirname(path.join(config.root, ...item.relative.split('/'))), file))
+    .sort((x, y) => y.relative.split('/').length - x.relative.split('/').length)[0] ?? candidates[0];
+  const fileMap = new Map();
+  const checkerByFile = new Map();
+  const ownerByFile = new Map();
+  for (const [name, candidates] of occurrences) {
+    const owner = owningProject(candidates, name);
+    ownerByFile.set(name, owner);
+    fileMap.set(name, sourceIn.get(`${owner.relative}|${name}`));
+    checkerByFile.set(name, owner.program.getTypeChecker());
+  }
   const files = [...fileMap.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, file]) => file);
   const edges = new Map([...fileMap.keys()].map(file => [file, []]));
   for (const [file, sourceFile] of fileMap) {
@@ -370,11 +455,7 @@ function typeScriptContext(config, loaded, paths) {
   const workspaceNames = new Set(workspaces.map(item => item.name).filter(Boolean));
   for (const [from, sourceFile] of fileMap) {
     const owningWorkspace = workspaceOf(workspaces, from);
-    const candidates = occurrences.get(from) ?? [];
-    // The deepest project directory holding the file owns its resolution: a root tsconfig without paths must not
-    // shadow the app project whose aliases the file actually uses.
-    const project = candidates.filter(item => isInside(path.dirname(path.join(config.root, ...item.relative.split('/'))), from))
-      .sort((x, y) => y.relative.split('/').length - x.relative.split('/').length)[0] ?? candidates[0];
+    const project = ownerByFile.get(from);
     if (!project) continue;
     const references = moduleReferences(ts, sourceFile, project.program.getTypeChecker());
     for (const item of references.unproven) errors.push({
@@ -385,7 +466,9 @@ function typeScriptContext(config, loaded, paths) {
       message: `${item.kind} must use a string-literal module name so architecture coverage can resolve its dependency.`,
     });
     for (const reference of references.found) {
-      const resolvedName = resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host);
+      // A workspace package is read at its source, never at its build: the same import resolves whether or not dist exists.
+      const workspaceTarget = workspaces.filter(item => item.root !== canonical(config.root)).map(item => workspaceSourceEntry(ts, item, reference.specifier)).find(Boolean);
+      const resolvedName = workspaceTarget ?? resolveTypeScriptModule(ts, reference.specifier, sourceFile.fileName, project.options, host);
       if (!resolvedName) {
         const codeLike = !ASSET_EXTENSION.test(reference.specifier);
         const workspaceImport = [...workspaceNames].some(name => sameOrUnder(reference.specifier, name));
@@ -412,6 +495,21 @@ function typeScriptContext(config, loaded, paths) {
       // project is then the boundary it always was.
       const reviewable = isInside(config.root, actualTarget)
         || (config.repository && isInside(config.repository, actualTarget) && !slash(actualTarget).includes('/node_modules/'));
+      // A side of an app (config.root is be/ or fe/) imports nothing of the app outside itself: the root holds no source, the other
+      // side is another program, and a declared read (sides.fe.reads, be/contracts/) is codegen input, never an import.
+      const crossesSide = config.packageRoot !== undefined && config.packageRoot !== config.root
+        && isInside(config.packageRoot, actualTarget) && !isInside(config.root, actualTarget) && !slash(actualTarget).includes('/node_modules/');
+      if (internal && crossesSide) {
+        errors.push({
+          ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
+          project: project.relative,
+          path: relativePath(config.root, sourceFile.fileName),
+          ...sourceLocation(sourceFile, reference.node),
+          specifier: reference.specifier,
+          message: `Internal import ${reference.specifier} leaves the ${path.basename(config.root)} side for ${slash(path.relative(config.packageRoot, actualTarget))}; nothing crosses the sides of an app.`,
+        });
+        continue;
+      }
       if (internal && !reviewable) {
         errors.push({
           ruleId: 'ARCH_INTERNAL_IMPORT_OUTSIDE',
@@ -443,7 +541,7 @@ function typeScriptContext(config, loaded, paths) {
         if (!owningWorkspace.app && targetWorkspace.app) {
           errors.push(boundaryViolation(config.root, edge, owningWorkspace, targetWorkspace, 'ARCH_PACKAGE_IMPORTS_APP', 'A reusable workspace package cannot depend on an application workspace.'));
         }
-        if (!packageExported(targetWorkspace, reference.specifier, actualTarget)) {
+        if (!packageExported(ts, targetWorkspace, reference.specifier, actualTarget)) {
           errors.push(boundaryViolation(config.root, edge, owningWorkspace, targetWorkspace, 'ARCH_PACKAGE_EXPORT_BYPASS', 'Cross-package imports must use the target package name and a declared package export.'));
         }
       }

package/runtime/scripts/checks/typescript-programs.mjs

@@ -4,8 +4,8 @@ import path from 'node:path';
 
 // One TypeScript program per (compiler, root names, compiler options, project references) inside a program run, and
 // one value per (kind, compiler, input) for what callers derive from those programs (the architecture context).
-// check-scoped-lint opens one run around its architecture check and its script checkers and releases it before
-// ESLint and the base measurement, so nothing built here outlives the run that built it. Outside a run every call
+// A caller (canon-scan's architecture machine, a script checker) opens one run around its work and releases it after,
+// so nothing built here outlives the run that built it. Outside a run every call
 // builds afresh.
 const runs = new AsyncLocalStorage();