@vibe-agent-toolkit/utils 0.2.0-rc.10 → 0.2.0-rc.12

package/dist/in-order.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Ordered and bounded-parallel iteration over async work — THE replacement for
+ * `await` inside a loop.
+ *
+ * `no-await-in-loop` (Sonar S9382) is on repo-wide, and it is right about the
+ * default: independent work belongs in `Promise.all` / `mapWithConcurrency`.
+ * When the order IS the contract, say so by name with one of the `*InOrder`
+ * helpers instead of a disable. None of them is written with `async` or with a
+ * loop: each step is chained onto the previous one's promise, so the rule has
+ * nothing to see here and a caller's `await` sits behind a function boundary.
+ *
+ * Every helper starts its callback synchronously and turns a synchronous throw into
+ * a rejection — exactly what the body of an `async` loop does — and a callback may
+ * return a plain value.
+ */
+/** One item's callback: its value and its position in the run. */
+type InOrderCallback<T, R> = (item: T, index: number) => Promise<R> | R;
+/**
+ * Enough parallelism to hide per-call filesystem latency, low enough to stay far
+ * from the default file-descriptor ceiling even with several builds at once.
+ * The default bound of `mapWithConcurrency`, and the bound every population-sized
+ * parallel fs fan-out uses instead of a bare `Promise.all`.
+ */
+export declare const FS_CONCURRENCY = 16;
+/**
+ * `work()` as a promise — its value resolved, a synchronous throw rejected — for a
+ * Promise-shaped API whose body is synchronous. `Promise.try`, until the Node floor
+ * has it. A body that returns a promise is adopted, so its own throw still rejects.
+ */
+export declare function promised<T>(work: () => T): Promise<Awaited<T>>;
+/**
+ * Run `fn` over `items` one at a time, each call starting only after the previous
+ * one settles.
+ *
+ * Reach for it when order is the CONTRACT, not an accident: ordered filesystem
+ * mutation (mkdir before recursing, a later entry deliberately overwriting an
+ * earlier one), first-refusal-wins (the error a user sees must name the FIRST bad
+ * item, deterministically — `Promise.all` rejects with the first in time), a
+ * shared memo/sink/walk-guard whose first use must not race, a report whose line
+ * order is its meaning, or a measurement that must not overlap itself.
+ *
+ * A rejection stops the run there: later items are never started, exactly as
+ * with `await` in `for…of`. Items are pulled lazily from the iterator, so an
+ * array that grows during the run is seen. If the items are independent, use
+ * `Promise.all` or {@link mapWithConcurrency} instead.
+ */
+export declare function forEachInOrder<T>(items: Iterable<T>, fn: InOrderCallback<T, void>): Promise<void>;
+/**
+ * {@link forEachInOrder} that collects each call's result, in input order.
+ *
+ * For a sequential transform whose steps depend on shared state — a resolver that
+ * stages into one root, a cache whose first user must not race — where the caller
+ * also needs every result. Stops at the first rejection, like `forEachInOrder`.
+ */
+export declare function mapInOrder<T, R>(items: Iterable<T>, fn: InOrderCallback<T, R>): Promise<R[]>;
+/**
+ * `Array#every`, in order and awaited: resolves `false` at the first callback that
+ * answers `false`, without starting any later item; resolves `true` when every item
+ * answered `true` (vacuously so for no items).
+ *
+ * The idiom for a loop that used to `break` or `return` early: stop at the first
+ * failure and leave the rest untouched — capture whatever the early exit carried in
+ * a closure. A rejection stops the run too, and rejects.
+ */
+export declare function everyInOrder<T>(items: Iterable<T>, fn: InOrderCallback<T, boolean>): Promise<boolean>;
+/**
+ * `Promise.all`-shaped, but with at most `limit` calls in flight. Results are in
+ * input order whatever order the calls finish in.
+ *
+ * For INDEPENDENT work over a population-sized list — the files in a skill, the
+ * skill directories of a plugin — where a bare `Promise.all` would open one file
+ * descriptor per item at once. Results are returned rather than pushed into a
+ * shared sink from inside the callbacks: concurrent pushes land in finish order,
+ * not input order, so fold the returned array afterwards.
+ *
+ * Rejects with the first rejection in TIME, and stops starting new items once one
+ * has rejected (calls already in flight run to completion). When the error a user
+ * sees must name the first bad item in input order, this is the wrong tool — use
+ * {@link forEachInOrder}.
+ *
+ * @throws RangeError when `limit` is not a whole number of at least 1 — a `NaN`
+ *   or `0` limit would otherwise start no workers and silently resolve holes.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], fn: InOrderCallback<T, R>, limit?: number): Promise<R[]>;
+/**
+ * {@link mapWithConcurrency} for independent read-only work whose failure must
+ * still be the one a sequential loop would have raised: every call settles, then
+ * the rejection of the EARLIEST item by position is rethrown. Results are in
+ * input order.
+ */
+export declare function mapConcurrentFailingInOrder<T, R>(items: readonly T[], fn: InOrderCallback<T, R>): Promise<R[]>;
+export {};
+//# sourceMappingURL=in-order.d.ts.map

