refactor(#4653): make containment ONE decision, resolved two ways

Satisfies #4653 DW1 and DW9, which were the phase's outstanding acceptance
criteria: every other implementation must be deleted or route its containment
DECISION through the canonical predicate, and no surviving wrapper may decide
WHETHER a path is contained.

Three implementations were being retained with their own comparisons, on the
argument that each needs LEXICAL resolution — a realpath-based predicate is the
wrong tool wherever a symlink must be preserved rather than resolved. That
argument is correct about RESOLUTION and was being used to justify owning the
DECISION too. Those are separable, and separating them is what closes the
criteria honestly rather than by reinterpretation.

  isContainedIn(resolvedTarget, resolvedRoot, pathImpl?)   module-internal

is now the single place this repo decides containment. It is separator-aware, so
a sibling merely sharing a prefix (`<root>-evil` against `<root>`) is still
rejected. Two exported families sit on it and differ ONLY in how a candidate is
resolved before the decision:

  assertWithinRoot / tryWithinRoot                realpath-resolving
  assertWithinRootLexical / tryWithinRootLexical  path.resolve only, no I/O

The lexical pair carries `opts.pathImpl`, so win32 separator semantics stay
testable off Windows — that seam already existed in isPathConfined and would
have been lost by a naive collapse.

The three call sites now take their decision from the predicate and keep only
what is genuinely theirs:

  external-descriptor-trust isPathConfined   delegates outright; pathImpl forwarded
  installer-migrations ensureInsideConfig    delegates; keeps its own message and
                                             its LEXICAL fullPath, which callers
                                             consume for existsSync and journal rows
  gsd-tools.cjs isInsideDir                  delegates; keeps its own `target !==
                                             root` condition, and the separate
                                             symlink refusal above it stands

DW5 is not weakened by this. That criterion binds the symlink oracle and the
ancestor canonicalization; both are untouched. The only change inside
validatePath is three comparison lines becoming one call, and the rejection
string `Path escapes allowed directory: <resolved> is outside <base>` stays
byte-identical because it is an observable CLI contract.

What this does NOT do, stated plainly: the lexical family still cannot see a
symlink. That is a property of lexical resolution, not a gap in the seam, and
the three callers that need it are the three that must pair it with their own
symlink refusal — which is exactly what the fix earlier in this phase added at
the install sites. The doc comment says so at the definition, and CONTEXT.md and
docs/explanation/security-model.md are corrected: they previously described
these three as deliberately NOT routed through the predicate, which is no longer
true.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/explanation/security-model.md

@@ -162,10 +162,19 @@ module is the central security utility. It provides:
 - Shell argument validation: arguments passed to subshell commands are
   validated before use
 
-Three containment checks elsewhere in the tree are deliberately NOT routed through
-this predicate, because each is narrower or stricter rather than a second opinion.
-The common thread is that a realpath-based predicate is the wrong tool wherever a
-symlink must be *preserved* rather than resolved.
+Containment is decided in exactly one place, but resolved two ways. The
+comparison itself — separator-aware, so a sibling merely sharing a prefix is
+never accepted — is internal to `security.cjs` and is the single decision. Two
+exported families sit on it and differ only in how a candidate is resolved
+before that decision: `assertWithinRoot` / `tryWithinRoot` resolve symlinks,
+and `assertWithinRootLexical` / `tryWithinRootLexical` use string resolution
+alone and never touch the filesystem.
+
+The lexical form exists because a realpath-based predicate is the wrong tool
+wherever a symlink must be *preserved* rather than resolved, or where the target
+legitimately does not exist yet. A lexical check **cannot see a symlink**, so a
+caller relying on one for a write-confinement guarantee must pair it with its
+own symlink refusal. Three call sites use it, each for a stated reason.
 
 The backup-restore gate in `gsd-core/bin/gsd-tools.cjs` rejects symlinks outright:
 the canonical predicate accepts a link whose target resolves inside the root, but