fix(studio): acquireSubstrate's pre-flight guards answer from inside the try

[KnockOutEZ]

Closes KnockOutEZ/wigolo-studio-run#188 (PX0 exit-6).

CI deferred — quota.

What was wrong

8f465f67 (#513) moved join(root, version) inside the try precisely so "NEVER THROWS is true of the function's shape rather than of its guards". It left the guards themselves outside — and staysInsideItsDirectory (:136) calls isAbsolute(), which throws ERR_INVALID_ARG_TYPE on a non-string. The exact class #513 closed for version reopened one line higher for executable, on the one seam a manifest can still arrive mistyped through: deps.source, which never passes readSubstrateManifest and which is where S16-alpha's published channel plugs in. warmup awaits this call with no try/catch on the strength of the documented contract, so the throw takes the browser, model and search phases with it.

Sibling asymmetry in the same file (security review LOW-2): readSubstrateRecord (:173) checked truthiness where readSubstrateManifest (:294) establishes typeof === 'string'. The other two fields throw their way to null through the function's own catch, so the shape that actually got through was a numeric version — read back as PRESENT, then flowing into already_present's detail text, the acquisition log and every doctor row downstream as a number.

What changed

• Both pre-flight guards now answer from inside the try, so the contract is structural rather than a property of the shapes the guards anticipated.
• The manifest's two path fields are type-checked at the seam entry, the way readSubstrateManifest does for a manifest on disk — so the refusal names its own reason instead of surfacing as the catch's generic install failure. What the guards refuse is unchanged; only where they answer from.
• readSubstrateRecord establishes typeof === 'string' on version, executable and path.

Demo

Repro against the built dist/, injected source + a hand-edited record.json.

Before (tip 89f423b1):

acquire: non-string executable -> THREW TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received type number (1)
acquire: non-string version    -> RESOLVED outcome=failed error=The "path" argument must be of type string. Received type number (1)
acquire: well-formed source    -> RESOLVED outcome=acquired error=-
record: non-string version    -> PRESENT (wrong)
record: non-string executable -> ABSENT
record: non-string path       -> ABSENT
record: well-formed          -> PRESENT

After:

acquire: non-string executable -> RESOLVED outcome=failed error=unusable manifest: version string, executable number
acquire: non-string version    -> RESOLVED outcome=failed error=unusable manifest: version number, executable string
acquire: well-formed source    -> RESOLVED outcome=acquired error=-
record: non-string version    -> ABSENT
record: non-string executable -> ABSENT
record: non-string path       -> ABSENT
record: well-formed          -> PRESENT

The well-formed lines are the anti-vacuity arms: they are unchanged across the fix, so the new refusals cannot be satisfied by a guard that refuses everything.

Red-then-green

7b0b94cd (test) is the direct parent of d920d200 (fix). Against unfixed source it was red on exactly the two defects and nothing else:

FAIL ... settles rather than rejecting when an injected manifest's executable is a number
FAIL ... settles rather than rejecting when an injected manifest's executable is an array
FAIL ... settles rather than rejecting when an injected manifest's executable is a boolean
FAIL ... refuses a record whose version is a number, even though the substrate is really there
Tests  4 failed | 59 passed (63)

The discriminator in the acquire arms is settle-vs-reject, not an outcome string — that is the property the never-throws contract is about, and an assertion on outcome alone cannot tell a refusal apart from a crash.

Suites (local — CI deferred, quota)

npm test              exit 0   955 passed | 5 skipped (960 files) · 12070 passed | 20 skipped | 7 todo
npx tsc --noEmit      exit 0   (0 lines of output)
npm run gate:studio   exit 0   tests/ type-check debt holds at baseline 363

Non-goals honoured

No concurrent-acquire interlock, no TOCTOU work between record validation and spawn, no change to what the guards refuse.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 621af8e8-dc1c-41c4-bbb7-17494df03fa4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}