package/dist/in-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-order.d.ts","sourceRoot":"","sources":["../src/in-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,kEAAkE;AAClE,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAO9D;AAuCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAClB,EAAE,EAAE,eAAe,CAAC,CAAC,EAAE,IAAI,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAC7B,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAClB,EAAE,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,EAAE,CAAC,CAMd;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAClB,EAAE,EAAE,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EACrC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,EAAE,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EACzB,KAAK,GAAE,MAAuB,GAC7B,OAAO,CAAC,CAAC,EAAE,CAAC,CAuBd;AAID;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,CAAC,EAC9C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,EAAE,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,EAAE,CAAC,CAYd"}

package/dist/in-order.js

@@ -0,0 +1,165 @@
+/**
+ * Ordered and bounded-parallel iteration over async work — THE replacement for
+ * `await` inside a loop.
+ *
+ * `no-await-in-loop` (Sonar S9382) is on repo-wide, and it is right about the
+ * default: independent work belongs in `Promise.all` / `mapWithConcurrency`.
+ * When the order IS the contract, say so by name with one of the `*InOrder`
+ * helpers instead of a disable. None of them is written with `async` or with a
+ * loop: each step is chained onto the previous one's promise, so the rule has
+ * nothing to see here and a caller's `await` sits behind a function boundary.
+ *
+ * Every helper starts its callback synchronously and turns a synchronous throw into
+ * a rejection — exactly what the body of an `async` loop does — and a callback may
+ * return a plain value.
+ */
+/**
+ * Enough parallelism to hide per-call filesystem latency, low enough to stay far
+ * from the default file-descriptor ceiling even with several builds at once.
+ * The default bound of `mapWithConcurrency`, and the bound every population-sized
+ * parallel fs fan-out uses instead of a bare `Promise.all`.
+ */
+export const FS_CONCURRENCY = 16;
+/**
+ * `work()` as a promise — its value resolved, a synchronous throw rejected — for a
+ * Promise-shaped API whose body is synchronous. `Promise.try`, until the Node floor
+ * has it. A body that returns a promise is adopted, so its own throw still rejects.
+ */
+export function promised(work) {
+    try {
+        return Promise.resolve(work());
+    }
+    catch (error) {
+        // Re-raised as-is: the caller's catch must see exactly what `work` threw.
+        return Promise.reject(error);
+    }
+}
+/** Start `fn` now, turning a synchronous throw into a rejection. */
+function settle(fn, item, index) {
+    return promised(() => fn(item, index));
+}
+/**
+ * The shared chain: pull the next item, run `fn`, hand the result to `keepGoing`,
+ * and continue only when it says so. The iterator is closed on an early stop or a
+ * rejection, as `for…of` closes it on `break` or `throw`.
+ */
+function chainInOrder(items, fn, keepGoing) {
+    return new Promise((resolveRun) => {
+        const iterator = items[Symbol.iterator]();
+        let index = 0;
+        const step = () => {
+            const next = iterator.next();
+            if (next.done === true)
+                return Promise.resolve(true);
+            return settle(fn, next.value, index++).then((result) => {
+                const more = keepGoing(result);
+                if (!more)
+                    iterator.return?.();
+                return more ? step() : false;
+            }, (error) => {
+                iterator.return?.();
+                throw error;
+            });
+        };
+        resolveRun(step());
+    });
+}
+/**
+ * Run `fn` over `items` one at a time, each call starting only after the previous
+ * one settles.
+ *
+ * Reach for it when order is the CONTRACT, not an accident: ordered filesystem
+ * mutation (mkdir before recursing, a later entry deliberately overwriting an
+ * earlier one), first-refusal-wins (the error a user sees must name the FIRST bad
+ * item, deterministically — `Promise.all` rejects with the first in time), a
+ * shared memo/sink/walk-guard whose first use must not race, a report whose line
+ * order is its meaning, or a measurement that must not overlap itself.
+ *
+ * A rejection stops the run there: later items are never started, exactly as
+ * with `await` in `for…of`. Items are pulled lazily from the iterator, so an
+ * array that grows during the run is seen. If the items are independent, use
+ * `Promise.all` or {@link mapWithConcurrency} instead.
+ */
+export function forEachInOrder(items, fn) {
+    return chainInOrder(items, fn, () => true).then(() => undefined);
+}
+/**
+ * {@link forEachInOrder} that collects each call's result, in input order.
+ *
+ * For a sequential transform whose steps depend on shared state — a resolver that
+ * stages into one root, a cache whose first user must not race — where the caller
+ * also needs every result. Stops at the first rejection, like `forEachInOrder`.
+ */
+export function mapInOrder(items, fn) {
+    const results = [];
+    return chainInOrder(items, fn, (result) => {
+        results.push(result);
+        return true;
+    }).then(() => results);
+}
+/**
+ * `Array#every`, in order and awaited: resolves `false` at the first callback that
+ * answers `false`, without starting any later item; resolves `true` when every item
+ * answered `true` (vacuously so for no items).
+ *
+ * The idiom for a loop that used to `break` or `return` early: stop at the first
+ * failure and leave the rest untouched — capture whatever the early exit carried in
+ * a closure. A rejection stops the run too, and rejects.
+ */
+export function everyInOrder(items, fn) {
+    return chainInOrder(items, fn, (result) => result);
+}
+/**
+ * `Promise.all`-shaped, but with at most `limit` calls in flight. Results are in
+ * input order whatever order the calls finish in.
+ *
+ * For INDEPENDENT work over a population-sized list — the files in a skill, the
+ * skill directories of a plugin — where a bare `Promise.all` would open one file
+ * descriptor per item at once. Results are returned rather than pushed into a
+ * shared sink from inside the callbacks: concurrent pushes land in finish order,
+ * not input order, so fold the returned array afterwards.
+ *
+ * Rejects with the first rejection in TIME, and stops starting new items once one
+ * has rejected (calls already in flight run to completion). When the error a user
+ * sees must name the first bad item in input order, this is the wrong tool — use
+ * {@link forEachInOrder}.
+ *
+ * @throws RangeError when `limit` is not a whole number of at least 1 — a `NaN`
+ *   or `0` limit would otherwise start no workers and silently resolve holes.
+ */
+export function mapWithConcurrency(items, fn, limit = FS_CONCURRENCY) {
+    if (!Number.isInteger(limit) || limit < 1) {
+        return Promise.reject(new RangeError(`mapWithConcurrency limit must be a whole number of at least 1, got ${String(limit)}`));
+    }
+    const results = Array.from({ length: items.length });
+    let next = 0;
+    let failed = false;
+    const worker = () => {
+        if (failed || next >= items.length)
+            return Promise.resolve();
+        const index = next++;
+        return settle(fn, items[index], index).then((result) => {
+            results[index] = result;
+            return worker();
+        }, (error) => {
+            failed = true;
+            throw error;
+        });
+    };
+    const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+    return Promise.all(workers).then(() => results);
+}
+/**
+ * {@link mapWithConcurrency} for independent read-only work whose failure must
+ * still be the one a sequential loop would have raised: every call settles, then
+ * the rejection of the EARLIEST item by position is rethrown. Results are in
+ * input order.
+ */
+export function mapConcurrentFailingInOrder(items, fn) {
+    return mapWithConcurrency(items, (item, index) => settle(fn, item, index).then((value) => ({ ok: true, value }), (error) => ({ ok: false, error }))).then((outcomes) => outcomes.map((outcome) => {
+        if (!outcome.ok)
+            throw outcome.error;
+        return outcome.value;
+    }));
+}
+//# sourceMappingURL=in-order.js.map

