@openclaw/openshell-sandbox 2026.9.1 → 2026.9.3

package/node_modules/@openclaw/fs-safe/docs/path.md

@@ -0,0 +1,208 @@
+# Path helpers
+
+`@openclaw/fs-safe/path` is the lower-level lexical and canonical path surface — useful when you have your own logic that needs to know "is this path inside that directory" without going through `root()` or `pathScope()`.
+
+```ts
+import {
+  isPathInside,
+  isPathInsideWithRealpath,
+  isWithinDir,
+  resolveSafeBaseDir,
+  safeRealpathSync,
+  safeStatSync,
+  assertNoNulPathInput,
+  assertNoUnsafeDeviceReadPath,
+  isUnsafeDeviceReadPath,
+  isNotFoundPathError,
+  isSymlinkOpenError,
+  hasNodeErrorCode,
+} from "@openclaw/fs-safe/path";
+```
+
+Path helpers are deliberately a subpath import so the main entry stays focused
+on the root capability, its shared configuration, errors, and external-output
+helper.
+
+## Boundary checks
+
+### `isPathInside(rootDir, target)`
+
+Pure lexical check. Returns `true` if `target` is `rootDir` itself or a descendant, after normalizing both inputs. **Does not** touch the filesystem — does not follow symlinks.
+
+```ts
+isPathInside("/srv/uploads", "/srv/uploads/photo.jpg");      // true
+isPathInside("/srv/uploads", "/srv/uploads/../escape.txt");  // false
+isPathInside("/srv/uploads", "/srv/uploads-other/x");        // false
+isPathInside("/srv/uploads", "/srv/uploads");                // true (root itself counts)
+```
+
+The check is platform-aware: on Windows, paths are normalized for case and separator before comparison.
+
+### `isPathInsideWithRealpath(rootDir, target, opts?)`
+
+Synchronous. Same as `isPathInside`, but resolves both inputs through `realpath` first. Use this when you want the canonical answer and either input might be a symlink.
+
+```ts
+isPathInsideWithRealpath("/srv/uploads", "/srv/symlink-to-elsewhere"); // false
+```
+
+```ts
+type Options = {
+  requireRealpath?: boolean;            // default true
+  cache?: Map<string, string>;
+};
+```
+
+Does not throw on missing inputs — `realpath` failures are absorbed by the underlying `safeRealpathSync`. By default (`requireRealpath: true`) the function returns `false` when either input cannot be resolved. Pass `{ requireRealpath: false }` to fall back to the lexical answer from `isPathInside` instead.
+
+### `isWithinDir(rootDir, targetPath)`
+
+Convenience wrapper around `isPathInside`. Same semantics, different name kept for callers that prefer the noun phrase.
+
+### `resolveSafeBaseDir(rootDir)`
+
+Resolve a base directory to an absolute, normalized form ready for prefix comparison. Pre-normalized directories make subsequent `isPathInside` checks unambiguous.
+
+```ts
+const base = resolveSafeBaseDir("/srv/uploads/.");  // "/srv/uploads/"
+```
+
+## Realpath and stat
+
+### `safeRealpathSync(targetPath, cache?)`
+
+Synchronous `realpath` that returns `null` instead of throwing on any error. Pass an optional `Map<string, string>` to cache results across calls within a single operation.
+
+```ts
+const real = safeRealpathSync("/srv/uploads/photo.jpg");
+if (real === null) return notFound();
+```
+
+All `realpath` failures collapse to `null` — there is no distinction between `ENOENT`, `EACCES`, and other I/O errors. Use `fs.realpathSync` directly if you need to branch on the error code.
+
+### `safeStatSync(targetPath)`
+
+Synchronous `stat` that returns `Stats` on success and `null` on any failure,
+including missing paths and permission errors. Use `fs.statSync` directly when
+the distinction matters.
+
+```ts
+const stat = safeStatSync("/srv/uploads/photo.jpg");
+if (!stat?.isFile()) return notFound();
+```
+
+### `assertNoNulPathInput(filePath, message?)`
+
+Throws `FsSafeError` with code `invalid-path` when a path string contains an embedded NUL byte. Use it before calling Node `fs` APIs directly; Node's native error can include raw path text in the message.
+
+### `assertNoUnsafeDeviceReadPath(filePath, options?)`
+
+Throws `FsSafeError` with code `device-path` when a read target is a known unsafe device or process-fd path. The built-in read/open helpers call this automatically before opening files; use it only when you are building your own read primitive.
+
+```ts
+assertNoUnsafeDeviceReadPath("/dev/zero"); // throws on POSIX
+isUnsafeDeviceReadPath("/dev/fd/0");       // true on POSIX
+```
+
+The check is intentionally not a normal consumer policy knob. Safe read APIs reject these targets by default because they can block forever, stream indefinitely, or alias process file descriptors.
+
+## Error inspection
+
+### `isNotFoundPathError(err)`
+
+`true` if the error is a `NodeJS.ErrnoException` with code `ENOENT` (file or directory missing).
+
+```ts
+try {
+  await fs.readFile(p);
+} catch (err) {
+  if (isNotFoundPathError(err)) return null;
+  throw err;
+}
+```
+
+### `isSymlinkOpenError(err)`
+
+`true` if the error indicates a symlink-related open failure (typically `ELOOP` or platform-specific symlink rejections from `O_NOFOLLOW`).
+
+### `hasNodeErrorCode(err, code)`
+
+Generic helper. `true` if `err` is a `NodeJS.ErrnoException` with the matching `code` string.
+
+```ts
+if (hasNodeErrorCode(err, "EACCES")) return reply(403);
+```
+
+## When to use these vs `root()`
+
+| Path helpers | `root()` |
+|---|---|
+| Pure functions over absolute path strings. | Boundary handle with method-style I/O. |
+| No I/O performed (except `safeRealpathSync`/`safeStatSync`). | Every method goes to disk. |
+| Fits inside other helpers / validation pipelines. | Standalone consumer of caller-supplied paths. |
+
+If you're writing a validator that says "is this safe?" without performing the operation, the path helpers are the right tool. If you're going to perform the read or write, use `root()` so the boundary check is fused with the operation.
+
+## Common patterns
+
+### "Resolve, then assert it's inside my dir"
+
+```ts
+import { isPathInsideWithRealpath, isNotFoundPathError } from "@openclaw/fs-safe/path";
+
+let canonical: string;
+try {
+  canonical = await fs.realpath(input);
+} catch (err) {
+  if (isNotFoundPathError(err)) return reply(404);
+  throw err;
+}
+if (!isPathInsideWithRealpath("/srv/uploads", canonical)) {
+  return reply(403);
+}
+```
+
+### Cache realpaths in a request scope
+
+```ts
+const cache = new Map<string, string>();
+for (const p of inputs) {
+  const real = safeRealpathSync(p, cache);
+  if (real && isPathInside(root, real)) keep.push(real);
+}
+```
+
+### Branch on `ENOENT` vs other errors
+
+```ts
+try {
+  return await fs.readFile(p);
+} catch (err) {
+  if (isNotFoundPathError(err)) return null;
+  if (hasNodeErrorCode(err, "EACCES")) return null;
+  throw err;
+}
+```
+
+## Path-policy helpers
+
+`path-policy.ts` exposes two assertions used by `root()` internally; they are exported for callers building their own helpers:
+
+```ts
+import {
+  assertNoPathAliasEscape,
+  assertNoHardlinkedFinalPath,
+  PATH_ALIAS_POLICIES,
+} from "@openclaw/fs-safe/advanced";
+```
+
+- `assertNoPathAliasEscape({ rootRealPath, candidatePath, policy })` — async. Asserts the candidate's resolved real path is inside the root. Configurable via `PATH_ALIAS_POLICIES` (which currently ships only the default `"strict"` policy).
+- `assertNoHardlinkedFinalPath({ filePath })` — async. Throws if the file at `filePath` has `nlink > 1`.
+
+Use these when writing a custom helper that wants the same guards `root()` uses but with different surrounding logic.
+
+## See also
+
+- [`root()`](root.md) — the high-level boundary that uses these checks internally.
+- [`pathScope()`](path-scope.md) — `Result`-style scope checks.
+- [Reading](reading.md) — `Root.read()` and friends use `isPathInside` + identity checks.

