docs: document absolute directory helper

docs/advanced.md

@@ -38,9 +38,15 @@ The exports group into a handful of themes. Each documented helper has its own p
 | Export | Page | Notes |
 |---|---|---|
 | `assertAbsolutePathInput` | – | Validate a caller-supplied absolute path string. |
+| `ensureAbsoluteDirectory`, `EnsureAbsoluteDirectoryOptions`, `EnsureAbsoluteDirectoryResult` | – | Create a trusted absolute directory path one segment at a time, rejecting symlink or non-directory segments. |
 | `canonicalPathFromExistingAncestor`, `findExistingAncestor` | – | Canonicalize without requiring the leaf to exist. |
 | `resolveAbsolutePathForRead`, `resolveAbsolutePathForWrite`, `ResolvedAbsolutePath`, `ResolvedWritableAbsolutePath`, `AbsolutePathSymlinkPolicy` | – | Validate an absolute path against a symlink policy before opening. |
 
+`ensureAbsoluteDirectory()` is for paths you already intend to trust as absolute
+locations, such as a configured output root. It does not enforce a root boundary;
+use `pathScope().ensureDir()` or `ensureDirectoryWithinRoot()` when the caller
+supplies a path that must stay under a root.
+
 ### Files and identity
 
 | Export | Page | Notes |

test/coverage-gaps.test.ts

@@ -254,6 +254,14 @@ describe("absolute path helpers", () => {
     expect((await fs.stat(targetDir)).isDirectory()).toBe(true);
   });
 
+  it("rejects relative absolute-directory inputs", async () => {
+    await expect(
+      ensureAbsoluteDirectory(path.join("..", "..", "..", "escape"), {
+        scopeLabel: "output directory",
+      }),
+    ).resolves.toEqual({ ok: false, error: "path must be absolute" });
+  });
+
   it("rejects absolute directory creation when the existing target is not a directory", async () => {
     const root = await fs.realpath(await tempRoot("fs-safe-absolute-dir-file-"));
     const targetPath = path.join(root, "file.txt");