package/dist/in-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-order.js","sourceRoot":"","sources":["../src/in-order.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -23,24 +23,40 @@
  * and has to be an argued edit rather than an unnoticed one.
  */
 export * from './errors/vat-error.js';
+export { RAG_DATABASE_UNREADABLE_CODE, RAG_INDEX_EMPTY_CODE } from './errors/rag-index-empty.js';
+export { ARCHIVE_ENTRY_UNREADABLE_CODE, ARCHIVE_REFUSED_CODE, isArchiveEntryReadRefusal, placeOf as archiveEntryPlace } from './archive/entries.js';
 export * from './path-utils.js';
 export * from './path-containment.js';
 export * from './dirent-kind.js';
 export * from './text-content.js';
 export * from './text-file.js';
 export * from './asset-reference.js';
-export { isFilesystemAccessError, isPathAbsentError } from './errors/errno.js';
-export { copyDirectory, CopyLinkEscapesSourceError, FsLookupCache, transientRefusalClause, } from './fs-utils.js';
-export { DirectorySpellingIndex, fillPathSpellings, fillRealpaths, pathSpellingFrom, realpathFrom, spellingWalkRoot, } from './fs-utils.js';
-export type { AbsenceCause, ComponentMatch, FilenameMatch, PathProbe, PathProbeStats, PathSpelling, PathSpellingRequest, PathSpellingTable, RealpathTable, VerifiedPrefix, } from './fs-utils.js';
+export { FS_FAULT_ERRNOS_BY_CLASS, fsFaultOf, isAlreadyExistsError, isFileInTheWayError, isFinalPathUnanswerableError, isInvalidArgumentError, isNoSuchEntryError, isNotARegularFileError, isPathAbsentError, isProcessGoneError, isRenameContentionError, isSymlinkUnsupportedError, isTimedOutError, isUnresolvableLinkError, isWouldBlockError, LINK_CHAIN_REFUSED_CODE, } from './errors/errno-table.js';
+export type { FsFaultClass, FsFaultFacts } from './errors/errno-table.js';
+export { assertUnresolvableLink, classifyFsFault, everywhere, FS_FAULT_CODE, FS_SIDES, FsFaultError, isCapacityFault, isFsFaultError, isLayoutFault, linkResolutionFault, refusedPathOf, sideWithin, SOURCE_ORIGINS, withFsFault, withFsFaultSync, } from './errors/fs-fault.js';
+export type { FsFaultContext, FsSide, SideOfPath, SourceOrigin } from './errors/fs-fault.js';
+export { fsBoundary } from './errors/fs-boundary.js';
+export { requireConfirmedAbsent, type ConfirmationContext, type ConfirmationProbe } from './errors/confirmed-absent.js';
+export { pathPresent, type PresenceMode } from './errors/path-present.js';
+export { assertLocalChain, type FollowedPathKind, followedKind, followedKindSync, followedRealpath, followedRealpathSync, followedStat, followedStatSync, realpathNative, realpathNativeSync, requireFollowedStat, requireFollowedStatSync, } from './link-following.js';
+export { foldedSegment } from './name-fold.js';
+export { recordSuppressedFault, suppressedFaultsOf } from './errors/suppressed-faults.js';
+export type { FsBoundary, FsRoots } from './errors/fs-boundary.js';
+export { FsLookupCache, transientRefusalClause } from './fs-utils.js';
+export { DirectorySpellingIndex, fillPathSpellings, fillRealpaths, pathSpellingFrom, realpathRowFrom, spellingWalkRoot, } from './fs-utils.js';
+export type { AbsenceCause, ComponentMatch, FilenameMatch, PathProbe, PathProbeStats, PathSpelling, PathSpellingRequest, PathSpellingTable, RealpathFault, RealpathRow, RealpathTable, VerifiedPrefix, } from './fs-utils.js';
 export * from './project-utils.js';
 export { createSymlink, createSymlinkAsync, detachGitEnv, errnoError, INHERITED_GIT_ENV, symlinkCapability, type SymlinkCapability, } from './test-helpers.js';
 export * from './zod-introspection.js';
 export * from './skill-targets.js';
