@starci/hfs 4.7.31 → 4.7.33

package/runtime/scripts/gates/type-impact.mjs

@@ -0,0 +1,277 @@
+// type-impact.mjs - compiler project impact, prerequisite stamps and stale buildinfo cleanup of the code gate.
+import fs from 'node:fs';
+import path from 'node:path';
+import { byCodeUnit } from '../lib/list.mjs';
+import { sha256, sha256File } from '../../engine/digest.mjs';
+import { pathKey, posixPath } from '../lib/path-key.mjs';
+import { walkFiles, isInside } from '../lib/walk.mjs';
+import { locateDeclaration, openHfs } from '../hfs/slots.mjs';
+import { typeScriptProjectReferencePath } from '../hfs/typescript-programs.mjs';
+
+/** The existing gate's TypeScript input suffixes; JavaScript is not silently given a new checkJs contract. */
+export const TS_SOURCE = /\.(?:[cm]?tsx?)$/;
+const regular = (file) => {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`type input is not a regular file: ${file}`);
+  return stat;
+};
+/** Only the canonical output slot proves generation; a source directory may have any basename. */
+const generatedOutput = (root) => {
+  const hfs = fs.existsSync(locateDeclaration(root).file) ? openHfs({ repoRoot: root }) : null;
+  return (file) => ['repo.build-output', 'app.build-output'].includes(hfs?.slotOf(posixPath(path.relative(root, file)))?.id);
+};
+const sourceFiles = (dir, root = dir) => {
+  const generated = generatedOutput(root);
+  return walkFiles(dir, { sorted: true, exclude: (name, full) => name === 'node_modules' || name === '.git' || generated(full) }).sort(byCodeUnit);
+};
+// Prerequisite stamps retain their cache/custody policy; it never decides compiler ownership.
+const stampDirectories = new Set(['node_modules', '.git', 'dist', 'coverage', '.next', '.turbo', '.starci', '.starciwork', '.starcistacks', '.artifacts']);
+const stampFiles = (dir) => walkFiles(dir, { sorted: true, exclude: (name) => stampDirectories.has(name) || name.endsWith('.tsbuildinfo') }).sort(byCodeUnit);
+
+/** Read bounded compiler membership/references; config errors throw, while no-input diagnostics remain owed by compilation. */
+export function readTypeProject(ts, root, project, sys) {
+  const parsed = ts.getParsedCommandLineOfConfigFile(path.join(root, project), {}, sys);
+  if (!parsed) throw new Error(`${project} could not be read`);
+  const errors = parsed.errors.filter((diagnostic) => diagnostic.code !== 18003);
+  if (errors.length) throw new Error(`${project}: ${ts.flattenDiagnosticMessageText(errors[0].messageText, '\n')}`);
+  return { parsed, fileNames: parsed.fileNames, references: (parsed.projectReferences ?? []).map((reference) => typeScriptProjectReferencePath(ts, reference)) };
+}
+
+/** Remove stale worktree *.tsbuildinfo files outside node_modules and .git, returning their root-relative paths. */
+export function removeStaleBuildInfo(root) {
+  const files = walkFiles(root, { filter: (name) => name.endsWith('.tsbuildinfo'), exclude: (name, full, entry) => entry.isDirectory() && (name === 'node_modules' || name === '.git'), ignoreReadErrors: true });
+  for (const file of files) fs.rmSync(file, { force: true });
+  return files.map((file) => posixPath(path.relative(root, file)));
+}
+
+/** Exact current file bytes, path membership and missing scopes; an M-to-M edit never retains a stamp. */
+export function inputStamp(root, paths) {
+  const top = path.resolve(root), rows = ['type-input-bytes-v1\0'];
+  for (const scope of [...new Set(paths.map(posixPath))].sort(byCodeUnit)) {
+    const at = path.resolve(top, scope);
+    if (!isInside(top, at)) throw new Error(`type input scope is outside the app: ${scope}`);
+    rows.push(`scope\0${scope}\0`);
+    if (!fs.existsSync(at)) { rows.push('missing\0'); continue; }
+    const stat = fs.lstatSync(at);
+    if (stat.isSymbolicLink()) throw new Error(`type input scope is linked: ${scope}`);
+    for (const file of stat.isDirectory() ? stampFiles(at) : [at]) {
+      const item = regular(file);
+      rows.push(`file\0${posixPath(path.relative(top, file))}\0${item.size}\0${sha256File(file)}\0`);
+    }
+  }
+  return sha256(rows.join(''));
+}
+
+/** Whether a workspace exposes built declarations or JavaScript beneath dist/. */
+export const exposesDist = (manifest) => /(?:^|["/])dist\//.test(JSON.stringify([manifest?.exports ?? null, manifest?.main ?? null, manifest?.types ?? null, manifest?.module ?? null]));
+
+/** Declared workspace directories; the gate builds only its existing dist-exposing workspace owners. */
+export function workspaceDirs(root, manifest) {
+  const globs = Array.isArray(manifest?.workspaces) ? manifest.workspaces : manifest?.workspaces?.packages ?? [];
+  return globs.flatMap((glob) => {
+    const clean = posixPath(glob).replace(/\/$/, '');
+    if (!clean.endsWith('/*')) return fs.existsSync(path.join(root, clean, 'package.json')) ? [clean] : [];
+    const parent = clean.slice(0, -2);
+    let entries = [];
+    try { entries = fs.readdirSync(path.join(root, parent), { withFileTypes: true }); } catch (error) {
+      if (error.code === 'ENOENT') return [];
+      throw error;
+    }
+    return entries.filter((entry) => entry.isDirectory() && fs.existsSync(path.join(root, parent, entry.name, 'package.json'))).map((entry) => `${parent}/${entry.name}`);
+  });
+}
+
+const manifestAt = (dir) => {
+  const file = path.join(dir, 'package.json');
+  return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : null;
+};
+const nearestProject = (root, file) => {
+  for (let dir = path.dirname(path.resolve(root, file)); ; dir = path.dirname(dir)) {
+    const config = path.join(dir, 'tsconfig.json');
+    if (fs.existsSync(config)) return posixPath(path.relative(root, config));
+    if (pathKey(dir) === pathKey(root) || path.dirname(dir) === dir) return null;
+  }
+};
+/**
+ * The compiler programs of the sides that read `file` across sides (hfs.json `sides.<side>.reads`, such as the generated
+ * `supabase/types/` of a lite app): such a file has no tsconfig of its own and is typechecked by the programs that import it,
+ * so a change to it affects every tsconfig.json of each reading side. Empty when no side reads it or there is no hfs.json.
+ */
+const readerProjects = (root, file) => {
+  let declaration;
+  try { declaration = JSON.parse(fs.readFileSync(path.join(root, 'hfs.json'), 'utf8')); } catch { return []; }
+  const sides = Object.entries(declaration?.sides ?? {}).filter(([, side]) => (Array.isArray(side?.reads) ? side.reads : []).some((prefix) => typeof prefix === 'string' && file.startsWith(prefix)));
+  return sides.flatMap(([side]) => {
+    const dir = path.join(root, side);
+    return fs.existsSync(dir) ? sourceFiles(dir, root).filter((config) => path.basename(config) === 'tsconfig.json').map((config) => posixPath(path.relative(root, config))) : [];
+  });
+};
+const sharedImpact = (file) => /(?:^|\/)(?:tsconfig[^/]*\.json|package\.json|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|turbo\.json|hfs\.json)$/.test(file) || file.startsWith('scripts/');
+
+const addTo = (projects, project, source = null) => {
+  if (!projects.has(project)) projects.set(project, []);
+  if (source !== null) projects.get(project).push(source);
+};
+
+/** Compiler-resolved configs, including references to custom-named configs, bounded to this app. */
+const projectGraph = (root, configs, readProject) => {
+  const generated = generatedOutput(root);
+  const records = new Map(), active = new Set();
+  const visit = (config) => {
+    const absolute = path.resolve(root, config), project = posixPath(path.relative(root, absolute));
+    if (!isInside(root, absolute)) throw new Error(`GATE_TSC_OWNER_UNPROVEN project reference is outside the app: ${project}`);
+    if (active.has(project)) throw new Error(`GATE_TSC_OWNER_UNPROVEN circular project reference: ${project}`);
+    if (records.has(project)) return;
+    active.add(project);
+    const parsed = readProject(project);
+    const names = new Map(parsed.fileNames.map((file) => [pathKey(file), file])), files = new Set(names.keys());
+    // Missing, invalid and out-of-bound declared inputs remain obligations, even in an output slot.
+    const roots = [...files].filter((file) => !isInside(root, file) || !fs.existsSync(file) || !fs.lstatSync(file).isFile() || !generated(file));
+    const record = { project, dir: path.dirname(absolute), files, names, roots, references: [], parsed: parsed.parsed };
+    records.set(project, record);
+    for (const reference of parsed.references) {
+      const target = posixPath(path.relative(root, path.resolve(root, reference)));
+      record.references.push(target);
+      visit(target);
+    }
+    active.delete(project);
+  };
+  for (const config of configs) visit(config);
+  return records;
+};
+
+const ownsRoot = (record, file, records) => ![...records.values()].some((other) => other.files.has(file)
+  && isInside(record.dir, other.dir, { includeSelf: false }));
+
+/** An ancestor that contributes no roots of its own delegates to its nested or referenced programs. */
+const aggregateProject = (record, records) => {
+  if (!record.roots.length) return record.references.length > 0 || [...records.values()].some((other) => other !== record && isInside(record.dir, other.dir, { includeSelf: false }));
+  return record.roots.every((file) => !ownsRoot(record, file, records));
+};
+
+/**
+ * A config keeps its diagnostics and every root no deeper compiler includes. Residual roots use the
+ * nearest nested config's options, so typed app configuration resolves the same aliases as app source.
+ * Discovery uses the supplied sys, including the gate's read-only base overlay.
+ */
+export function readTypePrograms(ts, root, project, sys) {
+  const directory = path.dirname(path.resolve(root, project)), generated = generatedOutput(root);
+  const configs = sys.readDirectory(directory, ['.json'], ['**/node_modules/**', '**/.git/**'])
+    .filter((file) => path.basename(file) === 'tsconfig.json' && !generated(file));
+  const records = projectGraph(root, [project, ...configs], (config) => readTypeProject(ts, root, config, sys));
+  const record = records.get(posixPath(project)), groups = new Map();
+  const nested = [...records.values()].some((other) => isInside(record.dir, other.dir, { includeSelf: false }));
+  // Leaf programs retain their declared generated inputs (for example Next ambient declarations and route types).
+  const roots = nested ? record.roots : [...record.files];
+  for (const file of roots.filter((file) => ownsRoot(record, file, records))) {
+    const owners = [...records.values()].filter((other) => isInside(record.dir, other.dir) && isInside(other.dir, file));
+    const owner = owners.sort((a, b) => b.dir.length - a.dir.length || byCodeUnit(a.project, b.project))[0] ?? record;
+    if (!groups.has(owner.project)) groups.set(owner.project, { project: owner.project, parsed: owner.parsed, rootNames: [] });
+    groups.get(owner.project).rootNames.push(record.names.get(file));
+  }
+  // Ambient declarations are part of the chosen app's compiler context, including generated Next declarations.
+  for (const group of groups.values()) group.rootNames = [...new Map([...group.rootNames, ...group.parsed.fileNames.filter((file) => /\.d\.[cm]?ts$/.test(file))].map((file) => [pathKey(file), file])).values()];
+  return { parsed: record.parsed, groups: [...groups.values()] };
+}
+
+/** The deepest compiler scopes, plus referenced external roots; an excluded selected file still owes coverage. */
+const sourceOwners = (file, records) => {
+  const candidates = [...records.values()].filter((record) => !aggregateProject(record, records));
+  const included = candidates.filter((record) => record.files.has(pathKey(file)));
+  const scopes = (included.length ? included : candidates).filter((record) => isInside(record.dir, file));
+  const depth = Math.max(...scopes.map((record) => record.dir.length));
+  const nearest = scopes.filter((record) => record.dir.length === depth);
+  const external = included.filter((record) => !isInside(record.dir, file));
+  return [...nearest, ...external];
+};
+
+/** Select real programs through an aggregate/reference graph; each selected source remains a required program input. */
+const addProject = (project, source, { records, projects, errors }, seen = new Set()) => {
+  if (seen.has(project)) return;
+  seen.add(project);
+  const record = records.get(project);
+  if (!record) { errors.push(`GATE_TSC_OWNER_UNPROVEN compiler project was not resolved: ${project}`); return; }
+  addTo(projects, project, source);
+  for (const reference of record.references) addProject(reference, null, { records, projects, errors }, seen);
+  if (aggregateProject(record, records)) {
+    for (const other of records.values()) {
+      if (isInside(record.dir, other.dir, { includeSelf: false })) addProject(other.project, null, { records, projects, errors }, seen);
+    }
+  }
+};
+
+/** Whether one selected file is a dist-workspace member after its owner checks, recording errors and the project. */
+const scanSelected = (root, file, state) => {
+  const { removed, workspaces, records, errors } = state;
+  const at = path.resolve(root, file);
+  if (!isInside(root, at)) { errors.push(`GATE_TSC_OWNER_UNPROVEN selected input is outside the app: ${file}`); return false; }
+  if (!TS_SOURCE.test(file)) return false;
+  const exists = fs.existsSync(at), owners = sourceOwners(at, records);
+  if (!exists && !removed.has(file)) { errors.push(`GATE_TSC_SOURCE_MISSING selected TypeScript does not exist: ${file}`); return false; }
+  if (!owners.length && exists) {
+    const readers = readerProjects(root, file);
+    if (!readers.length) { errors.push(`GATE_TSC_CONFIG_MISSING no tsconfig.json owns selected TypeScript ${file}`); return false; }
+    for (const reader of readers) addProject(reader, null, state);
+    return false;
+  }
+  for (const owner of owners) addProject(owner.project, exists ? file : null, state);
+  return workspaces.some((dir) => file.startsWith(`${dir}/`));
+};
+
+/** Whether a removed tsconfig still has TypeScript without compiler-proven ownership. */
+const strandedConfig = (root, file, records) => {
+  const dir = path.dirname(path.join(root, file));
+  return fs.existsSync(dir) && sourceFiles(dir, root).filter((source) => TS_SOURCE.test(source)).some((source) => {
+    return !sourceOwners(source, records).some((owner) => owner.files.has(pathKey(source)));
+  });
+};
+
+/** The whole-tree scan a broad impact triggers: every discovered program, stranded removals, and the no-program case. */
+const broadScan = (root, selected, inventory, state) => {
+  const { projects, errors, records } = state;
+  for (const record of records.values()) addProject(record.project, null, state);
+  for (const file of selected.filter((file) => /(?:^|\/)tsconfig\.json$/.test(file) && !fs.existsSync(path.join(root, file)))) {
+    if (strandedConfig(root, file, records)) errors.push(`GATE_TSC_CONFIG_MISSING removed tsconfig.json still has TypeScript without a retained compiler owner: ${file}`);
+  }
+  if (!projects.size && inventory.some((file) => TS_SOURCE.test(file))) errors.push('GATE_TSC_CONFIG_MISSING configuration/install impact has TypeScript inputs but no tsconfig.json program');
+};
+
+/**
+ * Selected TypeScript keeps its nearest compiler scopes and projects that include it from outside
+ * their own directories. Configuration, install and codegen changes,
+ * or a changed dist workspace, affect the actual discovered programs, including typed consumers.
+ * Only selected existing TypeScript becomes a required program input; generated assets elsewhere
+ * are not turned into source obligations. readProject supplies compiler-resolved fileNames and absolute
+ * reference config paths through the gate's bounded host. An unproved selected owner is an error, never a skip.
+ */
+export function typeImpact(root, files, { deleted = [], readProject } = {}) {
+  root = path.resolve(root);
+  const projects = new Map(), errors = [], removed = new Set(deleted.map((file) => posixPath(file)));
+  const selected = [...new Set(files.map((file) => posixPath(file)))];
+  const workspaces = workspaceDirs(root, manifestAt(root)).filter((dir) => exposesDist(manifestAt(path.join(root, dir))));
+  let broad = selected.some(sharedImpact) || selected.some((file) => TS_SOURCE.test(file) && workspaces.some((dir) => file.startsWith(`${dir}/`)));
+  if (!broad && !selected.some((file) => TS_SOURCE.test(file))) return { projects: [], required: projects, errors };
+  const inventory = sourceFiles(root), configs = inventory.filter((file) => path.basename(file) === 'tsconfig.json');
+  // A source-only check must not load an unrelated side's compiler or broken config. Start at its
+  // nearest scopes (or declared readers), then discover their descendants and reference closure.
+  const seeds = broad ? configs : selected.filter((file) => TS_SOURCE.test(file)).flatMap((file) => {
+    const nearest = nearestProject(root, file);
+    return nearest ? [path.join(root, nearest)] : readerProjects(root, file).map((project) => path.join(root, project));
+  });
+  // Ancestors contribute their reference closure, not all their unrelated descendant projects.
+  const ancestors = selected.filter((file) => TS_SOURCE.test(file)).flatMap((file) => configs.filter((config) => isInside(path.dirname(config), path.resolve(root, file))));
+  const records = projectGraph(root, [...new Set([...ancestors, ...configs.filter((config) => seeds.some((seed) => isInside(path.dirname(seed), config)))])], readProject);
+  const state = { removed, workspaces, projects, errors, records };
+  for (const file of selected) {
+    if (scanSelected(root, file, state)) broad = true;
+  }
+  if (broad) broadScan(root, selected, inventory, state);
+  return { projects: [...projects.keys()].sort(byCodeUnit), required: projects, errors };
+}
+
+/** Selected source must occur in the compiler's actual program, including an imported excluded root. */
+export function requireTypeCoverage(root, project, required, sourceFilesOfProgram) {
+  const measured = new Set(sourceFilesOfProgram.map((file) => pathKey(file.fileName)));
+  const missing = required.filter((file) => !measured.has(pathKey(path.resolve(root, file))));
+  if (missing.length) throw new Error(`GATE_TSC_FILE_EXCLUDED ${project} did not typecheck selected source: ${missing.join(', ')}`);
+}

package/runtime/scripts/gates/type-program.mjs

@@ -0,0 +1,113 @@
+// type-program.mjs - bounded compiler programs, residual-root projections and base overlays for the code gate.
+import fs from 'node:fs';
+import path from 'node:path';
+import { sha256 } from '../../engine/digest.mjs';
+import { pathKey, posixPath } from '../lib/path-key.mjs';
+import { readTypePrograms, requireTypeCoverage } from './type-impact.mjs';
+
+const TSC_BOUND = 'bounded-residual-v2';
+/** A diagnostic as {path, line, code, message, key}; the key drops the position and the absolute root. */
+function tscFinding(ts, diagnostic, root) {
+  const rootPaths = [path.resolve(root), posixPath(path.resolve(root))];
+  const scrub = (text) => rootPaths.reduce((acc, p) => acc.split(p).join('<ROOT>'), text);
+  const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n').split('\n')[0];
+  const file = diagnostic.file ? posixPath(path.relative(root, diagnostic.file.fileName)) : null;
+  const line = diagnostic.file && diagnostic.start !== undefined ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start).line + 1 : null;
+  return { engine: 'tsc', rule: `TS${diagnostic.code}`, path: file, line, message, key: `${file ?? '-'}|TS${diagnostic.code}|${scrub(message).replace(/\s+/g, ' ').trim()}` };
+}
+const errorsOf = (ts, diagnostics, root) => diagnostics.filter((d) => d.category === ts.DiagnosticCategory.Error).map((d) => tscFinding(ts, d, root));
+const programDiagnostics = (program) => [...program.getConfigFileParsingDiagnostics(), ...program.getOptionsDiagnostics(), ...program.getGlobalDiagnostics(), ...program.getSyntacticDiagnostics(), ...program.getSemanticDiagnostics()];
+const NO_OUTPUT = { noEmit: true, composite: false, declaration: false, declarationMap: false, emitDeclarationOnly: false, sourceMap: false };
+
+/** Keep config/reference errors on the original roots; TypeScript omits some reference checks on zero-root programs. */
+function configurationDiagnostics(ts, parsed, sys) {
+  const options = { ...parsed.options, ...NO_OUTPUT, incremental: false, preserveSymlinks: true };
+  const program = ts.createProgram({ rootNames: parsed.fileNames, options, projectReferences: parsed.projectReferences, host: boundHost(ts, ts.createCompilerHost(options), sys) });
+  return [...ts.getConfigFileParsingDiagnostics(parsed), ...program.getOptionsDiagnostics(), ...program.getGlobalDiagnostics()];
+}
+
+// Deduplicate repeated program context, retaining distinct positions for the base comparison's diagnostic multiset.
+const uniqueFindings = (ts, diagnostics, root) => errorsOf(ts, ts.sortAndDeduplicateDiagnostics(diagnostics), root);
+
+/**
+ * `base` (a ts.sys shape) answering only for paths inside `bound`, TypeScript's lib directory and the `allow`ed files; realpath
+ * is the identity. Every program of the gate reads through one, so nothing above the app root satisfies an import.
+ */
+export function boundedSys(ts, bound, base = ts.sys, allow = []) {
+  const roots = [pathKey(bound), pathKey(path.dirname(ts.getDefaultLibFilePath({})))];
+  const extra = new Set(allow.map((p) => pathKey(p)));
+  const inside = (p) => { const key = pathKey(p); return extra.has(key) || roots.some((r) => key === r || key.startsWith(`${r}/`)); };
+  return { ...base,
+    fileExists: (p) => inside(p) && base.fileExists(p),
+    directoryExists: (p) => inside(p) && base.directoryExists(p),
+    readFile: (p, encoding) => (inside(p) ? base.readFile(p, encoding) : undefined),
+    getDirectories: (p) => (inside(p) ? base.getDirectories(p) : []),
+    readDirectory: (dir, ext, exclude, include, depth) => (inside(dir) ? base.readDirectory(dir, ext, exclude, include, depth).filter(inside) : []),
+    realpath: (p) => p,
+    onUnRecoverableConfigFileDiagnostic: () => {} };
+}
+/** The compiler host of `host` rewired onto a bounded sys: every lookup, and every source file, goes through it. */
+function boundHost(ts, host, sys) {
+  return Object.assign(host, {
+    fileExists: sys.fileExists, directoryExists: sys.directoryExists, readFile: sys.readFile, getDirectories: sys.getDirectories, realpath: sys.realpath,
+    getSourceFile: (fileName, languageVersion) => { const text = sys.readFile(fileName); return text === undefined ? undefined : ts.createSourceFile(fileName, text, languageVersion); },
+  });
+}
+/**
+ * The head of one project, bounded to `bound`: original config diagnostics plus incremental residual groups. Each group's
+ * buildinfo lives in the worktree's git dir (the one outside-bound file its host may read). The incremental host's versioned
+ * getSourceFile reads through the same bound.
+ */
+export function headTsc(ts, root, project, { bound, cache, required = [] }) {
+  const sys = boundedSys(ts, bound), measured = [];
+  const { parsed, groups } = readTypePrograms(ts, root, project, sys);
+  const diagnostics = configurationDiagnostics(ts, parsed, sys);
+  for (const group of groups) {
+    const buildInfo = path.join(cache.worktree, 'tsbuildinfo', `${sha256([TSC_BOUND, project, group.project, ts.version, JSON.stringify(group.rootNames), sys.readFile(path.resolve(root, group.project))].join('\0')).slice(0, 24)}.tsbuildinfo`);
+    fs.mkdirSync(path.dirname(buildInfo), { recursive: true });
+    const hostSys = boundedSys(ts, bound, ts.sys, [buildInfo]);
+    const options = { ...group.parsed.options, ...NO_OUTPUT, incremental: true, tsBuildInfoFile: buildInfo, preserveSymlinks: true };
+    const program = ts.createIncrementalProgram({ rootNames: group.rootNames, options, projectReferences: group.parsed.projectReferences, host: ts.createIncrementalCompilerHost(options, hostSys) });
+    measured.push(...program.getProgram().getSourceFiles());
+    diagnostics.push(...programDiagnostics(program));
+    program.emit();
+  }
+  requireTypeCoverage(root, project, required, measured);
+  return uniqueFindings(ts, diagnostics, root);
+}
+/**
+ * The base program of one project, read-only: a host whose files are the working tree's except every path the delta changed,
+ * which reads its base blob (an added or renamed-to file does not exist, a deleted or renamed-from one comes back). A base
+ * finding on a rename source is keyed at its new path. Bounded to `bound` like the head. Recomputed only when head has errors;
+ * the working install and generated inputs are not proved by a shared (base, project) diagnostic cache.
+ */
+export function baseTsc(ts, root, project, { bound, delta, readBase }) {
+  const abs = (rel) => posixPath(path.resolve(root, rel));
+  const overlay = new Map([...delta.changed, ...delta.deleted].map((rel) => [abs(rel), rel]));
+  for (const rel of delta.added) overlay.set(abs(rel), rel);
+  const absent = (rel) => delta.added.has(rel) || delta.renamed.has(rel);
+  const read = (fileName) => {
+    const rel = overlay.get(posixPath(path.resolve(fileName)));
+    if (rel === undefined) return ts.sys.readFile(fileName);
+    return absent(rel) ? undefined : readBase(rel) ?? undefined;
+  };
+  const exists = (fileName) => { const rel = overlay.get(posixPath(path.resolve(fileName))); return rel === undefined ? ts.sys.fileExists(fileName) : !absent(rel) && readBase(rel) !== null; };
+  const deletedInputs = [...delta.deleted].map((rel) => path.resolve(root, rel));
+  const sys = boundedSys(ts, bound, { ...ts.sys, readFile: read, fileExists: exists,
+    readDirectory: (dir, ext, exclude, include, depth) => [...ts.sys.readDirectory(dir, ext, exclude, include, depth).filter((f) => exists(f)),
+      ...deletedInputs.filter((f) => (!ext || ext.some((suffix) => f.endsWith(suffix))) && posixPath(f).startsWith(`${posixPath(path.resolve(dir))}/`))] });
+  // A newly added project has no base program to compare, rather than an unreadable required base config.
+  if (!sys.fileExists(path.resolve(root, project))) return [];
+  const { parsed, groups } = readTypePrograms(ts, root, project, sys);
+  const diagnostics = configurationDiagnostics(ts, parsed, sys);
+  for (const group of groups) {
+    const options = { ...group.parsed.options, ...NO_OUTPUT, incremental: false, preserveSymlinks: true };
+    const host = boundHost(ts, ts.createCompilerHost(options), sys);
+    const program = ts.createProgram({ rootNames: group.rootNames, options, projectReferences: group.parsed.projectReferences, host });
+    diagnostics.push(...programDiagnostics(program));
+  }
+  const movedTo = new Map([...delta.renamed].map(([to, from]) => [from, to]));
+  const moved = (finding) => (finding.path && movedTo.has(finding.path)
+    ? { ...finding, path: movedTo.get(finding.path), key: `${movedTo.get(finding.path)}${finding.key.slice(finding.path.length)}` } : finding);
+  return uniqueFindings(ts, diagnostics, root).map(moved);
+}

package/runtime/scripts/guards/assigned-command.mjs

@@ -0,0 +1,12 @@
+// assigned-command.mjs - the command a parsed simple command really runs. PowerShell's `$p = Get-Process ...` and
+// `$h = [Environment]::GetEnvironmentVariables()` parse as a command named '' (or '=get-process') whose arguments start
+// with '=': the assigned command is the program, and the assignment words drop.
+export function assignedCommand(c) {
+  const w = [c.program, ...c.args];
+  let at = 0;
+  while (at < w.length && (w[at] === '' || w[at] === '=')) at += 1;
+  if (at === 0 && !String(w[0]).startsWith('=')) return c;
+  const program = String(w[at] ?? '').replace(/^=/, '');
+  // Native programs are lowercased by the parser; a [Type]::Method word keeps its case for the matcher.
+  return { ...c, program: program.startsWith('[') ? program : program.toLowerCase(), args: w.slice(at + 1) };
+}

package/runtime/scripts/guards/call-rights.mjs

@@ -0,0 +1,47 @@
+import { findInOrder } from '../lib/in-order.mjs';
+import { criticWriteVerdict } from './critic-reach.mjs';
+import { fileWriteVerdict, redirectTargetsOf, runtimeRootOf, writeTargetsOf } from './rights.mjs';
+import { policyVerdict } from './command-policy.mjs';
+import { kernelSeatCallVerdict } from './kernel-seat.mjs';
+
+// scripts/guards/call-rights.mjs — the rights refusals of one shell or file call: the file zones, the Kernel seat, the command policy.
+/** The refusal of one file write for the rights role, or null: the zone declaration loads only for a role that can be refused. */
+export async function fileRightsVerdict({ role, filePath, tool = 'Edit', edit = null, guard = null, shell = false }) {
+  if (role === 'critic') return criticWriteVerdict({ filePath, guard, tool });
+  if ((role !== 'supervisor' && role !== 'op') || !runtimeRootOf(filePath)) return null;
+  let zone = { runtimeRoot: runtimeRootOf(filePath) };
+  if (role === 'supervisor') {
+    const pz = await import('./protected-zone.mjs');
+    zone = { ...pz.zoneOfPath(filePath), catalogNames: pz.catalogNames };
+  }
+  return fileWriteVerdict({ role, filePath, tool, edit, guard, zone, shell });
+}
+
+/** The rights refusal of one parsed shell call: its commands (policyVerdict) and the files they write (fileRightsVerdict). */
+export const policyToolVerdict = (command, verdict) => {
+  const whole = [command.word ?? command.program, ...command.args].join(' ');
+  return { tool: command.program, ...verdict, command: verdict.command === whole ? command.args.join(' ').slice(0, 200) : verdict.command };
+};
+
+export async function rightsOfCall({ commands, command, cwd, ctx, guard }) {
+  if (!ctx.role) return null;
+  // The file rights are the more specific refusal (a write into the protected zone, an op writing the runtime checkout): they come before the generic command policy.
+  if (ctx.role === 'supervisor' || ctx.role === 'op' || ctx.role === 'critic') {
+    // The Critic's writer programs are judged whole by the command policy (their content words are not paths): only its redirections are targets here.
+    const targets = [...(ctx.role === 'critic' ? [] : commands.flatMap((c) => writeTargetsOf(c))), ...redirectTargetsOf(command, cwd)];
+    let refusal = null;
+    await findInOrder(targets, async (filePath) => {
+      const v = await fileRightsVerdict({ role: ctx.role, filePath, tool: 'shell', guard, shell: true });
+      if (v) refusal = { tool: 'shell', ...v };
+      return Boolean(v);
+    });
+    if (refusal) return refusal;
+  }
+  const seat = kernelSeatCallVerdict({ role: ctx.role, command, cwd });
+  if (seat) return seat;
+  for (const c of commands) {
+    const v = policyVerdict({ role: ctx.role, command: c, guard, handle: ctx.handle, lockOwner: ctx.lockOwner, policy: ctx.policy });
+    if (v) return policyToolVerdict(c, v);
+  }
+  return null;
+}