package/node_modules/@openclaw/fs-safe/docs/permissions.md

@@ -0,0 +1,200 @@
+# Permissions
+
+`@openclaw/fs-safe/permissions` contains the curated mode and permission inspection helpers used by secure file reads and by applications that want to report actionable permission problems.
+
+```ts
+import {
+  formatPermissionDetail,
+  formatPermissionRemediation,
+  inspectPathPermissions,
+} from "@openclaw/fs-safe/permissions";
+
+const perms = await inspectPathPermissions("/var/lib/app/auth.token");
+console.log(formatPermissionDetail("/var/lib/app/auth.token", perms));
+if (perms.ok && (perms.groupReadable || perms.worldReadable)) {
+  console.log(
+    formatPermissionRemediation({
+      targetPath: "/var/lib/app/auth.token",
+      perms,
+      isDir: false,
+      posixMode: 0o600,
+    }),
+  );
+}
+```
+
+## POSIX helpers
+
+```ts
+safeStat(path);
+inspectPathPermissions(path, options?);
+formatPermissionDetail(path, check);
+formatPermissionRemediation({ targetPath, perms, isDir, posixMode });
+modeBits(mode);
+formatOctal(bits);
+isWorldWritable(bits);
+isGroupWritable(bits);
+isWorldReadable(bits);
+isGroupReadable(bits);
+```
+
+POSIX remediation strings shell-quote paths with whitespace or metacharacters
+and protect option-like paths with `--`, so they can be presented as commands
+without letting the inspected pathname add shell syntax.
+
+`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. Secure reads and callers that protect credential-bearing execution require `ownerTrusted === true`.
+
+## Advanced Windows ACL helpers
+
+The low-level Windows ACL parser and `icacls` command builders live in `@openclaw/fs-safe/advanced`:
+
+```ts
+import {
+  createIcaclsResetCommand,
+  formatIcaclsResetCommand,
+  formatWindowsAclSummary,
+  inspectWindowsAcl,
+  parseIcaclsOutput,
+  resolveWindowsUserPrincipal,
+  summarizeWindowsAcl,
+} from "@openclaw/fs-safe/advanced";
+
+inspectWindowsAcl(path, { env, exec });
+parseIcaclsOutput(output, targetPath);
+summarizeWindowsAcl(entries, env);
+formatWindowsAclSummary(summary);
+formatIcaclsResetCommand(targetPath, { isDir, env });
+createIcaclsResetCommand(targetPath, { isDir, env });
+resolveWindowsUserPrincipal(env);
+```
+
+The fallback Windows inspector calls `icacls.exe <path>` using its supported
+path-only inspection syntax and classifies principals as trusted, world, or
+group. Trusted defaults include the current user, SYSTEM, and Administrators.
+Built-in PowerShell, `icacls.exe`, and `whoami.exe` invocations have a fixed
+30-second per-process deadline. A command failure or timeout returns an
+unverified result (`source: "unknown"`) so callers fail closed. Advanced callers
+that inject a custom `exec` implementation own that executor's deadline.
+Failed owner and ACL inspections retain `error` text and an optional
+`errorDetail: PermissionCommandFailure` with `command`, integer `durationMs`,
+`timedOut`, `exitCode`, `signal`, and `stderr`. The type is exported from both
+`@openclaw/fs-safe/permissions` and `@openclaw/fs-safe/advanced`. Built-in
+execution measures elapsed time; injected execFile-shaped failures receive
+best-effort command diagnostics. Plain errors have no `errorDetail`.
+Display reasons and stderr escape control characters and are limited to 400
+characters, including a trailing `…` when truncated. Diagnostics do not copy
+stdout or read target file contents. The separate `errorCause` retains the
+original exception for restricted local diagnosis; do not serialize or expose
+it as display text.
+The parser is on the advanced surface so tests and CLIs can process captured
+`icacls` output without spawning a process.
+
+When the native binding is available, `inspectPathPermissions()`
+reads the owner and DACL directly with Windows security APIs. It classifies the
+current user, LocalSystem, and built-in Administrators as trusted and reports
+the world/group read/write facts consumed by secure reads. Descriptor forms it
+cannot classify equivalently fall back to the established owner/.NET and
+`icacls` path; `mode: "off"` exercises that fallback deterministically.
+
+## Policy-free owner and DACL facts
+
+`readOwnerAndDacl()` exposes the direct Windows descriptor facts needed by a
+consumer that owns a principal allowlist. It deliberately does not decide
+which SID is trusted or calculate effective access. For example, snapshot
+staging can reject an incomplete descriptor and ignore inherit-only ACEs before
+applying its own exact SID policy:
+
+```ts
+import { readOwnerAndDacl } from "@openclaw/fs-safe/permissions";
+
+const facts = readOwnerAndDacl(stagingDirectory);
+if (facts.status === "unsupported-platform") {
+  throw new Error(`Windows ACL facts unavailable on ${facts.platform}`);
+}
+if (!facts.isLocal || !facts.daclPresent || !facts.complete) {
+  throw new Error("staging DACL cannot be evaluated completely");
+}
+
+for (const ace of facts.aces) {
+  if (ace.flags.inheritOnly) continue;
+  if (!trustedSids.has(ace.sid)) {
+    throw new Error(`unexpected staging principal: ${ace.sid}`);
+  }
+  evaluateMaskAndDenyOrder(ace.aceType, ace.mask);
+}
+```
+
+On Windows the supported result contains `ownerSid`, `currentUserSid`,
+`daclPresent`, `isLocal`, `complete`, `unsupportedAceTypes`, and ordered basic
+allow/deny `aces`. `currentUserSid` is the process token's `TokenUser` SID, so
+callers can compare it with the owner or their own allowlist without fs-safe
+applying trust policy. Each ACE has `{ sid, mask, aceType, flags }`; `flags`
+retains the raw byte and decoded
+`objectInherit`, `containerInherit`, `noPropagateInherit`, `inheritOnly`,
+`inherited`, `successfulAccess`, and `failedAccess` facts. SID strings are
+lowercase Windows SID notation. `daclPresent: false` represents a null DACL,
+which grants unrestricted access; it must not be mistaken for an empty DACL.
+
+Object-specific and other ACE layouts are not guessed: they are omitted,
+`complete` becomes false, and their numeric types appear in
+`unsupportedAceTypes`, allowing a security-sensitive caller to fail closed.
+Non-Windows systems return `{ status: "unsupported-platform", platform }`.
+Windows requires the native binding; if it is unavailable or forced
+off, the call throws `FsSafeError("helper-unavailable")`. The existing coarse
+`inspectPathPermissions()` API still owns its compatibility fallback and trust
+classification.
+
+## Private directories
+
+```ts
+import path from "node:path";
+import { createPrivateDirectory } from "@openclaw/fs-safe/permissions";
+
+const sqliteDirectory =
+  "C:\\Users\\me\\AppData\\Local\\OpenClaw\\private-databases";
+await createPrivateDirectory(sqliteDirectory);
+await openSqlite(path.join(sqliteDirectory, "sessions.sqlite"));
+```
+
+On Windows with native support, this creates the directory and applies a
+protected owner + LocalSystem + Administrators full-control DACL directly with
+an atomic security descriptor; no PowerShell or `icacls` process is launched.
+This API is Windows-only and native-only; it fails closed with
+`FsSafeError("helper-unavailable")` on other platforms, when native mode is off,
+or when the binding is unavailable. POSIX callers should create private
+directories through their existing trusted-root creation policy rather than a
+pathname-only compatibility shim. Existing Windows permission inspection still
+retains its .NET/`icacls` compatibility fallback.
+
+Use `createIcaclsResetCommand()` when you need a structured command and argv pair. Use `formatIcaclsResetCommand()` when you only need a remediation string for a user-facing message.
+
+## Types
+
+```ts
+type PermissionCheck = {
+  ok: boolean;
+  isSymlink: boolean;
+  isDir: boolean;
+  mode: number | null;
+  bits: number | null;
+  source: "posix" | "windows-acl" | "unknown";
+  worldWritable: boolean;
+  groupWritable: boolean;
+  worldReadable: boolean;
+  groupReadable: boolean;
+  ownerSid?: string;
+  ownerTrusted?: boolean;
+  ownerError?: string;
+  aclSummary?: string;
+  error?: string;
+};
+```
+
+`ok: false` means the path itself could not be inspected. `ok: true` with `source: "unknown"` means basic stat information was available, but the platform-specific permission source could not be verified.
+
+## See also
+
+- [Secure file reads](secure-file.md) — fd-pinned reads that enforce these checks.
+- [Errors](errors.md) — permission-related `FsSafeError` codes.
+- [Native architecture](native.md) — direct Windows security descriptor mechanisms.
+- [Migrating to 0.5](migrating-to-0.5.md) — native-only feature checklist.

package/node_modules/@openclaw/fs-safe/docs/private-file-store.md

@@ -0,0 +1,54 @@
+# Private file-store mode
+
+Private state is not a separate store family. Use `fileStore({ private: true })`
+when a directory holds credentials, tokens, auth profiles, or other private
+JSON/text state.
+
+```ts
+import { fileStore } from "@openclaw/fs-safe/store";
+
+const store = fileStore({ rootDir: "/var/lib/app", private: true });
+
+await store.writeJson("state.json", state);
+const loaded = await store.readJsonIfExists<State>("state.json");
+```
+
+## Behavior
+
+- Writes create parent directories at `0o700` and files at `0o600` unless you
+  pass stricter `dirMode` / `mode` options.
+- Async private-mode writes route through the secret-file atomic path, which refuses
+  symlink parent components and re-asserts mode after rename. Existing directories
+  must already have the requested mode; writes do not repair their permissions.
+  New-directory initialization requires guarded descriptor authority and may
+  fail closed under restrictive platform/umask combinations; see the
+  [secret-directory policy](secret-file.md#parameters).
+- Locked JSON mutations prepare private directories before acquiring their
+  sidecar and bind the lock to the admitted parent identity. Lock normalization
+  is read-only: a deleted or replaced admitted parent is rejected, not recreated.
+  The writer still revalidates directory admission afterward; reads do not create
+  directories.
+- `readText()` and `readJson()` are strict and throw on missing files.
+- `readTextIfExists()` and `readJsonIfExists()` return `null` on missing files.
+- `write()`, `writeText()`, `writeJson()`, `writeStream()`, and `copyIn()` all
+  keep the same root-relative `FileStore` shape.
+
+## Sync writes
+
+Use `fileStoreSync({ private: true })` for boot paths or sync-only integration
+points:
+
+```ts
+import { fileStoreSync } from "@openclaw/fs-safe/store";
+
+fileStoreSync({ rootDir: "/var/lib/app", private: true }).writeJson("config.json", config);
+```
+
+The sync store intentionally exposes a smaller surface: path resolution,
+lenient reads, and atomic text/JSON writes.
+
+## See also
+
+- [`fileStore`](file-store.md) — full store API.
+- [Secret files](secret-file.md) — standalone credential file reads and writes.
+- [JSON files](json.md) — strict/lenient JSON helpers without a bound store.

package/node_modules/@openclaw/fs-safe/docs/public-api.md

@@ -0,0 +1,112 @@
+# Public API inventory
+
+This page closes the gap between the narrative guides and the complete package
+surface. The generated declarations define the exact signatures; the lists
+below name the lower-frequency exports that are easy to miss when reading only
+the focused guides. `test/public-api.json` guards the same inventory during
+pack checks.
+
+## Main entry and `root`
+
+The main entry and `@openclaw/fs-safe/root` expose the root capability types,
+including `ContainmentGuarantee`, `RootOpenOptions`, `RootCreateOptions`,
+`RootCreateJsonOptions`, and `WritableOpenMode`. The root-bounded iterator uses
+`RootWalkOptions`, `RootWalkEntry`, `RootWalkDataEntry`, `RootWalkEntryKind`,
+`RootWalkDataEntryKind`, `RootWalkSymlinkPolicy`, `RootWalkLimitBehavior`,
+`RootWalkDirectoryErrorBehavior`, `RootWalkEntryFilter`, and
+`RootWalkEntryFilterResult`.
+
+The root subpath also exports `openLocalFileSafely`, `readLocalFileSafely`, and
+`resolveOpenedFileRealPathForHandle` for trusted absolute-file composition.
+They do not create a root boundary around arbitrary caller input; prefer
+`root()` for untrusted paths.
+
+The error helpers are `categorizeFsSafeError` and `FsSafeErrorDetails`. The
+deprecated native-configuration bridge retains the `FsSafePythonConfig` type.
+
+## `path` and `advanced`
+
+The lexical path surface additionally exports `isNodeError`,
+`isPathRelativeEscape`, `normalizeWindowsPathForComparison`,
+`resolveSafeRelativePath`, `splitSafeRelativePath`, and
+`matchUnsafeDeviceReadPath`. The device matcher is described by
+`UnsafeDeviceReadPathMatch`, `UnsafeDeviceReadPathOptions`, and
+`UnsafeDeviceReadPathReason`.
+
+The advanced root-file primitive exports `OpenRootFileParams`,
+`OpenRootFileSyncParams`, `RootFileOpenResult`, and
+`RootFileOpenFailureReason`. These are composition types for callers building
+their own pinned-open flow, not substitutes for the higher-level `Root` verbs.
+
+## `json` and `store`
+
+Standalone structured reads use `ReadJsonOptions`, `ReadRootJsonSyncOptions`,
+`ReadRootStructuredFileSyncOptions`, and `RootStructuredFileReadResult`.
+
+The store surface additionally exports `FileStoreReadOptions` and
+`JsonFileStoreOptions`. Durable-queue inspection and recovery use
+`jsonDurableQueueEntryExists`, `loadJsonDurableQueueEntry`,
+`readJsonDurableQueueEntry`, and the `JsonDurableQueueLoadOptions` and
+`JsonDurableQueueReadResult` types. `unlinkBestEffort` is the explicitly
+best-effort cleanup helper used by those queue flows.
+
+## Permissions and secure files
+
+Permission inspection exposes `PermissionCheckOptions` and `SafeStatResult`.
+Private-directory creation uses `CreatePrivateDirectoryOptions`. Raw Windows
+descriptor facts use `OwnerAndDaclResult`, `WindowsAccessControlEntry`, and
+`WindowsAceFlags`.
+
+Secure reads split their option and result shapes into
+`SecureFileTrustOptions`, `SecureFilePermissionOptions`,
+`SecureFileInjectOptions`, `SecureFileIoOptions`, and `SecureFileReadResult`.
+
+## Locks, walking, and temp workspaces
+
+The file-lock diagnostics surface includes `FileLockHeldEntry`,
+`FileLockStaleRecovery`, and `SidecarLockCompromisedInfo`.
+`drainFileLockManagerForTest` and `resetFileLockManagerForTest` are test-only
+manager controls; production code should not use them as lock recovery.
+
+Standalone walkers use the `WalkEntryKind` and `WalkSymlinkPolicy` unions.
+Private workspaces expose `TempPathIdentityReceipt`,
+`TempWorkspaceCleanupResult`, and `TempWorkspaceCleanupSafety` so callers can
+distinguish outcomes and select compatible or required bounded-tree cleanup.
+Strict workspace creation requires native no-replace quarantine plus retained
+parent/workspace descriptors; see the
+[creation and cleanup contract](temp.md#private-temp-workspaces).
+
+## Atomic replacement and durability
+
+Atomic helper option and receipt types include
+`MovePathWithCopyFallbackOptions`, `ReplaceDirectoryAtomicOptions`,
+`ReplaceFileAtomicSyncOptions`, `ReplaceFileAtomicResult`,
+`ReplaceFileAtomicRestoreCleanup`, `ReplaceFileCopyFallbackRestorePolicy`, and
+`ReplaceFileDestinationHardlinkPolicy`.
+
+The durability surface also exports the synchronous strict
+`syncDirectorySync`, plus `DirectoryReceipt`, `DurableDirectoryReceipt`,
+`EnsureDurableDirectoryOptions`, `PublishFileExclusiveResult`,
+`PublishFileExclusiveStrategy`, `PublishFileExclusiveCleanup`,
+`PublishFileExclusiveFailurePhase`,
+`PublishFileExclusiveDirectorySyncFailure`, `Sha256FileInput`, and
+`Sha256FileResult`.
+
+## Archives
+
+Archive option and policy types are `ExtractArchiveOptions`,
+`ArchiveEntryFilter`, `ArchiveEntryModePolicy`, and
+`ArchiveFilteredEntryPolicy`. Typed error-code unions are
+`ArchiveFormatErrorCode`, `ArchiveLimitErrorCode`, and
+`ArchiveSecurityErrorCode`. TAR and ZIP preflight composition uses
+`TarEntryInfo` and `ZipArchiveWithFiles`.
+
+`createArchiveSymlinkTraversalError` constructs the typed traversal failure
+used by extractors. `resolvePackedRootDir` finds the single packed root when an
+archive layout permits it; neither helper weakens entry validation.
+
+## Keeping this list honest
+
+Every runtime and type name in `test/public-api.json` must appear somewhere in
+`README.md` or `docs/`. Documentation examples are also checked so a named
+import cannot silently move to another package subpath.