+export { requireTestScratch, TEST_USER_STATE_UNDER } from './test-scratch-guard.js';
 export * from './glob/glob-pattern.js';
 export * from './fs/file-hash.js';
+export { applyTreePlan, applyTreePlanOrLeftover, COPY_LINK_ESCAPES_SOURCE_CODE, copyRegularFile, copyTree, CopyLinkEscapesSourceError, DIRECTORY_WALK_REVISITED_CODE, DirectoryWalkRevisitedError, disposeTempDir, disposeTempDirAfterFailure, disposeTempDirSync, entryIdentities, FollowedWalk, isLinkChainRefusedError, HOST_PATH_FLAVOR, isInsideByIdentity, isParkedTreeEntry, isTreeChangeResidue, planTreeChanges, proveTreeReadable, readRegularFile, makeDirectoryUnder, refuseEscapingLinks, renameFileAtomic, replaceFile, writeFileUnder, sameEntry, TEMP_DIR_OUTSIDE_TMPDIR_CODE, TREE_CLEANUP_INCOMPLETE_CODE, TREE_DEST_HOLDS_SOURCE_CODE, TREE_DEST_NOT_OWNED_CODE, TREE_DEST_OCCUPIED_CODE, TREE_DESTS_OVERLAP_CODE, TREE_ROLLBACK_INCOMPLETE_CODE, TREE_SOURCE_HOLDS_DEST_CODE, treeChain, treeContainment, TreeRollbackIncompleteError, untrustedTextRefusal, untrustedLinkRefusal, isWithinUnder, win32FoldedName, withTempDir, } from './tree-change/index.js';
+export type { ApplyOptions, ApplyOutcome, ApplyResult, CopyOnto, CopyRegularFileOptions, CopyTreeOptions, EntryContainment, EntryKind, EntrySameness, FileContents, Identity, LinkContainmentCheck, LinkPolicy, Ownership, OwnershipVerdict, PlannedAction, PlannedChange, ProveTreeReadableOptions, TempDirOutcome, TreeChange, TreeChangeWarning, TreeFill, TreePlan, TreeRollbackStranded, TreeWalkOptions, } from './tree-change/index.js';
 export { parseWholeNumberAtLeast } from './numeric-args.js';
 export { parseEnvBoolean } from './env-flag.js';
