@substrat-run/cli 0.49.6 → 0.50.0

package/dist/push.js

@@ -1,11 +1,12 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, basename, extname, relative, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { join, basename, delimiter, dirname, extname, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { webcrypto } from 'node:crypto';
 import { build } from 'esbuild';
-import { migrationDigestOf, DECLARED_OUTPUT_FIELDS_MAX, ASSET_PART_PREFIX, assetHash, assetsNeed, ATTACHMENT_BLOB_BINDING, buildPermissionRegistry, declaredOwnerGrants, ownerGrantSets, reservedKeyMessage, reservedKeyOffences, reservedKeysOf, declaresAttachmentTargets, DECLARED_MIGRATIONS_MAX, DECLARED_MIGRATIONS_SQL_BYTES_MAX, DEPLOY_MANIFEST_BYTES_SAFE, deployManifest, emittedModel, declaredMigrationDeclarations, sqlBytes, utf8Length, envVarSpec, runtimeNeeds, RUNTIME_BASELINE, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, assertDeclaredScopeStores, storeNamesOfBindings, manifestStoresOf, } from '@substrat-run/contracts';
+import { migrationDigestOf, DECLARED_OUTPUT_FIELDS_MAX, ASSET_PART_PREFIX, assetHash, assetsNeed, ATTACHMENT_BLOB_BINDING, buildPermissionRegistry, declaredOwnerGrants, ownerGrantSets, reservedKeyMessage, reservedKeyOffences, reservedKeysOf, declaresAttachmentTargets, DECLARED_MIGRATIONS_MAX, DECLARED_MIGRATIONS_SQL_BYTES_MAX, DEPLOY_MANIFEST_BYTES_SAFE, deployManifest, emittedModel, declaredMigrationDeclarations, sqlBytes, utf8Length, envVarSpec, runtimeNeeds, RUNTIME_BASELINE, PLATFORM_FEATURES_HEADER, PLATFORM_FEATURE_SCOPE_SWEEPER, assertDeclaredScopeStores, storeNamesOfBindings, manifestStoresOf, pushedConnectorProblems, verticalConnectorDeclarations, } from '@substrat-run/contracts';
 import { lint, loadConfig as loadBoundaryLintConfig, resolvePackages, declaredEngines, formatViolations, maskSource, } from '@substrat-run/boundary-lint';
 import { walkPages } from '@substrat-run/control-plane-client';
 import { checkMigrationDataLoss } from './data-loss-check.js';
@@ -251,6 +252,32 @@ export function boundManifest(manifest, warn = console.warn) {
     const { migrations: _omitted, ...rest } = manifest;
     return rest;
 }
+/**
+ * Bundle `contents` — an ES module whose imports resolve from `dir` — with every package left
+ * external, write it INTO `dir` so Node resolves those imports (@substrat-run/*, and any node
+ * addon a node-ful entry pulls) from the vertical's own node_modules, import it, and remove it.
+ * The unique name avoids the ESM import cache across pushes.
+ */
+async function importBundledAsData(dir, stem, contents) {
+    const out = join(dir, `.substrat.${stem}.${Date.now()}.mjs`);
+    try {
+        await build({
+            stdin: { contents, resolveDir: resolve(dir), sourcefile: `substrat-${stem}.mjs`, loader: 'js' },
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            packages: 'external',
+            outfile: out,
+            logLevel: 'silent',
+        });
+        // @vite-ignore: this is a real filesystem path imported at runtime, never a bundler input —
+        // the comment keeps vitest/vite from trying to resolve it through their transform pipeline.
+        return (await import(/* @vite-ignore */ pathToFileURL(out).href));
+    }
+    finally {
+        rmSync(out, { force: true });
+    }
+}
 export async function deriveDeclaredSurface(dir) {
     const pkgPath = join(dir, 'package.json');
     // Named rather than left as an ENOENT trace: `substrat push --check` (#1205) is run from
@@ -274,121 +301,173 @@ export async function deriveDeclaredSurface(dir) {
     if (!existsSync(entryPath)) {
         throw new Error(`substrat.permissions points at "${entry}", which does not exist under ${dir}.`);
     }
-    // Written INTO the vertical dir so Node resolves the externalised imports (@substrat-run/*,
-    // and any node addon a node-ful entry pulls) from the vertical's own node_modules. Removed
-    // immediately after import. The unique name avoids the ESM import cache across pushes.
-    const out = join(dir, `.substrat.permissions.${Date.now()}.mjs`);
+    let mod;
     try {
-        let mod;
+        // The entry, plus the vertical's OWN kernel (#1677), imported where the vertical
+        // resolves it: `packages: 'external'` keeps the specifier, so it loads from the
+        // vertical's node_modules. Optional — a vertical with none still reads as data.
+        // Both absolute: a CI job names the dir relatively (`substrat push demos/ticket0`), and
+        // a relative path written as an import specifier is a BARE one — `packages: 'external'`
+        // then keeps `demos/…` as a package named `demos`, which Node cannot find. `join` also
+        // strips a leading `./`, so spelling the dir `./demos/…` would not have saved it.
+        // The specifiers are the VERTICAL's packages, resolved from its node_modules, never the CLI's
+        // own dependencies; spelled through `q` so `lint:deps`, which reads text, does not count them.
+        const q = JSON.stringify;
+        mod = await importBundledAsData(dir, 'permissions', `export * from ${q(resolve(entryPath))};\n` +
+            `export const __substratKernel = await import(${q('@substrat-run/kernel')}).catch(() => null);\n` +
+            // The spine the data-loss replay builds first (#2321), from the vertical's own
+            // adapter-sqlite — imported only when a replay runs, since it loads a native driver.
+            `export const __substratSpine = () => import(${q('@substrat-run/adapter-sqlite')}).then((m) => m.SCOPE_SPINE_DDL, () => undefined);\n` +
+            // Where that kernel resolves, for the replay's own process to import (#2321).
+            `export const __substratKernelUrl = (() => { try { return import.meta.resolve(${q('@substrat-run/kernel')}); } catch { return null; } })();\n`);
+    }
+    catch (e) {
+        // The third silent-until-deploy failure (#1205): the entry exists and exports the right
+        // name, but cannot be read OUTSIDE the vertical's runtime — a worker-only import, a
+        // `node:*` on a path the bundler follows, an import-time side effect wanting a live host.
+        // Named as that, rather than as a bare esbuild/ESM stack, because the remedy is specific:
+        // `definePermissions(...)` returns a plain object, so the module holding it must stay
+        // importable as data.
+        throw new Error(`substrat.permissions points at "${entry}", which could not be bundled and imported as data — ` +
+            `the declared surface must be readable without a live host (no worker-only imports on the ` +
+            `path it pulls in, no import-time side effects).\n${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!mod.permissions) {
+        throw new Error(`${entry} exports no \`permissions\`. Export ` +
+            `\`const permissions = definePermissions({ modules, roles, entityGrants })\`.`);
+    }
+    let spec;
+    if (mod.envSpec !== undefined) {
+        if (!Array.isArray(mod.envSpec)) {
+            throw new Error(`${entry} exports \`envSpec\`, but it is not an array of env-var specs.`);
+        }
         try {
-            await build({
-                // The entry, plus the vertical's OWN kernel (#1677), imported where the vertical
-                // resolves it: `packages: 'external'` keeps the specifier, so it loads from the
-                // vertical's node_modules. Optional — a vertical with none still reads as data.
-                // Both absolute: a CI job names the dir relatively (`substrat push demos/ticket0`), and
-                // a relative path written as an import specifier is a BARE one — `packages: 'external'`
-                // then keeps `demos/…` as a package named `demos`, which Node cannot find. `join` also
-                // strips a leading `./`, so spelling the dir `./demos/…` would not have saved it.
-                stdin: {
-                    contents: `export * from ${JSON.stringify(resolve(entryPath))};\n` +
-                        `export const __substratKernel = await import('@substrat-run/kernel').catch(() => null);\n` +
-                        // The spine the data-loss replay builds first (#2321), from the vertical's own
-                        // adapter-sqlite — imported only when a replay runs, since it loads a native driver.
-                        `export const __substratSpine = () => import('@substrat-run/adapter-sqlite').then((m) => m.SCOPE_SPINE_DDL, () => undefined);\n` +
-                        // Where that kernel resolves, for the replay's own process to import (#2321).
-                        `export const __substratKernelUrl = (() => { try { return import.meta.resolve('@substrat-run/kernel'); } catch { return null; } })();\n`,
-                    resolveDir: resolve(dir),
-                    sourcefile: 'substrat-surface.mjs',
-                    loader: 'js',
-                },
-                bundle: true,
-                platform: 'node',
-                format: 'esm',
-                packages: 'external',
-                outfile: out,
-                logLevel: 'silent',
-            });
-            // @vite-ignore: this is a real filesystem path imported at runtime, never a bundler input —
-            // the comment keeps vitest/vite from trying to resolve it through their transform pipeline.
-            mod = (await import(/* @vite-ignore */ pathToFileURL(out).href));
+            spec = mod.envSpec.map((e) => envVarSpec.parse(e));
         }
         catch (e) {
-            // The third silent-until-deploy failure (#1205): the entry exists and exports the right
-            // name, but cannot be read OUTSIDE the vertical's runtime — a worker-only import, a
-            // `node:*` on a path the bundler follows, an import-time side effect wanting a live host.
-            // Named as that, rather than as a bare esbuild/ESM stack, because the remedy is specific:
-            // `definePermissions(...)` returns a plain object, so the module holding it must stay
-            // importable as data.
-            throw new Error(`substrat.permissions points at "${entry}", which could not be bundled and imported as data — ` +
-                `the declared surface must be readable without a live host (no worker-only imports on the ` +
-                `path it pulls in, no import-time side effects).\n${e instanceof Error ? e.message : String(e)}`);
-        }
-        if (!mod.permissions) {
-            throw new Error(`${entry} exports no \`permissions\`. Export ` +
-                `\`const permissions = definePermissions({ modules, roles, entityGrants })\`.`);
+            throw new Error(`${entry} exports an \`envSpec\` that is not a valid env-var spec list.\n` +
+                `${e instanceof Error ? e.message : String(e)}`);
         }
-        let spec;
-        if (mod.envSpec !== undefined) {
-            if (!Array.isArray(mod.envSpec)) {
-                throw new Error(`${entry} exports \`envSpec\`, but it is not an array of env-var specs.`);
-            }
-            try {
-                spec = mod.envSpec.map((e) => envVarSpec.parse(e));
-            }
-            catch (e) {
-                throw new Error(`${entry} exports an \`envSpec\` that is not a valid env-var spec list.\n` +
-                    `${e instanceof Error ? e.message : String(e)}`);
-            }
-        }
-        // #2430: a key a module declares `holder: 'system'` in a role a person can hold, an entity grant
-        // shape or an owner grant (a module's, or this package's `substrat.ownerGrants`, which an install
-        // grants its owner), refused before anything uploads, in `lint:permissions`' own words. The
-        // registry build below refuses most of it too; this is the message that names the remedy.
-        const reserved = reservedKeysOf(mod.permissions.modules);
-        const offences = reservedKeyOffences({
-            roles: mod.permissions.roles,
-            grants: mod.permissions.entityGrants ?? [],
-            personGrants: ownerGrantSets(mod.permissions.modules, ownerGrants.grants),
-        }, reserved);
-        if (offences.length > 0)
-            throw new Error(reservedKeyMessage(basename(resolve(dir)), entry, offences, reserved));
-        // #1234: the declared half of a declared-vs-observed finding — what the modules say
-        // they emit and consume, which exists nowhere off their manifests.
-        const declaredEvents = flattenDeclaredEvents(mod.permissions);
-        return {
-            registry: buildPermissionRegistry(mod.permissions),
-            modules: mod.permissions.modules.map(({ manifest }) => ({
-                id: manifest.id,
-                permissions: manifest.permissions.map(({ key, description, holder }) => ({
-                    key, description, ...(holder ? { holder } : {}),
-                })),
-                ...(manifest.ownerGrants ? { ownerGrants: manifest.ownerGrants } : {}),
+    }
+    // #2430: a key a module declares `holder: 'system'` in a role a person can hold, an entity grant
+    // shape or an owner grant (a module's, or this package's `substrat.ownerGrants`, which an install
+    // grants its owner), refused before anything uploads, in `lint:permissions`' own words. The
+    // registry build below refuses most of it too; this is the message that names the remedy.
+    const reserved = reservedKeysOf(mod.permissions.modules);
+    const offences = reservedKeyOffences({
+        roles: mod.permissions.roles,
+        grants: mod.permissions.entityGrants ?? [],
+        personGrants: ownerGrantSets(mod.permissions.modules, ownerGrants.grants),
+    }, reserved);
+    if (offences.length > 0)
+        throw new Error(reservedKeyMessage(basename(resolve(dir)), entry, offences, reserved));
+    // #1234: the declared half of a declared-vs-observed finding — what the modules say
+    // they emit and consume, which exists nowhere off their manifests.
+    const declaredEvents = flattenDeclaredEvents(mod.permissions);
+    const connectors = await readDeclaredConnectors(dir, pkg.substrat?.connectors);
+    const registry = buildPermissionRegistry(mod.permissions);
+    if (connectors) {
+        // The standing grants join the registry, so widening them moves the permission digest the
+        // promote checkpoint acknowledges. Sorted like the rest of the registry, so the digest is a
+        // function of content. Absent when there are none: a digest must not move for a vertical
+        // without connectors.
+        registry.connectors = connectors
+            .map((c) => ({ provider: c.provider, grants: [...c.grants].sort() }))
+            .sort((a, b) => a.provider.localeCompare(b.provider));
+        assertConnectorsAdmissible(basename(resolve(dir)), pkg.substrat?.connectors, connectors, registry, mod.permissions);
+    }
+    return {
+        registry,
+        modules: mod.permissions.modules.map(({ manifest }) => ({
+            id: manifest.id,
+            permissions: manifest.permissions.map(({ key, description, holder }) => ({
+                key, description, ...(holder ? { holder } : {}),
             })),
-            envSpec: spec,
-            // #1232: the same import that yields the permission surface already holds every
-            // module manifest — the schedules ride out of it with zero extra reads.
-            schedules: flattenDeclaredSchedules(mod.permissions),
-            freshness: flattenDeclaredFreshness(mod.permissions),
-            declaredEvents: declaredEvents.events,
-            declaredEventsTruncated: declaredEvents.truncated,
-            declaresAttachments: declaresAttachmentTargets(mod.permissions.modules.map((m) => m.manifest)),
-            migrations: flattenDeclaredMigrations(mod.permissions, typeof mod.__substratKernel?.moduleMigrations === 'function'
-                ? mod.__substratKernel.moduleMigrations
-                : undefined),
-            replay: {
-                kernel: mod.__substratKernel ?? null,
-                kernelUrl: typeof mod.__substratKernelUrl === 'string' ? mod.__substratKernelUrl : null,
-                modules: mod.permissions.modules,
-                spineDdl: async () => {
-                    const ddl = await mod.__substratSpine?.();
-                    return typeof ddl === 'string' ? ddl : undefined;
-                },
+            ...(manifest.ownerGrants ? { ownerGrants: manifest.ownerGrants } : {}),
+        })),
+        envSpec: spec,
+        // #1232: the same import that yields the permission surface already holds every
+        // module manifest — the schedules ride out of it with zero extra reads.
+        schedules: flattenDeclaredSchedules(mod.permissions),
+        freshness: flattenDeclaredFreshness(mod.permissions),
+        declaredEvents: declaredEvents.events,
+        declaredEventsTruncated: declaredEvents.truncated,
+        declaresAttachments: declaresAttachmentTargets(mod.permissions.modules.map((m) => m.manifest)),
+        migrations: flattenDeclaredMigrations(mod.permissions, typeof mod.__substratKernel?.moduleMigrations === 'function'
+            ? mod.__substratKernel.moduleMigrations
+            : undefined),
+        replay: {
+            kernel: mod.__substratKernel ?? null,
+            kernelUrl: typeof mod.__substratKernelUrl === 'string' ? mod.__substratKernelUrl : null,
+            modules: mod.permissions.modules,
+            spineDdl: async () => {
+                const ddl = await mod.__substratSpine?.();
+                return typeof ddl === 'string' ? ddl : undefined;
             },
-        };
+        },
+        connectors,
+    };
+}
+/**
+ * The vertical's connectors (vertical-connectors.md §5.1): `substrat.connectors` names a module
+ * exporting `connectors`, a `defineConnectors(...)` value whose `declarations()` is the static half
+ * a push carries. Imported as data the way the permission entry is. Undefined when the package
+ * names no such module or its declarations are empty.
+ */
+async function readDeclaredConnectors(dir, entry) {
+    if (entry === undefined)
+        return undefined;
+    if (typeof entry !== 'string' || entry.length === 0) {
+        throw new Error(`${basename(resolve(dir))}/package.json declares \`substrat.connectors\` as ${JSON.stringify(entry)}, ` +
+            `not a path. Point it at the module that exports \`connectors = defineConnectors(...)\`.`);
     }
-    finally {
-        rmSync(out, { force: true });
+    const entryPath = join(dir, entry);
+    if (!existsSync(entryPath))
+        throw new Error(`substrat.connectors points at "${entry}", which does not exist under ${dir}.`);
+    let mod;
+    try {
+        mod = await importBundledAsData(dir, 'connectors', `export * from ${JSON.stringify(resolve(entryPath))};\n`);
+    }
+    catch (e) {
+        throw new Error(`substrat.connectors points at "${entry}", which could not be bundled and imported as data — ` +
+            `the connectors module must be importable without a live host (no worker-only imports on the ` +
+            `path it pulls in, no import-time side effects).\n${e instanceof Error ? e.message : String(e)}`);
+    }
+    const declarations = mod.connectors?.declarations;
+    if (typeof declarations !== 'function') {
+        throw new Error(`${entry} exports no \`connectors\` with a \`declarations()\`. Export ` +
+            `\`const connectors = defineConnectors({ … })\` from @substrat-run/vertical-host/connectors.`);
+    }
+    let raw;
+    try {
+        raw = declarations.call(mod.connectors);
     }
+    catch (e) {
+        throw new Error(`${entry}: \`connectors.declarations()\` threw.\n${e instanceof Error ? e.message : String(e)}`);
+    }
+    const parsed = verticalConnectorDeclarations.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `  - ${i.path.length ? `${i.path.join('.')}: ` : ''}${i.message}`);
+        throw new Error(`${entry} declares connectors a push cannot carry:\n${issues.join('\n')}`);
+    }
+    return parsed.data.length > 0 ? parsed.data : undefined;
+}
+/**
+ * vertical-connectors.md §7.1, the refusals the static half allows: a standing grant the registry
+ * does not declare or reserves to a system principal (`pushedConnectorProblems`, the check the
+ * control plane repeats), and a routed event type no module of the vertical declares it emits.
+ */
+function assertConnectorsAdmissible(vertical, entry, connectors, registry, permissions) {
+    const emitted = new Set(permissions.modules.flatMap((m) => (m.manifest.events?.emits ?? []).map((e) => e.type)));
+    const problems = [
+        ...pushedConnectorProblems({ connectors, registry }),
+        ...connectors.flatMap((c) => c.events.filter((t) => !emitted.has(t)).map((t) => `connector ${c.provider} routes ${t}, which no module of ${vertical} declares it emits`)),
+    ];
+    if (problems.length === 0)
+        return;
+    throw new Error(`${vertical}: ${entry} declares connectors a push cannot carry:\n${problems.map((p) => `  - ${p}`).join('\n')}\n` +
+        `Remedy: a standing grant must be a key a module declares and does not reserve (\`holder: 'system'\`); ` +
+        `a routed event must be one a module's manifest lists under \`events.emits\`.`);
 }
 /** The declared permission surface alone — `deriveDeclaredSurface` for the callers that
  *  want only the registry (D-41). */
@@ -527,6 +606,13 @@ export function formatPermissionSurface(surface, label) {
             lines.push(`  ${l.provider}: ${l.operation} holding ${l.permission}`);
         }
     }
+    // A vertical-defined connector's standing grants, which the digest also covers.
+    if (registry.connectors?.length) {
+        lines.push('', 'connector standing grants:');
+        for (const c of registry.connectors) {
+            lines.push(`  ${c.provider}: ${c.grants.length ? c.grants.join(', ') : '(none)'}`);
+        }
+    }
     if (surface.envSpec) {
         lines.push('', `env keys (code-declared, #1206): ${surface.envSpec.length}`);
         for (const e of surface.envSpec) {
@@ -1206,18 +1292,84 @@ export function assertAttachmentBindingFree(bindings, blobStores) {
 export function generatedConfigPath(dir) {
     return resolve(dir, '.wrangler.substrat.json');
 }
+/**
+ * The vertical's own wrangler: the script its `bin` names, and the version that script is.
+ *
+ * Resolved the way Node resolves an import from the vertical (its `node_modules`, then each
+ * parent's, so a workspace that hoists wrangler to its root still finds it), and run as
+ * `node <bin>`. Not through `npx`, for two reasons:
+ *
+ *   - On Windows `npx` is `npx.cmd`. Node will not spawn a batch file without a shell
+ *     (CVE-2024-27980), and through a shell every argument is parsed twice — by cmd.exe and
+ *     again by the batch file's `%*` — so a build path holding a space, `&`, `%` or `^` cannot
+ *     be passed safely. `push` failed there with `spawnSync npx ENOENT` before it built anything.
+ *   - `npx` downloads the newest wrangler when the project has none, without asking when stdin
+ *     is not a TTY. The bundle a deploy ships then depends on the day it was built. The
+ *     project's pinned wrangler is the only one this runs; a project without one is told so.
+ *
+ * Every node_modules directory is checked for `wrangler/package.json` on disk rather than
+ * through `require.resolve('wrangler/package.json')`, so the lookup never depends on which
+ * subpaths a given wrangler release lists in its `exports`.
+ */
+export function resolveWrangler(dir) {
+    const root = resolve(dir);
+    const candidates = createRequire(join(root, 'package.json')).resolve.paths('wrangler') ?? [];
+    const pkgFile = candidates.map((nm) => join(nm, 'wrangler', 'package.json')).find((f) => existsSync(f));
+    if (!pkgFile) {
+        throw new Error([
+            `wrangler is not installed in this project (${root}).`,
+            '  substrat push builds the Worker with the wrangler your project pins, and never downloads one.',
+            '  Add it as a devDependency, then push again:',
+            '    npm install --save-dev wrangler    (or: pnpm add -D wrangler, yarn add -D wrangler)',
+            '  Yarn Plug\'n\'Play installs no node_modules, which the push reads: set `nodeLinker: node-modules`',
+            '  in .yarnrc.yml and run `yarn install`.',
+        ].join('\n'));
+    }
+    const pkg = JSON.parse(readFileSync(pkgFile, 'utf8'));
+    const rel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.wrangler;
+    if (!rel)
+        throw new Error(`${pkgFile} names no \`wrangler\` bin — reinstall wrangler in this project`);
+    return { bin: resolve(dirname(pkgFile), rel), version: pkg.version ?? 'unknown' };
+}
+/**
+ * The environment wrangler builds in: this process's, with the project's `node_modules/.bin`
+ * directories (its own, then each parent's, nearest first) and Node's own directory put in
+ * front of PATH.
+ *
+ * That is what `npx` used to give it, and the project's build command depends on it. Wrangler
+ * runs `build.command` (`runtimeNeeds.build`) through a shell on the PATH it was handed, so a
+ * build of `vite build` or `tsc` finds the project's own `vite` or `tsc` only when its `.bin`
+ * is there. A CLI installed globally, or started from a repository root, has no such entry.
+ */
+export function wranglerEnv(dir, env = process.env) {
+    const bins = [];
+    for (let at = resolve(dir);; at = dirname(at)) {
+        bins.push(join(at, 'node_modules', '.bin'));
+        if (dirname(at) === at)
+            break;
+    }
+    // Windows names it `Path`, and environment keys are case-insensitive there. A copy is a
+    // plain object, so set the key that is already present instead of adding a second one.
+    const key = Object.keys(env).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH';
+    const path = [...bins, dirname(process.execPath), env[key]].filter(Boolean).join(delimiter);
+    return { ...env, [key]: path };
+}
 const checkedWorkerBundles = new WeakSet();
 /** Run Wrangler's configured build once, then check the source graph it produced. */
 export async function prepareWorkerBundle(dir, resolved = resolveWranglerConfig(dir), label = 'Worker', output = 'stdout') {
     const { cfg, needs } = resolved;
+    // Before anything is written: a project without wrangler leaves no temp dir or config behind.
+    const wrangler = resolveWrangler(dir);
     const out = mkdtempSync(join(tmpdir(), 'substrat-build-'));
     const generated = needs ? generatedConfigPath(dir) : undefined;
-    (output === 'stderr' ? console.error : console.log)(`building ${label} …`);
+    (output === 'stderr' ? console.error : console.log)(`building ${label} with wrangler ${wrangler.version} …`);
     try {
         if (generated)
             writeFileSync(generated, JSON.stringify(cfg, null, 2) + '\n');
         try {
-            execFileSync('npx', ['wrangler', 'deploy', '--dry-run', '--outdir', out, ...(generated ? ['--config', generated] : [])], { cwd: dir, stdio: output === 'stderr' ? ['inherit', 2, 2] : 'inherit' });
+            // `node <wrangler bin>`, no shell: each argument reaches wrangler as one argv entry on
+            // every OS, so `out` and `generated` may hold spaces or non-ASCII (see resolveWrangler).
+            execFileSync(process.execPath, [wrangler.bin, 'deploy', '--dry-run', '--outdir', out, ...(generated ? ['--config', generated] : [])], { cwd: dir, env: wranglerEnv(dir), stdio: output === 'stderr' ? ['inherit', 2, 2] : 'inherit' });
         }
         finally {
             if (generated)
@@ -1286,7 +1438,7 @@ export async function push(opts) {
     // below. Throws if the vertical declares no surface: absence is never a silent empty registry.
     // The same import reads the entry's `envSpec` export (#1206); when it exists it is the copy
     // that ships, and a drifted package.json duplicate refuses the push.
-    const { registry, modules: declaredModules, envSpec: derivedEnvSpec, schedules, freshness, declaredEvents, declaredEventsTruncated, migrations, declaresAttachments, replay, } = await deriveDeclaredSurface(opts.dir);
+    const { registry, modules: declaredModules, envSpec: derivedEnvSpec, schedules, freshness, declaredEvents, declaredEventsTruncated, migrations, declaresAttachments, replay, connectors, } = await deriveDeclaredSurface(opts.dir);
     // #2321: the vertical's migrations, replayed against a populated in-memory scope through its own
     // kernel's data-loss fence — before anything is uploaded, so a migration that would close every
     // populated scope at promote is refused here instead. Throws on a refusal.
@@ -1431,6 +1583,10 @@ export async function push(opts) {
         // `[]` when undeclared, because absence means "pre-#1706 push" (unenforced) and a
         // new-CLI push must not read as that. Enforcement input, versioned with the code.
         calls: opts.calls ?? [],
+        // The vertical's connector declarations (vertical-connectors.md §5.1), absent when none, so a
+        // vertical without connectors pushes the manifest it did before. Their standing grants are
+        // also in `registry.connectors`, which the permission digest covers.
+        ...(connectors ? { connectors } : {}),
         // The declared permission surface travels with the bundle (D-39/D-41): keys+descriptions,
         // role templates, entity-grant shapes. Required — its content hash is digests.permission.
         registry,