carrick 0.3.102 → 0.3.103

package/sidecar/dist/src/capture/check-probe.js

@@ -23,6 +23,11 @@
  * at compare time (ts_check type-checker `unwrapGraphqlPayload`, deleted in
  * WP8); the type-level port here is its v2-native equivalent.
  *
+ * GraphQL pairs also read the consumer's `__typename` as optional, at any depth
+ * (carrick#1759): the server adds that meta-field to every object a selection
+ * asks for, so a resolver's return type never states it, while a consumer type
+ * generated from a document that selects it declares it required.
+ *
  * Seam: node builtins + `typescript` + this bundle only. No imports needed here.
  */
 /**
@@ -172,12 +177,36 @@ export function buildProbe(spec, packageOf) {
         push(`type GqlPayloadKeys<T> = { [K in keyof T]-?: [GqlObjLike<T[K]>] extends [true] ? K : never }[keyof T];`);
         push(`type GqlSingleKey<K> = [K] extends [never] ? never : ([GqlIsUnion<K>] extends [false] ? K : never);`);
         push(`type GqlPayloadOf<S> = [S] extends [readonly unknown[]] ? never : [GqlIsUnion<S>] extends [true] ? never : [S] extends [object] ? ([GqlSingleKey<GqlPayloadKeys<S>>] extends [never] ? never : S[GqlSingleKey<GqlPayloadKeys<S>> & keyof S]) : never;`);
-        push(`type GqlComparand = [Sent] extends [Expected] ? Sent : ([GqlPayloadOf<Sent>] extends [never] ? Sent : GqlPayloadOf<Sent>);`);
+        // carrick#1759: the server supplies `__typename` on every object a
+        // selection asks for, so the consumer's `__typename` is read as OPTIONAL,
+        // at any depth. It keeps its declared type: a producer that states a
+        // different one is still a mismatch, and tsc stays the judge of that.
+        //
+        //   - only an object that declares `__typename` is rebuilt, through one
+        //     anonymous mapped type, so modifiers survive, the field walk sees an
+        //     object root, and a headline prints its members, not a helper name;
+        //   - arrays and tuples map homomorphically, so they stay arrays, and a
+        //     function member is kept whole (a mapped function loses its call
+        //     signature and would accept anything);
+        //   - the depth bound ends the expansion; below it the consumer type is
+        //     compared as declared, which can only keep a mismatch;
+        //   - `GqlExpected` keeps the declared type whenever relaxing changes
+        //     nothing observable, so a consumer with no `__typename` to relax is
+        //     judged, and named in the headline, exactly as before.
+        //
+        // The envelope short-circuit below tests the RELAXED consumer: a bare
+        // payload with one object-shaped property would otherwise fail it on
+        // `__typename` alone and unwrap onto that property.
+        push(`type GqlDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];`);
+        push(`type GqlTypenameParts<T, D extends number> = { [K in keyof T as K extends '__typename' ? never : K]: GqlTypenameOptional<T[K], GqlDepth[D]> } & { [K in keyof T as K extends '__typename' ? K : never]?: T[K] };`);
+        push(`type GqlTypenameOptional<T, D extends number = 16> = [D] extends [never] ? T : T extends (...args: any[]) => any ? T : T extends object ? ('__typename' extends keyof T ? { [K in keyof GqlTypenameParts<T, D>]: GqlTypenameParts<T, D>[K] } : { [K in keyof T]: GqlTypenameOptional<T[K], GqlDepth[D]> }) : T;`);
+        push(`type GqlExpected = [GqlTypenameOptional<Expected>] extends [Expected] ? Expected : GqlTypenameOptional<Expected>;`);
+        push(`type GqlComparand = [Sent] extends [GqlExpected] ? Sent : ([GqlPayloadOf<Sent>] extends [never] ? Sent : GqlPayloadOf<Sent>);`);
         gateLines.set(push(`type _G_comparand_any = Assert<Not<IsAny<GqlComparand>>>;`), 'sent:any');
         gateLines.set(push(`type _G_comparand_unknown = Assert<Not<IsUnknown<GqlComparand>>>;`), 'sent:unknown');
         gateLines.set(push(`type _G_comparand_never = Assert<Not<IsNever<GqlComparand>>>;`), 'sent:never');
         push(`declare const sentComparand: GqlComparand;`);
-        assignmentLine = push(`const expected: Expected = sentComparand;`);
+        assignmentLine = push(`const expected: GqlExpected = sentComparand;`);
     }
     else {
         assignmentLine = push(`const expected: Expected = sent;`);

package/sidecar/dist/src/capture/check-workspace.d.ts

@@ -14,6 +14,7 @@
  */
 import type { CheckStubInput } from './api.js';
 import type { ProbePlan } from './check-probe.js';
+import { WriteGuard } from './guarded-fs.js';
 export interface AssembledStub {
     serviceName: string;
     /** Workspace package dir under packages/ (== the @carrick/<dir> suffix). */
@@ -23,6 +24,8 @@ export interface AssembledStub {
 }
 export interface AssembledWorkspace {
     workspaceDir: string;
+    /** Every write and the clean-up are held to `workspaceDir` (carrick#1748). */
+    guard: WriteGuard;
     probesDir: string;
     /** Relative (forward-slash) probes dir, e.g. packages/carrick-probes. */
     probesRel: string;

package/sidecar/dist/src/capture/check-workspace.js

@@ -13,8 +13,8 @@
  * Seam: node builtins + this bundle only.
  */
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
+import { WriteGuard } from './guarded-fs.js';
 const PROBES_PACKAGE = 'carrick-probes';
 function parseVersion(v) {
     const core = v.replace(/^[^\d]*/, '').split('-')[0].split('+')[0];
@@ -108,13 +108,12 @@ function packageDirOf(packageName) {
 }
 /** Create the scratch workspace and copy in the stub packages. */
 export function assembleWorkspace(opts) {
-    const root = opts.workspaceRoot ?? os.tmpdir();
-    fs.mkdirSync(root, { recursive: true });
-    const workspaceDir = fs.mkdtempSync(path.join(root, 'carrick-check-v2-'));
+    // A fresh directory under the caller's root (the OS temp dir by default).
+    const { dir: workspaceDir, guard } = WriteGuard.scratch('carrick-check-v2-', opts.workspaceRoot);
     const packagesDir = path.join(workspaceDir, 'packages');
-    fs.mkdirSync(packagesDir, { recursive: true });
-    fs.writeFileSync(path.join(workspaceDir, '.npmrc'), NPMRC);
-    fs.writeFileSync(path.join(workspaceDir, 'pnpm-workspace.yaml'), 'packages:\n  - "packages/*"\n');
+    guard.mkdir(packagesDir);
+    guard.writeFile(path.join(workspaceDir, '.npmrc'), NPMRC);
+    guard.writeFile(path.join(workspaceDir, 'pnpm-workspace.yaml'), 'packages:\n  - "packages/*"\n');
     const assembled = [];
     const dependencySets = [];
     const svcToPkg = new Map();
@@ -124,10 +123,7 @@ export function assembleWorkspace(opts) {
         const packageName = readStubPackageName(stub.stub_dir);
         const packageDir = packageDirOf(packageName);
         const dest = path.join(packagesDir, packageDir);
-        fs.cpSync(stub.stub_dir, dest, {
-            recursive: true,
-            filter: (src) => !src.split(path.sep).includes('node_modules'),
-        });
+        guard.copyTree(stub.stub_dir, dest, (src) => !src.split(path.sep).includes('node_modules'));
         assembled.push({ serviceName: stub.service_name, packageDir, packageName });
         dependencySets.push({ dependencies: readStubDependencies(stub.stub_dir) });
         svcToPkg.set(stub.service_name, packageName);
@@ -136,26 +132,27 @@ export function assembleWorkspace(opts) {
     }
     // Root manifest carries the semver-dedupe overrides.
     const overrides = computeDedupeOverrides(dependencySets);
-    fs.writeFileSync(path.join(workspaceDir, 'package.json'), JSON.stringify({
+    guard.writeFile(path.join(workspaceDir, 'package.json'), JSON.stringify({
         name: 'carrick-check-workspace',
         version: '0.0.0',
         private: true,
         ...(Object.keys(overrides).length > 0 ? { pnpm: { overrides } } : {}),
     }, null, 2) + '\n');
     const probesDir = path.join(packagesDir, PROBES_PACKAGE);
-    fs.mkdirSync(path.join(probesDir, 'probes'), { recursive: true });
+    guard.mkdir(path.join(probesDir, 'probes'));
     const probeDeps = {};
     for (const stub of assembled)
         probeDeps[stub.packageName] = 'workspace:*';
-    fs.writeFileSync(path.join(probesDir, 'package.json'), JSON.stringify({
+    guard.writeFile(path.join(probesDir, 'package.json'), JSON.stringify({
         name: PROBES_PACKAGE,
         version: '0.0.0',
         private: true,
         dependencies: probeDeps,
     }, null, 2) + '\n');
-    fs.writeFileSync(path.join(probesDir, 'tsconfig.json'), CHECKER_TSCONFIG);
+    guard.writeFile(path.join(probesDir, 'tsconfig.json'), CHECKER_TSCONFIG);
     return {
         workspaceDir,
+        guard,
         probesDir,
         probesRel: `packages/${PROBES_PACKAGE}`,
         stubs: assembled,
@@ -172,7 +169,7 @@ export function assembleWorkspace(opts) {
 /** Write the generated probe files into the assembled probes package. */
 export function writeProbes(ws, plans) {
     for (const plan of plans) {
-        fs.writeFileSync(path.join(ws.probesDir, 'probes', plan.fileName), plan.source);
+        ws.guard.writeFile(path.join(ws.probesDir, 'probes', plan.fileName), plan.source);
     }
 }
 const NPMRC = [

package/sidecar/dist/src/capture/check.js

@@ -214,7 +214,7 @@ export async function runCheck(opts, onProgress) {
             ...unresolved,
         ]);
         if (cleanup)
-            safeRm(ws.workspaceDir);
+            safeRm(ws);
         return {
             success: false,
             workspace_dir: cleanup ? '' : ws.workspaceDir,
@@ -254,7 +254,7 @@ export async function runCheck(opts, onProgress) {
             ...unresolved,
         ]);
         if (cleanup)
-            safeRm(ws.workspaceDir);
+            safeRm(ws);
         return {
             success: false,
             workspace_dir: cleanup ? '' : ws.workspaceDir,
@@ -306,7 +306,7 @@ export async function runCheck(opts, onProgress) {
     ]);
     const workspaceDirOut = cleanup ? '' : ws.workspaceDir;
     if (cleanup)
-        safeRm(ws.workspaceDir);
+        safeRm(ws);
     return {
         success: true,
         workspace_dir: workspaceDirOut,
@@ -453,9 +453,9 @@ function planPairs(opts, packageOf) {
 function fnvOfSpec(spec) {
     return buildProbe(spec, (s) => `@carrick/${s}`).pairId;
 }
-function safeRm(dir) {
+function safeRm(ws) {
     try {
-        fs.rmSync(dir, { recursive: true, force: true });
+        ws.guard.remove(ws.workspaceDir);
     }
     catch {
         /* best effort */

package/sidecar/dist/src/capture/deep-walk.js

@@ -17,7 +17,10 @@ import ts from 'typescript';
 /** Cap on findings reported per alias. The FIRST one is what the check phase
  * pre-gates on, so verdicts never depend on this number; the rest are there to
  * tell a reader which fields are `any` (carrick#376), and a type with more
- * than this many is already better described by "this type is not typed". */
+ * than this many is already better described by "this type is not typed".
+ * The scanner mirrors it (`CAPTURE_FINDINGS_CAP` in
+ * `src/engine/type_compat_v2.rs`): a record this long may have stopped
+ * listing, so it cannot vouch for every position (carrick#1752). */
 const MAX_DEEP_FINDINGS = 32;
 /**
  * Depth-bounded structural walk for a disqualifying top type at ANY depth:
@@ -97,6 +100,16 @@ function walkTopTypes(root, program, checker, location, flagOf) {
     // about the whole type and makes any further finding meaningless.
     const found = [];
     let exhausted = false;
+    // One finding per kind and position, under the cap. Two union members that
+    // both type `x` reach the same position twice.
+    const named = new Set();
+    const note = (kind, path) => {
+        const key = `${kind}\u0000${path}`;
+        if (named.has(key) || found.length >= MAX_DEEP_FINDINGS)
+            return;
+        named.add(key);
+        found.push({ kind, path });
+    };
     const walk = (t, path, depth) => {
         // Genuine cycle handling — NOT fail-open. `t` is already on the walk stack
         // (or was fully explored earlier), so the owning frame completes it;
@@ -107,8 +120,25 @@ function walkTopTypes(root, program, checker, location, flagOf) {
         // any shallower re-entry — so `seen` never memoizes a truncated visit as
         // clean. And a type fully explored clean at depth d1 is clean at any d2 < d1
         // (the shallower reach is a superset of the deeper), so reusing it is safe.
-        if (exhausted || seen.has(t))
+        if (exhausted)
+            return;
+        if (seen.has(t)) {
+            // A type met before has nothing left to walk, but a top type is a leaf
+            // that sits at every position typed with it, and `any` and `unknown`
+            // are intrinsics: the compiler hands out one object for each, however
+            // many members hold it. So this position is named too. Without it the
+            // record named the first `unknown` and the first `any` and nothing after
+            // them, and a member the source declares `unknown` hid a later one that
+            // an unresolved import left (carrick#1752). An object type met again is
+            // one declaration reached twice, and the first path already named
+            // every top type inside it, with its cause. The first finding, which
+            // the check phase pre-gates on, does not move: a repeat always follows
+            // the first meeting.
+            const kind = depth > 0 ? flagOf(t) : undefined;
+            if (kind)
+                note(kind, path);
             return;
+        }
         // Budget exhaustion FAILS CLOSED. Returning "clean" here would let an
         // `any` buried past the depth/node budget read compatible — the fail-open
         // cliff a bigger number only relocates. Instead abstain: the alias demotes
@@ -140,8 +170,7 @@ function walkTopTypes(root, program, checker, location, flagOf) {
         if (depth > 0) {
             const kind = flagOf(t);
             if (kind) {
-                if (found.length < MAX_DEEP_FINDINGS)
-                    found.push({ kind, path });
+                note(kind, path);
                 return;
             }
         }
@@ -170,16 +199,20 @@ function walkTopTypes(root, program, checker, location, flagOf) {
                 return;
         }
         // Type arguments: arrays, tuples, Promise<T>, Map<K, V>, ...
-        if (t.objectFlags & ts.ObjectFlags.Reference) {
-            const args = checker.getTypeArguments(t);
-            for (let i = 0; i < args.length; i++) {
-                walk(args[i], `${path}<${i}>`, depth + 1);
-                if (exhausted)
-                    return;
-            }
+        const args = t.objectFlags & ts.ObjectFlags.Reference
+            ? checker.getTypeArguments(t)
+            : [];
+        for (let i = 0; i < args.length; i++) {
+            walk(args[i], `${path}<${i}>`, depth + 1);
+            if (exhausted)
+                return;
         }
-        // Index signatures: { [k: string]: T }, Record<string, T>.
+        // Index signatures: { [k: string]: T }, Record<string, T>. An array's
+        // number index is its element type argument again, the position walked
+        // just above under `<0>`: walking it twice would name one element twice.
         for (const info of checker.getIndexInfosOfType(t)) {
+            if (args.includes(info.type))
+                continue;
             walk(info.type, `${path}[index]`, depth + 1);
             if (exhausted)
                 return;

package/sidecar/dist/src/capture/deno-project.d.ts

@@ -1,5 +1,6 @@
 /** Deno owns module resolution; both compiler frontends consume its graph. */
 import ts from 'typescript';
+import { WriteGuard } from './guarded-fs.js';
 export interface DenoConfig {
     configPath: string;
     workspaceRoot: string;
@@ -48,5 +49,5 @@ export declare class DenoProject {
     /** Turn a Deno npm alias into its real package export, with the exact pin. */
     private externalName;
     /** Relocate Deno's per-file resolutions into the portable declaration tree. */
-    rewrite(typesDir: string, files: string[], sourceByEmitted: Map<string, string>): number;
+    rewrite(guard: WriteGuard, typesDir: string, files: string[], sourceByEmitted: Map<string, string>): number;
 }

package/sidecar/dist/src/capture/deno-project.js

@@ -6,6 +6,7 @@ import { pathToFileURL, fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { rewriteSpecifiers } from './specifiers.js';
+import { WriteGuard } from './guarded-fs.js';
 function readConfig(file) {
     const parsed = ts.parseConfigFileTextToJson(file, fs.readFileSync(file, 'utf8'));
     if (parsed.error)
@@ -104,7 +105,13 @@ export class DenoProject {
         this.repoRoot = repoRoot;
         const cache = path.join(config.workspaceRoot, '.carrick', 'deno', createHash('sha256').update(path.resolve(repoRoot)).digest('hex').slice(0, 16));
         this.cacheDir = cache;
-        fs.mkdirSync(cache, { recursive: true });
+        // The graph root lives within the service so compilerOptions.types uses
+        // that member's import-map scope, just like the real source files do.
+        const entry = path.join(repoRoot, '.carrick', 'deno', 'graph.ts');
+        // Its cache and its graph root are the only places a Deno project writes,
+        // both inside `.carrick/deno` (carrick#1748).
+        const guard = WriteGuard.of({ dirs: [cache, path.dirname(entry)], protect: [repoRoot, config.workspaceRoot] });
+        guard.mkdir(cache);
         const raw = { ...config.compilerOptions };
         const libs = Array.isArray(raw.lib) ? raw.lib : ['deno.window'];
         const denoLibs = libs.filter(l => l.startsWith('deno.'));
@@ -138,24 +145,21 @@ export class DenoProject {
                     (ts.isInterfaceDeclaration(s) && s.name.text === 'ImportMeta')).map(s => s.getFullText(source)).join('\n');
             }
             const globalPath = path.join(cache, 'runtime.d.ts');
-            fs.writeFileSync(globalPath, text);
+            guard.writeFile(globalPath, text);
             this.globals.push(globalPath);
         }
-        // The graph root lives within the service so compilerOptions.types uses
-        // that member's import-map scope, just like the real source files do.
-        const entry = path.join(repoRoot, '.carrick', 'deno', 'graph.ts');
-        fs.mkdirSync(path.dirname(entry), { recursive: true });
+        guard.mkdir(path.dirname(entry));
         const roots = this.parsed.fileNames.map(f => pathToFileURL(f).href);
         const extraTypes = config.compilerOptions.types;
         if (Array.isArray(extraTypes))
             roots.push(...extraTypes.filter((t) => typeof t === 'string'));
-        fs.writeFileSync(entry, roots.map(s => `import ${JSON.stringify(s)};`).join('\n'));
+        guard.writeFile(entry, roots.map(s => `import ${JSON.stringify(s)};`).join('\n'));
         let graph;
         try {
             graph = JSON.parse(runDeno(['info', '--json', '--frozen', '--node-modules-dir=none', '--config', config.configPath, entry], repoRoot));
         }
         finally {
-            fs.rmSync(entry, { force: true });
+            guard.remove(entry);
         }
         if (!Array.isArray(graph.modules))
             throw new Error('Unsupported deno info JSON: missing modules array');
@@ -181,8 +185,8 @@ export class DenoProject {
                     continue;
                 }
                 local = path.join(cache, 'remote', createHash('sha256').update(module.specifier).digest('hex') + extension);
-                fs.mkdirSync(path.dirname(local), { recursive: true });
-                fs.copyFileSync(module.local, local);
+                guard.mkdir(path.dirname(local));
+                guard.copyFile(module.local, local);
             }
             this.localPaths.set(module.specifier, path.resolve(local));
             this.specifiersByPath.set(path.resolve(local), module.specifier);
@@ -210,7 +214,7 @@ export class DenoProject {
                     this.globals.push(local);
             }
         }
-        fs.writeFileSync(path.join(cache, 'resolution-diagnostics.json'), JSON.stringify(this.diagnostics, null, 2));
+        guard.writeFile(path.join(cache, 'resolution-diagnostics.json'), JSON.stringify(this.diagnostics, null, 2));
         this.parsed.fileNames.push(...this.globals);
     }
     targetPath(resolution, from = this.repoRoot) {
@@ -404,7 +408,7 @@ export class DenoProject {
         return undefined;
     }
     /** Relocate Deno's per-file resolutions into the portable declaration tree. */
-    rewrite(typesDir, files, sourceByEmitted) {
+    rewrite(guard, typesDir, files, sourceByEmitted) {
         let count = 0;
         const emittedBySource = new Map([...sourceByEmitted].map(([rel, source]) => [path.resolve(source), rel]));
         for (const rel of files) {
@@ -427,26 +431,26 @@ export class DenoProject {
                 return relative;
             });
             if (result.rewrites)
-                fs.writeFileSync(file, result.text);
+                guard.writeFile(file, result.text);
             count += result.rewrites;
         }
         const runtime = this.globals.find(file => path.basename(file) === 'runtime.d.ts');
         const runtimeRel = runtime && emittedBySource.get(path.resolve(runtime));
         if (runtimeRel)
-            isolateRuntime(typesDir, files, runtimeRel);
+            isolateRuntime(guard, typesDir, files, runtimeRel);
         const references = this.globals.filter(file => file !== runtime)
             .map(file => emittedBySource.get(path.resolve(file)))
             .filter((file) => file !== undefined)
             .map(file => `/// <reference path=${JSON.stringify('./' + file)} />`);
         if (references.length) {
             const surface = path.join(typesDir, 'surface.d.ts');
-            fs.writeFileSync(surface, references.join('\n') + '\n' + fs.readFileSync(surface, 'utf8'));
+            guard.writeFile(surface, references.join('\n') + '\n' + fs.readFileSync(surface, 'utf8'));
         }
         return count;
     }
 }
 /** Runtime declarations belong to their producer, not the checker's globals. */
-function isolateRuntime(typesDir, files, runtimeRel) {
+function isolateRuntime(guard, typesDir, files, runtimeRel) {
     const runtimePath = path.join(typesDir, runtimeRel);
     const program = ts.createProgram(files.map(file => path.join(typesDir, file)), {
         strict: true, skipLibCheck: true, target: ts.ScriptTarget.ESNext,
@@ -510,7 +514,7 @@ function isolateRuntime(typesDir, files, runtimeRel) {
         for (const edit of edits.sort((a, b) => b.start - a.start))
             text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
         if (edits.length)
-            fs.writeFileSync(file, text);
+            guard.writeFile(file, text);
     }
     while (pending.length) {
         const visit = (node) => {
@@ -545,5 +549,5 @@ function isolateRuntime(typesDir, files, runtimeRel) {
         }
     }
     const text = ts.createPrinter().printFile(ts.factory.updateSourceFile(runtime, statements));
-    fs.writeFileSync(runtimePath, '// Runtime declarations from deno types. Copyright the Deno authors. MIT license.\n/// <reference lib="esnext" />\n' + text + `\nexport { ${[...names].sort().join(', ')} };\n`);
+    guard.writeFile(runtimePath, '// Runtime declarations from deno types. Copyright the Deno authors. MIT license.\n/// <reference lib="esnext" />\n' + text + `\nexport { ${[...names].sort().join(', ')} };\n`);
 }

package/sidecar/dist/src/capture/guarded-fs.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Every file the sidecar writes or deletes goes through a {@link WriteGuard}
+ * (carrick#1748).
+ *
+ * A scan reads the repo it scans and never writes it. carrick#1742 showed how
+ * easily that breaks: the capture self-check reaches the repo's own sources
+ * through a `node_modules` link, and a pass that "only rewrites its own
+ * declarations" rewrote them. Each write site used to be safe only by its own
+ * reasoning. Now each run names the directories it owns (its scratch, the stub
+ * it emits, a runtime cache) and every write and delete is checked against
+ * them, on the RESOLVED path, before it happens.
+ *
+ * Resolution follows the operation:
+ *  - a write lands where the path's links lead, so the whole path is resolved,
+ *    and a path that does not exist yet resolves through its deepest existing
+ *    ancestor (a dangling link resolves through its target);
+ *  - a delete, or a new link, touches the directory entry itself, so only the
+ *    parent is resolved. Unlinking the stub's `node_modules` link is allowed;
+ *    writing through it into the repo's packages is refused.
+ *
+ * `test/no-raw-writes.test.ts` fails when any other source file calls a
+ * mutating `fs` API.
+ */
+import * as fs from 'node:fs';
+/** A write or delete the guard refused, or a root it would not accept. */
+export declare class WriteRefused extends Error {
+    constructor(message: string);
+}
+export interface WriteRoots {
+    /** Directories a run may write anywhere beneath, each one included. */
+    dirs?: string[];
+    /** Single files a run may write and delete, and nothing beside them. */
+    files?: string[];
+    /**
+     * Trees the run reads: no root may be one of them or contain one. A root
+     * that contained the scanned repo would let a stub's clean-up delete it.
+     */
+    protect?: string[];
+}
+export declare class WriteGuard {
+    private readonly dirs;
+    private readonly files;
+    private readonly protect;
+    private constructor();
+    /** A guard over `roots`. Throws when a root equals or contains a protected tree. */
+    static of(roots: WriteRoots): WriteGuard;
+    /**
+     * A new, empty directory under `parent` (the OS temp dir by default) and a
+     * guard over it alone. `mkdtemp` picks an unused name, so creating it cannot
+     * overwrite anything; `parent` is created when missing.
+     */
+    static scratch(prefix: string, parent?: string): {
+        dir: string;
+        guard: WriteGuard;
+    };
+    /** This guard with more roots, under the same protected trees. */
+    with(roots: Omit<WriteRoots, 'protect'>): WriteGuard;
+    /** A guard over `dir` alone, which must already be writable under this one. */
+    narrow(dir: string): WriteGuard;
+    /** Whether a write to `p` would land inside this guard's roots. */
+    allowsWrite(p: string): boolean;
+    /** Throws unless `p` (a subprocess's working directory, say) lies inside the roots. */
+    assertWithin(p: string): void;
+    writeFile(p: string, data: string | NodeJS.ArrayBufferView): void;
+    /** `mkdir -p`. A directory that already exists is no write and passes unchecked. */
+    mkdir(p: string): void;
+    copyFile(from: string, to: string): void;
+    /** `cp -R`. Links in the source are copied as links, never written through. */
+    copyTree(from: string, to: string, filter?: (source: string) => boolean): void;
+    /** `rm -rf`. A link is removed itself; its target is left alone. */
+    remove(p: string): void;
+    unlink(p: string): void;
+    symlink(target: string, linkPath: string, type?: fs.symlink.Type): void;
+    private holds;
+    private check;
+}