+export { everyInOrder, forEachInOrder, FS_CONCURRENCY, mapConcurrentFailingInOrder, mapInOrder, mapWithConcurrency, promised, } from './in-order.js';
 export { compareCodeUnits } from './compare-code-units.js';
 export { CRAWL_BLOB_POPULATE_ID, CRAWL_CLOSURE_CONTRIBUTE_ID, CRAWL_CLOSURE_RESOLVE_ID, CRAWL_PASS_INSIDE, CRAWL_REGISTRY_ADMIT_ID, CRAWL_REGISTRY_ENUMERATE_ID, CRAWL_REGISTRY_ID_PREFIX, CRAWL_REGISTRY_RESOLVE_LINKS_ID, CRAWL_SHARED_GIT_TRACKER_ID, CRAWL_STORE_READ_ID, CRAWL_STORE_WRITE_ID, CRAWL_STRATA, CRAWL_WALKER_GITIGNORE_ID, CRAWL_WALKER_ID, crawlTimingStart, recordContributorInvocation, recordCrawlPass, recordRegistryPass, recordSharedPass, withContributorStratum, withOuterBracket, type CrawlDriverStratum, type CrawlStratum, type CrawlTimingDump, type CrawlTimingEntry, type CrawlTimingProcess, } from './crawl-timing.js';
 export { ensureTimingDirectory, normalizeTimingDirectory, readTimingProcess, type TimingProcess, writeTimingDump, } from './timing-dump.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,cAAc,uBAAuB,CAAC;AAGtC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,kBAAkB,CAAC;AASjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAG/B,cAAc,sBAAsB,CAAC;AAyCrC,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,aAAa,EACb,sBAAsB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAC;AAIvB,cAAc,oBAAoB,CAAC;AASnC,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,cAAc,wBAAwB,CAAC;AAGvC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAK5D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAgB3D,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,EAC3B,wBAAwB,EACxB,+BAA+B,EAC/B,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,iBAAiB,EACjB,KAAK,aAAa,EAClB,eAAe,GAChB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -25,6 +25,11 @@
 // The base of every error VAT throws on purpose; `code` is what a catch
 // block dispatches on, never `message`.
 export * from './errors/vat-error.js';
+export { RAG_DATABASE_UNREADABLE_CODE, RAG_INDEX_EMPTY_CODE } from './errors/rag-index-empty.js';
+// The code and the one-entry predicate alone: the archive readers are on `./archive` (they load
+// `tar` and `adm-zip`), and a refusal map, or a lane that skips one member, needs only these.
+export { ARCHIVE_ENTRY_UNREADABLE_CODE, ARCHIVE_REFUSED_CODE, isArchiveEntryReadRefusal, placeOf as archiveEntryPlace } from './archive/entries.js';
+// The code alone: its error class is on `./crawl`, and the CLI's refusal map needs only the code.
 // Cross-platform path utilities
 export * from './path-utils.js';
 // The filesystem-backed containment verdict every delete/copy/uninstall sink asks.
