Add opt-in CNC scoped introspection

[Zetazzz]

Summary

• Add the independently publishable graphile-scoped-introspection package under graphile/.
• Keep the Constructive server on untouched upstream Graphile introspection by default.
• Add the strictly validated startup switch GRAPHILE_INTROSPECTION_MODE=stock|scoped-required; absence defaults to stock.
• Load the scoped replacement preset and apply scoped-only PgService settings only when scoped-required is selected.
• Keep the stock/scoped fresh-process performance comparison on the same explicit package boundary.
• Pass the benchmark database URL and opaque worker configuration through the core harness CLI protocol rather than perf-only environment variables.

Default and opt-in boundaries

stock (default)

• ConstructivePreset retains upstream PgIntrospectionPlugin.
• graphile-settings.makePgService is the upstream PostGraphile factory, without CNC service fields or introspection settings.
• The server does not load graphile-scoped-introspection, so its pinned upstream contract sentinel cannot affect stock startup.

scoped-required (opt-in)

• The server dynamically loads ScopedIntrospectionPreset while constructing the schema handler.
• makeScopedPgService selects dependency-closure catalog retention, bounded introspection settings, configured dependency schemas, and configured capability extensions.
• Missing required schemas, unapproved namespace crossings, incomplete type closure, and upstream contract drift remain fail closed.

Configuration is owned by @constructive-io/graphql-env and forwarded through typed GraphileOptions; the plugin package does not read process.env. Precedence remains defaults → config file → environment → runtime override, and malformed explicit mode values fail during option resolution.

Architecture

The scoped SQL is CNC-owned, static, and parameterized. It is adapted from the MIT-licensed pg-introspection@1.0.1 query structure and does not patch installed Graphile, Dataplan, or pg-introspection packages or import private package subpaths.

The introspection mode, catalog policy, and PgService option contracts have a single owner in @constructive-io/graphql-types. The scoped plugin re-exports those public types for compatibility; graphile-settings consumes the canonical contract directly and has no package dependency on graphile-scoped-introspection.

Database clients continue to use the normal three-argument withPgClientFromPgService(service, settings, callback) lifecycle. Final pool teardown remains the responsibility of PgService.release().

Validation

• @constructive-io/graphql-env: 1 suite / 14 tests passed, including default, valid values, malformed values, and config/env/runtime precedence.
• graphile-settings: 6 non-database suites / 47 tests passed, including upstream-default and scoped service wiring.
• @constructive-io/graphql-server: 14 suites / 145 tests passed, including proof that stock wiring does not invoke the scoped loader.
• graphile-scoped-introspection: 6 suites / 18 tests passed.
• @constructive-io/perf-harness: 6 suites / 11 tests passed, including the explicit worker CLI protocol.
• CJS and ESM builds passed for all six affected packages.
• Affected ESLint completed with zero errors (one pre-existing warning).
• Final PR-range regular and whitespace-ignoring diff statistics are identical; git diff --check against the PR base passed.
• pnpm install --frozen-lockfile and offline frozen-lockfile install passed.
• Compiled CJS and ESM server output retains a dynamic import, and compiled graphile-settings has no runtime reference to the scoped package.
• PostgreSQL 18.4 fresh-process smoke passed with distinct PIDs (28375, 28378), matching schema hash 67dae5a669c8aaa4a8cbf71a943cc0854f8ad610e835c03204c9e178c2cbe5f3, successful runtime validation in both cases, and no database URL in the report.

Follow-up

When Graphile progressive introspection is available, CNC can replace this concentrated opt-in package boundary with the upstream implementation while preserving the server configuration boundary.