fix(optional-integration): detect absence by quoted specifier, not bare substring

The recipe classified a dynamic-import failure as "package absent" using
message.includes("@r3b1s/pi-repair-layer"). A present-but-broken install
(pi-repair-layer resolvable, a transitive dependency like typebox missing)
throws a module-not-found error naming the transitive module while embedding
pi-repair-layer only as a node_modules path segment, so the bare substring
misread it as absence and silently ran tools unwrapped.

Match the package name only as an imported specifier — an opening quote
immediately followed by the name ('@r3b1s/pi-repair-layer, no trailing quote so
both the bare-package and /pi-subpath error shapes match) — and extract the
classification into an exported isRepairPackageAbsent predicate for direct unit
testing. A broken install now rethrows loudly instead of falling back.

Updates the recipe fixture, the tool-owner integration guide, research Claim 11,
and the optional-integration spec; adds predicate unit coverage.

Author: r3b1s

docs/research.md

@@ -257,9 +257,19 @@ the requested module:
 
 **Why it matters:** the optional-integration recipe treats an import failure
 as "package absent" only when the code is one of these two values **and** the
-message names `@r3b1s/pi-repair-layer`; anything else rethrows so a broken
-install (a *transitive* module missing) is not silently misread as absent.
-All three observed shapes pass that discrimination.
+message names `@r3b1s/pi-repair-layer` **as a quoted module specifier** —
+matched as an opening quote immediately followed by the name
+(`'@r3b1s/pi-repair-layer`, no trailing quote so both the bare-package and
+`/pi`-subpath forms match); anything else rethrows so a broken install (a
+*transitive* module missing, e.g. `typebox`) is not silently misread as
+absent. The quote anchor matters because the jiti and compiled-binary shapes
+carry the importer path: a present-but-broken install throws
+`Cannot find module 'typebox/value' from '.../node_modules/@r3b1s/pi-repair-layer/...'`,
+which contains `@r3b1s/pi-repair-layer` only as a path segment (preceded by
+`/`, not a quote). A bare-substring match would misread that as absence; the
+quoted-specifier match rethrows it loudly. All three observed absent-package
+shapes still begin with quote-then-name and pass the discrimination.
+(Refined 2026-07-21; matcher verified by unit test against all three shapes.)
 
 ### Claim 12 — Git installs and other scopes do not resolve the shared npm siblings
 

docs/tool-owner-integration.md

@@ -191,19 +191,29 @@ const definition: ToolDefinition<typeof parameters> = {
   },
 };
 