@@ -61,7 +66,7 @@ export * from './asset-reference.js';
 //     published too, for the lazy caller that cannot enumerate its targets up
 //     front.
 //   - realpaths — `fillRealpaths` (every canonicalization, once, up front) plus
-//     `realpathFrom`.
+//     `realpathRowFrom`.
 //
 // In both, the row lookup IS the judge: the row is the answer, so there is
 // nothing left to keep internal.
@@ -81,11 +86,21 @@ export * from './asset-reference.js';
 // symptom is a type that cannot be imported, which surfaces the first time
 // someone tries — not a silent break in existing code.
 // The lookups themselves, plus the memo every fill shares.
-export { isFilesystemAccessError, isPathAbsentError } from './errors/errno.js';
-export { copyDirectory, CopyLinkEscapesSourceError, FsLookupCache, transientRefusalClause, } from './fs-utils.js';
+export { FS_FAULT_ERRNOS_BY_CLASS, fsFaultOf, isAlreadyExistsError, isFileInTheWayError, isFinalPathUnanswerableError, isInvalidArgumentError, isNoSuchEntryError, isNotARegularFileError, isPathAbsentError, isProcessGoneError, isRenameContentionError, isSymlinkUnsupportedError, isTimedOutError, isUnresolvableLinkError, isWouldBlockError, LINK_CHAIN_REFUSED_CODE, } from './errors/errno-table.js';
+export { assertUnresolvableLink, classifyFsFault, everywhere, FS_FAULT_CODE, FS_SIDES, FsFaultError, isCapacityFault, isFsFaultError, isLayoutFault, linkResolutionFault, refusedPathOf, sideWithin, SOURCE_ORIGINS, withFsFault, withFsFaultSync, } from './errors/fs-fault.js';
+export { fsBoundary } from './errors/fs-boundary.js';
+export { requireConfirmedAbsent } from './errors/confirmed-absent.js';
+export { pathPresent } from './errors/path-present.js';
+// The one module that asks the kernel to follow a link, each call once the chain beneath `within` is read.
+export { assertLocalChain, followedKind, followedKindSync, followedRealpath, followedRealpathSync, followedStat, followedStatSync, realpathNative, realpathNativeSync, requireFollowedStat, requireFollowedStatSync, } from './link-following.js';
+// The one fold for "are these two names one entry on some volume".
+export { foldedSegment } from './name-fold.js';
+// Faults raised while a failure was being handled, recorded beside it (never on its cause chain).
+export { recordSuppressedFault, suppressedFaultsOf } from './errors/suppressed-faults.js';
+export { FsLookupCache, transientRefusalClause } from './fs-utils.js';
 // The two fill+judge pairs, in the order the note above lists them, plus the
 // lazy index a caller that cannot enumerate its targets up front reaches for.
-export { DirectorySpellingIndex, fillPathSpellings, fillRealpaths, pathSpellingFrom, realpathFrom, spellingWalkRoot, } from './fs-utils.js';
+export { DirectorySpellingIndex, fillPathSpellings, fillRealpaths, pathSpellingFrom, realpathRowFrom, spellingWalkRoot, } from './fs-utils.js';
 // Project root discovery (canonical: config → git → null).
 // CLI-boundary use only — see docs/concepts/roots-and-config.md.
 export * from './project-utils.js';
@@ -101,15 +116,26 @@ export { createSymlink, createSymlinkAsync, detachGitEnv, errnoError, INHERITED_
 export * from './zod-introspection.js';
 // Skill target resolution (cross-platform flat skill install paths)
 export * from './skill-targets.js';
+// The fail-closed guard for user state in a test process
+export { requireTestScratch, TEST_USER_STATE_UNDER } from './test-scratch-guard.js';
 // Glob pattern helpers (isGlob, staticGlobBase, globMagicRemainder)
 export * from './glob/glob-pattern.js';
 // Filesystem hashing (sha256 of raw file bytes)
 export * from './fs/file-hash.js';
+// Tree-change primitive: entry identity (`sameEntry`) for the planner and uninstall; the
+// readable-tree proof and the copy, with the two refusals a following walk raises.
+// The planner and applier every destructive verb goes through, and the file helpers beside them.
+export { applyTreePlan, applyTreePlanOrLeftover, COPY_LINK_ESCAPES_SOURCE_CODE, copyRegularFile, copyTree, CopyLinkEscapesSourceError, DIRECTORY_WALK_REVISITED_CODE, DirectoryWalkRevisitedError, disposeTempDir, disposeTempDirAfterFailure, disposeTempDirSync, entryIdentities, FollowedWalk, isLinkChainRefusedError, HOST_PATH_FLAVOR, isInsideByIdentity, isParkedTreeEntry, isTreeChangeResidue, planTreeChanges, proveTreeReadable, readRegularFile, makeDirectoryUnder, refuseEscapingLinks, renameFileAtomic, replaceFile, writeFileUnder, sameEntry, TEMP_DIR_OUTSIDE_TMPDIR_CODE, TREE_CLEANUP_INCOMPLETE_CODE, TREE_DEST_HOLDS_SOURCE_CODE, TREE_DEST_NOT_OWNED_CODE, TREE_DEST_OCCUPIED_CODE, TREE_DESTS_OVERLAP_CODE, TREE_ROLLBACK_INCOMPLETE_CODE, TREE_SOURCE_HOLDS_DEST_CODE, treeChain, treeContainment, TreeRollbackIncompleteError, untrustedTextRefusal, untrustedLinkRefusal, isWithinUnder, win32FoldedName, withTempDir, } from './tree-change/index.js';
 export { parseWholeNumberAtLeast } from './numeric-args.js';
 // THE reading of an environment variable as a boolean. One implementation
 // because three switches each had their own `!== '0'` comparison and none of
 // them turned off for `=false`.
 export { parseEnvBoolean } from './env-flag.js';
+// Ordered (`forEachInOrder`, `mapInOrder`, `everyInOrder`) and bounded-parallel
+// (`mapWithConcurrency`, `mapConcurrentFailingInOrder`) async iteration — what
+// replaces `await` in a loop, which `no-await-in-loop` refuses repo-wide — and
+// `promised`, a synchronous body behind a Promise-shaped API.
+export { everyInOrder, forEachInOrder, FS_CONCURRENCY, mapConcurrentFailingInOrder, mapInOrder, mapWithConcurrency, promised, } from './in-order.js';
 // Machine-independent string ordering for hashed/serialized output — never `localeCompare`.
 export { compareCodeUnits } from './compare-code-units.js';
 // The crawl-timing seam: which contributor, stratum and fixpoint pass owns the

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/kill-process-tree.d.ts

@@ -0,0 +1,43 @@
+/** A spawned child, as {@link killProcessTree} needs it. */
+export interface KillableChild {
+    readonly pid?: number | undefined;
+    kill(signal: NodeJS.Signals): boolean;
+}
+/** How {@link killProcessTree} reaches the child's descendants, and whether it also goes through the child. */
+export interface KillProcessTreeOptions {
+    /**
+     * POSIX: the child was spawned `detached`, so it leads a process group and the kill takes the
+     * whole GROUP (the negated pid) — its grandchildren included. False: the child's pid alone (a
+     * child that is not a leader has no group of its own to kill). Ignored on Windows, where
+     * `taskkill /T` walks the tree from the child.
+     */
+    readonly groupLeader: boolean;
+    /**
+     * Also SIGKILL through `child.kill`, the call whose refusal Node reports as the child's `error`
+     * event — for a caller that watches that event to retry or report a kill that did not land.
+     */
+    readonly throughChild: boolean;
+}
+/**
+ * SIGKILL a child and every process it started — the ONE way VAT kills a process tree.
+ *
+ * - **POSIX**: the child's process group when it leads one (`groupLeader`), else its pid.
+ * - **Windows**: `taskkill /T /F`, which terminates the child and its whole tree. Windows has no
+ *   process groups, and `child.kill` there is `TerminateProcess` of the child alone.
+ * - A child with no pid (never spawned) has nothing to kill. A kill whose target is already gone
+ *   ({@link isProcessGoneError}) is absorbed; anything else the kill throws stays loud — a reaper
+ *   that says nothing about a tree it did not reap leaves processes running unseen.
+ * - **`throughChild` goes FIRST.** On Windows only the child's own kill records the signal: libuv's
+ *   `uv_process_kill` sets the handle's `exit_signal` when ITS `TerminateProcess` lands, so `exit`
+ *   reports `(null, 'SIGKILL')`. A `taskkill` first leaves `child.kill` nothing to kill (ESRCH, no
+ *   signal recorded) and `exit` reads `(1, null)` — the supervisor's kill reported as the child
+ *   exiting 1 on its own. The `taskkill /T` sweep after it is best-effort: `TerminateProcess` is
+ *   asynchronous and Node still holds the child's handle (so its pid is not recycled), but whether
+ *   taskkill can still walk the tree from a root already terminating is not established — a
+ *   grandchild may run on, as it does on POSIX for a child that does not lead a group.
+ *
+ * @param child - The spawned child
+ * @param options - See {@link KillProcessTreeOptions}
+ */
+export declare function killProcessTree(child: KillableChild, options: KillProcessTreeOptions): void;
+//# sourceMappingURL=kill-process-tree.d.ts.map

package/dist/kill-process-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill-process-tree.d.ts","sourceRoot":"","sources":["../src/kill-process-tree.ts"],"names":[],"mappings":"AAIA,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;CACvC;AAED,+GAA+G;AAC/G,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAW3F"}

package/dist/kill-process-tree.js

@@ -0,0 +1,48 @@
+import { spawnSync } from 'node:child_process';
+import { isProcessGoneError } from './errors/errno-table.js';
+/**
+ * SIGKILL a child and every process it started — the ONE way VAT kills a process tree.
+ *
+ * - **POSIX**: the child's process group when it leads one (`groupLeader`), else its pid.
+ * - **Windows**: `taskkill /T /F`, which terminates the child and its whole tree. Windows has no
+ *   process groups, and `child.kill` there is `TerminateProcess` of the child alone.
+ * - A child with no pid (never spawned) has nothing to kill. A kill whose target is already gone
+ *   ({@link isProcessGoneError}) is absorbed; anything else the kill throws stays loud — a reaper
+ *   that says nothing about a tree it did not reap leaves processes running unseen.
+ * - **`throughChild` goes FIRST.** On Windows only the child's own kill records the signal: libuv's
+ *   `uv_process_kill` sets the handle's `exit_signal` when ITS `TerminateProcess` lands, so `exit`
+ *   reports `(null, 'SIGKILL')`. A `taskkill` first leaves `child.kill` nothing to kill (ESRCH, no
+ *   signal recorded) and `exit` reads `(1, null)` — the supervisor's kill reported as the child
+ *   exiting 1 on its own. The `taskkill /T` sweep after it is best-effort: `TerminateProcess` is
+ *   asynchronous and Node still holds the child's handle (so its pid is not recycled), but whether
+ *   taskkill can still walk the tree from a root already terminating is not established — a
+ *   grandchild may run on, as it does on POSIX for a child that does not lead a group.
+ *
+ * @param child - The spawned child
+ * @param options - See {@link KillProcessTreeOptions}
+ */
+export function killProcessTree(child, options) {
+    if (options.throughChild)
+        child.kill('SIGKILL');
+    const { pid } = child;
+    if (pid !== undefined) {
+        if (process.platform === 'win32') {
+            // eslint-disable-next-line sonarjs/no-os-command-from-path -- taskkill is a fixed Windows system command (no PATH-injection surface); it is the only way to terminate a Windows process tree.
+            spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+        }
+        else {
+            killAbsorbingGone(options.groupLeader ? -pid : pid);
+        }
+    }
+}
+/** SIGKILL `target` (a pid, or a negated group id); a target already gone has nothing left to kill. */
+function killAbsorbingGone(target) {
+    try {
+        process.kill(target, 'SIGKILL');
+    }
+    catch (error) {
+        if (!isProcessGoneError(error))
+            throw error;
+    }
+}
+//# sourceMappingURL=kill-process-tree.js.map

package/dist/kill-process-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kill-process-tree.js","sourceRoot":"","sources":["../src/kill-process-tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAwB7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB,EAAE,OAA+B;IACnF,IAAI,OAAO,CAAC,YAAY;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;IACtB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,8LAA8L;YAC9L,SAAS,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QACnG,CAAC;aAAM,CAAC;YACN,iBAAiB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;AACH,CAAC;AAED,uGAAuG;AACvG,SAAS,iBAAiB,CAAC,MAAc;IACvC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;IAC9C,CAAC;AACH,CAAC"}