+// Opening quote + name, no trailing quote: matches both the bare-package ESM
+// error (`'@r3b1s/pi-repair-layer'`) and the jiti/binary subpath error
+// (`'@r3b1s/pi-repair-layer/pi'`), while a `node_modules/...` path segment
+// (preceded by `/`, not a quote) does not read as absence.
+const REPAIR_PACKAGE_SPECIFIER_QUOTED = "'@r3b1s/pi-repair-layer";
+
+export function isRepairPackageAbsent(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code;
+  const message = error instanceof Error ? error.message : String(error);
+  return (
+    (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") &&
+    message.includes(REPAIR_PACKAGE_SPECIFIER_QUOTED)
+  );
+}
+
 async function loadRepairAdapter(): Promise<
   typeof adaptToolDefinition | undefined
 > {
   try {
     const repair = await import("@r3b1s/pi-repair-layer/pi");
     return repair.adaptToolDefinition;
   } catch (error) {
-    const code = (error as { code?: unknown } | null)?.code;
-    const message = error instanceof Error ? error.message : String(error);
-    const packageAbsent =
-      (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") &&
-      message.includes("@r3b1s/pi-repair-layer");
-    if (!packageAbsent) throw error;
+    if (!isRepairPackageAbsent(error)) throw error;
     return undefined;
   }
 }
@@ -225,12 +235,16 @@ The details are load-bearing:
   `code: "MODULE_NOT_FOUND"` (jiti's require path) or
   `code: "ERR_MODULE_NOT_FOUND"` (native ESM and the compiled pi binary). But
   a *present-but-broken* install — pi-repair-layer resolvable while one of its
-  own transitive modules is not — throws the same codes naming the
-  *transitive* module. Requiring the message to name
-  `@r3b1s/pi-repair-layer` keeps a broken install loud instead of silently
-  running unwrapped while the user believes repairs are active. Match the
-  package name, not the `/pi` subpath: native ESM reports only
-  `Cannot find package '@r3b1s/pi-repair-layer'`.
+  own transitive modules (e.g. `typebox`) is not — throws the same codes
+  naming the *transitive* module, and its message embeds
+  `.../node_modules/@r3b1s/pi-repair-layer/...` as a path segment. Match the
+  package name only where it appears as an imported specifier — an opening
+  quote immediately followed by the name (`'@r3b1s/pi-repair-layer`) — so that
+  path segment does not read as absence. No trailing quote: jiti and the
+  compiled binary name the full subpath (`'@r3b1s/pi-repair-layer/pi'`) while
+  native ESM names the bare package (`'@r3b1s/pi-repair-layer'`); both start
+  with quote-then-name. This keeps a broken install loud (it rethrows) instead
+  of silently running unwrapped while the user believes repairs are active.
 - **Rethrow everything else.** Any other error is a real failure, not
   absence.
 - **Emit one stderr line when falling back.** The two branches differ in
@@ -337,7 +351,11 @@ touches is deliberately small and covered by the compatibility contract in
   current major; documented exports follow semantic versioning.
 - Absence detection semantics are part of the contract: a missing package
   surfaces with `code` `MODULE_NOT_FOUND` or `ERR_MODULE_NOT_FOUND` and a
-  message naming the requested module.
+  message naming the requested module. The recipe matches that name as a
+  quoted specifier (`'@r3b1s/pi-repair-layer`, opening quote + name), not a
+  bare substring, so the package name appearing as a `node_modules` path
+  segment in a present-but-broken install rethrows loudly rather than reading
+  as absence.
 - Unrecognized preprocessor `kind`s are ignored — never fatal, no mutation, no
   claimed change — and results are still schema-validated. Repair options
   written against a newer minor version therefore degrade to the recognized

openspec/changes/archive/2026-07-21-robust-optional-integration/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-21

openspec/changes/archive/2026-07-21-robust-optional-integration/design.md

@@ -0,0 +1,44 @@
+## Context
+
+The optional-integration recipe lets a tool-owning extension depend on `@r3b1s/pi-repair-layer` optionally: it dynamically imports `@r3b1s/pi-repair-layer/pi`, and on failure discriminates "package genuinely absent" (fall back to the raw tool definition) from every other error (rethrow). The discrimination is deliberately narrow because a *present-but-broken* install — the package resolves but its own `typebox` runtime dependency does not — throws the same `MODULE_NOT_FOUND` / `ERR_MODULE_NOT_FOUND` codes, and swallowing that would silently run tools unwrapped while the user believes repairs are active.
+
+The recipe discriminated with a bare substring test, `message.includes("@r3b1s/pi-repair-layer")`. The jiti/require and compiled-binary error shapes (Claim 11 in `docs/research.md`) carry the importer *path*, e.g. `Cannot find module 'typebox/value' from '.../node_modules/@r3b1s/pi-repair-layer/dist/src/pipeline.js'`. That message names the missing *transitive* module (`typebox/value`) yet contains `@r3b1s/pi-repair-layer` as a path segment — so the bare substring test misclassified it as "absent."
+
+## Goals / Non-Goals
+
+**Goals:**
+- Make the absence matcher immune to the package name appearing as a `node_modules` path segment, so a present-but-broken install rethrows (loud) instead of being misread as absence.
+- Express the classification as a discrete, unit-testable predicate.
+- Keep the recipe copy-compatible for existing consumers; no breaking change; fixture, snippet, and spec in lockstep.
+
+**Non-Goals:**
+- Making the `/pi` entry dependency-free (bundling typebox). Evaluated and dropped — see Decision 2.
+- The loader shim package (Roadmap item C).
+- Changing repair behavior, the adapter API surface, or the pipeline internals.
+
+## Decisions
+
+### Decision 1: Match the package name as a quoted module specifier
+
+Change the recipe's absence predicate from `message.includes("@r3b1s/pi-repair-layer")` to match the name only where it appears as an imported specifier: an opening quote immediately followed by the name — `message.includes("'@r3b1s/pi-repair-layer")`.
+
+- **No trailing quote.** All three documented shapes render the missing module in single quotes, but jiti and the compiled binary name the *full subpath* (`'@r3b1s/pi-repair-layer/pi'`) while native ESM names the *bare package* (`'@r3b1s/pi-repair-layer'`). Both begin with quote-then-name; a trailing-quote match (`'@r3b1s/pi-repair-layer'`) would fail to match the subpath form and rethrow a genuine absence. So the match is opening-quote + name only.
+- **Why this excludes path segments.** In a path-bearing message the importer path is quoted as a whole (`from '/…/node_modules/@r3b1s/pi-repair-layer/…'`); the character after the opening quote is `/` (or a drive letter), never `@r3b1s`. So the package name inside a path segment is never immediately preceded by a quote and cannot match.
+- **Keep the code gate.** `(code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND")` remains the first gate; the quoted-name test is the discriminator.
+- **Extract for testability.** Lift the predicate into an exported `isRepairPackageAbsent(error)` so a unit test can feed it synthetic error shapes. vitest cannot force a dynamic `import()` to reject with an arbitrary error (a throwing mock factory is wrapped in vitest's own diagnostic), so the pure predicate is the testable seam.
+
+### Decision 2: Rely on the precise matcher; do not make the `/pi` entry dependency-free
+
+The `/pi` chain has exactly one third-party runtime import, `typebox/value`. Eliminating it (so a missing transitive dep is impossible) was considered via `bundledDependencies`, but that mechanism is rejected by pnpm's isolated node-linker — `pnpm publish` errors with `ERR_PNPM_BUNDLED_DEPENDENCIES_WITHOUT_HOISTED` — and this repo both installs isolated and publishes with `pnpm publish` (and steers away from npm via `scripts/bin/npm`/`npx` shims). The workarounds each cost more than they save:
+
+- **`nodeLinker: hoisted`** — one line, but switches the whole repo off pnpm's strict isolated linking (reintroducing phantom-dependency risk), against the grain of a deliberately strict setup; the hoisted reinstall was also pathologically slow in testing.
+- **Publish via npm** — splits the toolchain and fights the repo's pnpm-only shims.
+- **esbuild bundling** — robust and mechanism-independent, but adds a bundler to an intentionally `tsc`-only build.
+
+Decisive point: once Decision 1 lands, a present-but-broken install (`typebox` missing) already surfaces **correctly** — the matcher returns "not absent," the recipe rethrows, and the failure is loud at extension load. That is the exact behavior the discrimination always intended. Making the entry dependency-free would only convert a loud-and-correct failure into a can't-happen; it is a robustness nicety, not a correctness requirement. Deferred to the roadmap.
+
+## Risks / Trade-offs
+
+- **[A genuinely broken pi-repair-layer install fails the consumer's extension load]** → this is intended and correct: it is loud and diagnosable, strictly better than silently running unwrapped. Documented in the guide's caveats.
+- **[Quote-form assumptions across loaders]** → the opening-quote + name match is validated against all three documented shapes (jiti, native ESM, compiled binary) by the predicate unit test; a future loader change is caught by re-verifying Claim 11.
+- **[Snippet/fixture divergence]** → the doc snippet and `test/fixtures/optional-consumer.ts` are edited together; the existing "keep in sync" note flags this and the smoke test exercises the fixture.

openspec/changes/archive/2026-07-21-robust-optional-integration/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+The optional-integration recipe's absence detection uses a bare substring test (`message.includes("@r3b1s/pi-repair-layer")`), which false-positives when the package name appears as a `node_modules` path segment in a path-bearing error message (jiti and compiled-binary error shapes carry the importer path). A consumer integrating the recipe recently hit exactly this: a *present-but-broken* install — pi-repair-layer resolves but its `typebox` dependency does not — threw an error naming the missing transitive module while embedding pi-repair-layer only as a path segment, and the bare substring misclassified it as "absent," which would silently run tools unwrapped while the user believed repairs were active.
+
+## What Changes
+
+- Harden the absence-detection matcher in the canonical recipe to match the package name only as an **imported module specifier** — an opening quote immediately followed by the name (`'@r3b1s/pi-repair-layer`, no trailing quote so it matches both the bare-package ESM error and the `/pi` subpath error) — rather than a bare substring. A `node_modules/@r3b1s/pi-repair-layer/...` path segment is preceded by `/`, not a quote, so it can no longer read as absence.
+- Extract the classification into an exported `isRepairPackageAbsent(error)` predicate so it is directly unit-testable (a dynamic `import()` cannot be forced to reject with an arbitrary error under vitest).
+- With the corrected matcher, a present-but-broken install now surfaces **correctly** as a loud rethrow at load rather than a silent fallback — the discrimination the recipe always intended, now actually achieved.
+- Update the canonical recipe fixture (`test/fixtures/optional-consumer.ts`), the `docs/tool-owner-integration.md` snippet and caveats, and the `optional-integration` spec accordingly, keeping snippet and fixture in sync.
+- Add a matcher unit test proving a path-bearing transitive-missing error is not classified as absent.
+
+## Capabilities
+
+### New Capabilities
+<!-- none -->
+
+### Modified Capabilities
+- `optional-integration`: the documented absence check matches the package name as a quoted module specifier rather than a bare substring; the classification is expressed as an exported, unit-tested predicate; and the fixture/test coverage is extended with the path-segment false-positive case.
+
+## Impact
+
+- **Docs:** `docs/tool-owner-integration.md` recipe snippet, the "Discriminate before falling back" caveat, and the "Absence detection semantics" stability-contract bullet; `docs/research.md` Claim 11 detection-semantics rationale.
+- **Tests:** `test/fixtures/optional-consumer.ts` (extracted predicate + corrected matcher), a new matcher unit test.
+- **Specs:** modified `optional-integration`.
+- **No packaging/build change.** Making the `/pi` entry dependency-free (bundling `typebox`) was evaluated and dropped: it collides with the repo's pnpm isolated node-linker (`pnpm publish` rejects `bundledDependencies`) and the alternatives (repo-wide `nodeLinker: hoisted`, or publishing via npm) run against the repo's strict pnpm-only posture. The corrected matcher makes a broken install fail loudly and correctly, so eliminating the dependency is unnecessary for correctness (recorded as a roadmap consideration, not this change).
+- **Consumers:** no breaking change — the recipe stays copy-compatible; the matcher change is strictly more precise.

openspec/changes/archive/2026-07-21-robust-optional-integration/specs/optional-integration/spec.md

@@ -0,0 +1,35 @@
+## MODIFIED Requirements
+
+### Requirement: Documented optional integration recipe
+The tool-owner integration guide SHALL contain an optional-integration section presenting a complete, copyable fallback recipe by which a tool-owning extension attempts a dynamic import of the `pi` subpath and, when the package is absent, registers its unmodified tool definition. The recipe SHALL treat an import failure as "absent" only when the error code is `MODULE_NOT_FOUND` or `ERR_MODULE_NOT_FOUND` **and** the error message names `@r3b1s/pi-repair-layer` as a quoted module specifier — matched as an opening quote immediately followed by the package name (`'@r3b1s/pi-repair-layer`), with no trailing quote so it matches both the bare-package error (`'@r3b1s/pi-repair-layer'`) and the full-subpath error (`'@r3b1s/pi-repair-layer/pi'`) — rather than as a bare substring, so that the package name appearing only as a `node_modules` path segment does not classify a failure as absence; any other error SHALL be rethrown. The recipe SHALL express this classification as a discrete, exported, unit-testable predicate. The fallback branch SHALL emit a one-line stderr (or debug-channel) note identifying the extension and stating that its tools run unwrapped.
+
+#### Scenario: Package absent
+- **WHEN** a consumer following the recipe activates in a pi install where `@r3b1s/pi-repair-layer` is not resolvable
+- **THEN** the extension registers its raw tool definition, emits the single fallback note, and activation succeeds
+
+#### Scenario: Package present
+- **WHEN** the same consumer activates in an install where the package is resolvable
+- **THEN** the extension registers the adapted definition and no fallback note is emitted
+
+#### Scenario: Broken install is not misread as absent
+- **WHEN** the dynamic import fails with a module-not-found error naming a different (transitive) module
+- **THEN** the recipe rethrows instead of silently registering the unwrapped definition
+
+#### Scenario: Path-segment name does not cause a false positive
+- **WHEN** the classification predicate is given a module-not-found error whose message names a different missing module but includes `@r3b1s/pi-repair-layer` only as a `node_modules` path segment (e.g. `Cannot find module 'typebox/value' from '.../node_modules/@r3b1s/pi-repair-layer/...'`)
+- **THEN** the predicate does not classify the failure as absence and the recipe rethrows
+
+### Requirement: Optional-consumer fixture and smoke coverage
+The repository SHALL contain an optional-consumer fixture implementing the documented recipe, and the package smoke test SHALL exercise the recipe in a clean project in both states: with the packed package installed (adapter branch taken) and without it (fallback branch taken, fallback note emitted, raw definition registered). The fixture SHALL express the absence classification as an exported predicate, and the repository SHALL contain a unit test that feeds that predicate the documented module-not-found shapes — including a path-bearing transitive-missing error — and asserts that only genuine package absence is classified as absent.
+
+#### Scenario: Smoke test covers the absent branch
+- **WHEN** the package smoke test runs the optional-consumer fixture in a clean project without installing the package
+- **THEN** the fixture activates successfully, reports the fallback branch, and the run fails if the fallback note is missing or an error escapes
+
+#### Scenario: Predicate rejects a path-bearing transitive-missing error
+- **WHEN** the unit test invokes the exported absence predicate with a synthetic module-not-found error naming a transitive module while embedding `@r3b1s/pi-repair-layer` only as a path segment
+- **THEN** the predicate returns that the package is not absent
+
+#### Scenario: Predicate accepts the documented absent-package shapes
+- **WHEN** the unit test invokes the exported absence predicate with the native-ESM bare-package error and the jiti/compiled-binary full-subpath error
+- **THEN** the predicate returns that the package is absent for each