@orkestrel/scaffold 0.0.101 → 0.0.103

package/dist/host/claude/rules/workspace.md

@@ -68,12 +68,19 @@ Give every selected environment and every face an alias: `src/styles`, each `src
 - `configs/agents/tsconfig.skills.json`: the scoped typecheck of the skill scripts; its presence selects the `skills` blueprint fact.
 - `configs/src/` and `configs/app/`: thin per-target wrappers, including optional
   `configs/src/*bin*` files. Shared logic remains in root configs.
-- `configs/helpers.ts`, `configs/browsers.ts`, and `configs/policy.ts`: the only permitted leaves
-  under `configs/`. Each imports nothing from the workspace, which is what keeps it a leaf, so no
-  `configs/types.ts` exists for one to import: each keeps its own types, data, and functions in its
-  one file, and the centralized-kind placement in `.claude/rules/architecture.md` does not reach a
-  leaf. Each `configs/src/*.config.ts` wrapper imports the root config and may import the permitted
-  leaves; keep shared build and project composition in the root config.
+- `configs/helpers.ts`, `configs/browsers.ts`, `configs/commands.ts`, and `configs/policy.ts`: the
+  only permitted leaves under `configs/`. Each imports nothing from the workspace, which is what
+  keeps it a leaf, so no `configs/types.ts` exists for one to import: each keeps its own types,
+  data, and functions in its one file, and the centralized-kind placement in
+  `.claude/rules/architecture.md` does not reach a leaf. Each `configs/src/*.config.ts` wrapper
+  imports the root config and may import the permitted leaves; keep shared build and project
+  composition in the root config.
+- Register the package's own Vitest browser commands in the `commands` record of
+  `configs/commands.ts`, the presence-owned seed scaffold plans beside `configs/browsers.ts`.
+  Import only a `node:` module or a package the manifest declares in `dependencies` or
+  `devDependencies` there: the root config bundles the file into every config load, builds
+  included, and the bundle resolves no workspace alias. Load workspace source inside a command
+  body through `context.project.vitest.import`, never through a static import.
 - Keep `configs/helpers.ts` free of any dependency a core-only workspace does not declare. It is
   vendored byte-identical to every workspace, so an import there must resolve in all of them.
   `configs/browsers.ts` exists for that reason: it imports `playwright` and
@@ -148,6 +155,9 @@ environment axis is one project per src/app axis × environment, plus one per ex
 - Give every browser project `optimizeDeps.include` of `@orkestrel/test`, `@orkestrel/test/browser`,
   `@orkestrel/contract` where the manifest declares it, and `vue` where the project renders Vue.
   Give a Node project no `optimizeDeps` setting.
+- Give every browser project `test.browser.commands` from `configs/commands.ts`: each root factory
+  that names the Playwright provider reads the record, and a project that spreads another
+  factory's `test.browser`, as `appVue` and every `journey:<variant>` project do, keeps it.
 
 The workspace-proof axis is cross-cutting. Each proof covers the whole workspace rather than
 one environment, so each is its own project:
@@ -165,6 +175,7 @@ one environment, so each is its own project:
 | `distribution`      | `tests/distribution.test.ts`                                   | The packed package installs and resolves through its public exports                                                                                                                                                         | `prepublishOnly`; absent when private |
 | `integration`       | `tests/integration.test.ts`                                    | The package's features work together end to end across environments                                                                                                                                                         | `test`                                |
 | `service`           | `tests/service/**/*.test.ts`                                   | The live external services this package drives, driven for real                                                                                                                                                             | `prepublishOnly`; `test` when private |
+| `studies`           | `tests/studies/**/*.test.ts`                                   | The consumer study proofs: installed packages driven through bounded subprocesses and protocol fixtures                                                                                                                     | `prepublishOnly`; `test` when private |
 
 - Define the Node `setup` project when `global` selects its seeded proof or a root file matches
   `tests/setup*.test.ts`, exact-case, other than `tests/setupBrowser.test.ts` and
@@ -173,6 +184,11 @@ one environment, so each is its own project:
   exact-case browser proof exists; collect those browser proof paths alone. For each registered project, emit
   its `test:setup` or `test:setup:browser` script and run it from `test`; otherwise emit neither its
   project nor its script.
+- Define the `studies` project when at least one exact-case `*.test.ts` file sits beneath
+  `tests/studies`, nested or direct, outside any `node_modules` or `.git` directory, which Vitest's
+  default exclude never collects. Give it `tests/setup.ts` alone: `tests/setupStudy.ts` is the
+  harness module those tests import, and it is no project's setup file. Scaffold plans no
+  `tests/setupStudy.ts`, and the root `studies/` directory is no test-project input.
 - When `tests/setupGlobal.ts` exists, give `src:browser`, `setup:browser`, and `integration` that
   module as their `globalSetup` option, and give no other project a global setup.
 - When a browser application selects the journey axis, register `journey:<variant>` projects
@@ -183,15 +199,16 @@ one environment, so each is its own project:
   from its application project, and run `test:journey` and one `test:journey:<framework>` per
   app-side browser extension after the application projects in `test`.
 
-`conformance`, `integration`, `distribution`, and `service` are separate subjects, not names for
-one.
+`conformance`, `integration`, `distribution`, `studies`, and `service` are separate subjects, not
+names for one.
 Keep `conformance` in `test`: measure this package against an installed official artifact, and start
 any server the proof drives itself. Keep `integration` in `test`: compose the workspace's public
 surfaces without packing, installing, or driving an external service. In a publishing workspace,
-run `distribution` and `service` from `prepublishOnly`: pack and install the package in
-`distribution`, and drive the real service with `tests/setupService.ts`, longer timeouts, and no file
+run `distribution`, `studies`, and `service` from `prepublishOnly`: pack and install the package in
+`distribution`, run the authored study proofs in `studies` after `npm test` and before the release
+proof, and drive the real service with `tests/setupService.ts`, longer timeouts, and no file
 parallelism in `service`. In a `private: true` workspace, never declare `prepublishOnly`; omit
-`distribution`, reach `service` from `test`, and retain the service project's isolated
+`distribution`, reach `studies` and then `service` from `test`, and retain each isolated project's
 configuration.
 
 One project sits on neither axis. `probe` includes `tmp/probes/**/*.test.ts` so an agent can run a
@@ -221,7 +238,8 @@ Setup assets:
 Scope with `test:src`, `test:src:core`, `test:src:<face>`, `test:app`, `test:app:server`, and
 equivalent scripts. Each cross-cutting project has its own script too: `test:policy`,
 `test:config`, `test:setup`, `test:setup:browser`, `test:journey`, `test:journey:<framework>`,
-`test:guides`, `test:conformance`, `test:distribution`, `test:integration`, `test:service`.
+`test:guides`, `test:conformance`, `test:distribution`, `test:integration`, `test:studies`,
+`test:service`.
 
 ## Typechecking and environment isolation
 
@@ -293,12 +311,9 @@ Build/check config alignment:
 
 - Typechecker: `vue-tsc` only where Vue SFCs are checked; `tsc` elsewhere.
 - Linter: Oxlint with `.oxlintrc.json`, independent from typechecking.
-- Place caller-selected local build inspection in `tools/artifacts/` or
-  `.orkestrel/<package>/instruments/**/tools/artifacts/`, and published runtime artifact
-  loaders in `src/server/artifacts/`. Permit computed ESM imports at those boundaries in
-  `.js`, `.mjs`, `.ts`, and `.mts` modules, and keep ordinary implementation dependencies
-  statically named. A source adapter admitted by a runtime loader remains a separately
-  selected inventory; it does not widen the loader's built-package admission.
+- Permit computed `import()` in every module, and refuse dynamic `require`. Name ordinary
+  implementation dependencies statically. In a module that imports a computed specifier,
+  document what selects it in the module's TSDoc.
 - Formatter: Oxfmt with `.oxfmtrc.json`.
 - Bundler: Vite.
 - Tests: Vitest; `@vitest/browser-playwright` for browser projects.

package/dist/host/configs/helpers.ts

@@ -1,4 +1,4 @@
-import type { Plugin, Rolldown } from 'vite'
+import type { Plugin, ResolvedConfig, Rolldown } from 'vite'
 import { parseSync, transformWithOxc, Visitor } from 'vite'
 import { fileURLToPath } from 'node:url'
 import { spawnSync } from 'node:child_process'
@@ -29,6 +29,29 @@ export function hasAsciiUrlControl(value: string): boolean {
 	return false
 }
 
+/**
+ * Runs a producer once and returns its value, or `undefined` when the producer throws.
+ *
+ * @remarks
+ * This leaf is vendored byte-identical to every workspace, so it imports no result helper and keeps
+ * its own value-returning form.
+ *
+ * @param produce - The producer to run once.
+ * @returns The producer's value, or `undefined` when it throws.
+ * @example
+ * ```ts
+ * attemptValue(() => decodeURI('%E0%A4%A')) // undefined
+ * attemptValue(() => decodeURI('%20')) // ' '
+ * ```
+ */
+export function attemptValue<T>(produce: () => T): T | undefined {
+	try {
+		return produce()
+	} catch {
+		return undefined
+	}
+}
+
 export const PACKAGE_MANIFEST_BYTES = 1_048_576
 export const ENVIRONMENT_MODULE_BYTES = 8_388_608
 
@@ -171,18 +194,10 @@ export function isBoundaryExemptModule(id: string): boolean {
 	) {
 		return true
 	}
-	let physicalId: string | undefined
-	try {
-		physicalId = physicalPath(id).replaceAll('\\', '/')
-	} catch {
-		physicalId = undefined
-	}
-	for (const candidate of physicalId === undefined ? [path] : [path, physicalId]) {
-		if (candidate.split('/').some((segment) => segment.toLowerCase() === 'node_modules')) {
-			return true
-		}
-	}
-	return false
+	const physicalId = attemptValue(() => physicalPath(id).replaceAll('\\', '/'))
+	return (physicalId === undefined ? [path] : [path, physicalId]).some((candidate) =>
+		candidate.split('/').some((segment) => segment.toLowerCase() === 'node_modules'),
+	)
 }
 
 export function isWorkspaceBoundaryModule(id: string): boolean {
@@ -190,12 +205,9 @@ export function isWorkspaceBoundaryModule(id: string): boolean {
 	const normalizedId = id.replaceAll('\\', '/')
 	const [path] = normalizedId.split(/[?#]/)
 	if (path === undefined) return false
-	let candidate = fileSystemPath(path)
-	try {
-		if (/^file:/i.test(candidate)) candidate = fileURLToPath(candidate)
-	} catch {
-		return false
-	}
+	const system = fileSystemPath(path)
+	const candidate = /^file:/i.test(system) ? attemptValue(() => fileURLToPath(system)) : system
+	if (candidate === undefined) return false
 	const rootRelative = /^\/(?:app|src)\/(?:core|browser|server|vue)\//.test(candidate)
 	const absoluteCandidate = rootRelative
 		? resolvePath(WORKSPACE_ROOT, candidate.slice(1))
@@ -247,6 +259,27 @@ export function packageNameOf(source: string): string | undefined {
 	return segments[0]
 }
 
+/**
+ * Fills a buffer from an open file handle until the handle ends, and reports how many bytes it read.
+ *
+ * @param handle - The open file descriptor.
+ * @param bytes - The buffer to fill; its length is the read ceiling.
+ * @param offset - The count of bytes already read into the buffer.
+ * @param limit - The largest total count the file may hold.
+ * @returns The total count read when the handle ends, or `undefined` when the count passes `limit`.
+ */
+export function readHandleBytes(
+	handle: number,
+	bytes: Buffer,
+	offset: number,
+	limit: number,
+): number | undefined {
+	const count = readSync(handle, bytes, offset, bytes.length - offset, null)
+	if (count === 0) return offset
+	const total = offset + count
+	return total > limit ? undefined : readHandleBytes(handle, bytes, total, limit)
+}
+
 export function readBoundedFile(path: string, limit: number): string | undefined {
 	if (!existsSync(path)) return undefined
 	try {
@@ -269,13 +302,8 @@ export function readBoundedFile(path: string, limit: number): string | undefined
 				return undefined
 			}
 			const bytes = Buffer.allocUnsafe(current.size + 1)
-			let offset = 0
-			for (;;) {
-				const count = readSync(handle, bytes, offset, bytes.length - offset, null)
-				if (count === 0) break
-				offset += count
-				if (offset > current.size) return undefined
-			}
+			const offset = readHandleBytes(handle, bytes, 0, current.size)
+			if (offset === undefined) return undefined
 			const final = fstatSync(handle)
 			if (
 				!final.isFile() ||
@@ -315,10 +343,7 @@ export function packageManifestName(directory: string): string | undefined {
 
 export function isPackageBoundary(directory: string): boolean {
 	const segments = directory.replaceAll('\\', '/').split('/')
-	let nodeModules = -1
-	for (const [index, segment] of segments.entries()) {
-		if (segment.toLowerCase() === 'node_modules') nodeModules = index
-	}
+	const nodeModules = segments.findLastIndex((segment) => segment.toLowerCase() === 'node_modules')
 	if (nodeModules < 0) return false
 	const packageSegments = segments.slice(nodeModules + 1)
 	return (
@@ -329,47 +354,39 @@ export function isPackageBoundary(directory: string): boolean {
 	)
 }
 
-export function packageRootOf(packageName: string, resolvedPath: string): string | undefined {
-	const physical = physicalPath(resolvedPath)
-	let current =
-		existsSync(physical) && lstatSync(physical).isDirectory() ? physical : dirname(physical)
-	for (;;) {
-		const boundary = isPackageBoundary(current)
-		const manifest = resolvePath(current, 'package.json')
-		if (boundary || existsSync(manifest)) {
-			return packageManifestName(current) === packageName ? realpathSync.native(current) : undefined
-		}
-		const parent = dirname(current)
-		if (parent === current) return undefined
-		current = parent
+/**
+ * Finds the nearest directory, starting at the given one, that is a package boundary or holds a
+ * `package.json`.
+ *
+ * @param current - The directory to start from.
+ * @returns That directory, or `undefined` when none up to the filesystem root qualifies.
+ */
+export function findPackageDirectory(current: string): string | undefined {
+	if (isPackageBoundary(current) || existsSync(resolvePath(current, 'package.json'))) {
+		return current
 	}
+	const parent = dirname(current)
+	return parent === current ? undefined : findPackageDirectory(parent)
 }
 
-export function packageRootForResolved(resolvedPath: string): string | undefined {
+export function packageRootOf(packageName: string, resolvedPath: string): string | undefined {
 	const physical = physicalPath(resolvedPath)
-	let current =
-		existsSync(physical) && lstatSync(physical).isDirectory() ? physical : dirname(physical)
-	for (;;) {
-		const boundary = isPackageBoundary(current)
-		const manifest = resolvePath(current, 'package.json')
-		if (boundary || existsSync(manifest)) {
-			return packageManifestName(current) === undefined ? undefined : realpathSync.native(current)
-		}
-		const parent = dirname(current)
-		if (parent === current) return undefined
-		current = parent
-	}
+	const directory = findPackageDirectory(
+		existsSync(physical) && lstatSync(physical).isDirectory() ? physical : dirname(physical),
+	)
+	return directory !== undefined && packageManifestName(directory) === packageName
+		? realpathSync.native(directory)
+		: undefined
 }
 
-export function trustedPackageRootFor(
-	target: string,
-	trustedPackageRoots: ReadonlySet<string>,
-): string | undefined {
-	const physical = physicalPath(target)
-	for (const root of trustedPackageRoots) {
-		if (containedPath(root, physical)) return root
-	}
-	return undefined
+export function packageRootForResolved(resolvedPath: string): string | undefined {
+	const physical = physicalPath(resolvedPath)
+	const directory = findPackageDirectory(
+		existsSync(physical) && lstatSync(physical).isDirectory() ? physical : dirname(physical),
+	)
+	return directory !== undefined && packageManifestName(directory) !== undefined
+		? realpathSync.native(directory)
+		: undefined
 }
 
 export function isStylesheetPath(path: string): boolean {
@@ -487,6 +504,84 @@ export function environmentSourceError(owner: string, source: string): string |
 	return undefined
 }
 
+/**
+ * Holds what a build plugin reads from the resolved Vite configuration after `configResolved` ran.
+ *
+ * @remarks
+ * Vite runs a plugin hook with its own context as `this`, so a plugin cannot keep this state on
+ * itself. Each plugin factory owns one instance and fills it from `configResolved`; before that hook
+ * runs, the instance holds the workspace defaults. The environment boundary plugin also keeps the
+ * physical package roots it has admitted here, because they outlive each hook call. The admitted
+ * roots are read through `locate` and never returned.
+ */
+export class BuildState {
+	#building = false
+	#output: string
+	#root = WORKSPACE_ROOT
+	#source = ''
+	readonly #trusted = new Set<string>()
+
+	constructor(output = WORKSPACE_ROOT) {
+		this.#output = output
+	}
+
+	/** Whether the resolved command is a build. */
+	get building(): boolean {
+		return this.#building
+	}
+
+	/** The absolute build output directory. */
+	get output(): string {
+		return this.#output
+	}
+
+	/** The physical project root. */
+	get root(): string {
+		return this.#root
+	}
+
+	/** The library entry path, or an empty string when the build has none. */
+	get source(): string {
+		return this.#source
+	}
+
+	/**
+	 * Admits one physical package root.
+	 *
+	 * @param root - The physical package root to admit.
+	 */
+	trust(root: string): void {
+		this.#trusted.add(root)
+	}
+
+	/**
+	 * Finds the admitted package root that contains a path.
+	 *
+	 * @param target - The path to place, followed through links to its physical location.
+	 * @returns The first admitted root, in admission order, that contains the path, or `undefined`
+	 * when none does.
+	 */
+	locate(target: string): string | undefined {
+		const physical = physicalPath(target)
+		return [...this.#trusted].find((root) => containedPath(root, physical))
+	}
+
+	/**
+	 * Reads the command, output directory, project root, and library entry from a resolved config.
+	 *
+	 * @param config - The resolved Vite configuration.
+	 */
+	resolve(config: ResolvedConfig): void {
+		this.#building = config.command === 'build'
+		this.#output = resolvePath(config.root, config.build.outDir)
+		this.#root = physicalPath(config.root)
+		this.#source =
+			config.build.lib !== false && typeof config.build.lib.entry === 'string'
+				? config.build.lib.entry
+				: ''
+	}
+}
+
 export function enforceOutputPath(configured: string, expected: string): void {
 	if (relative(expected, configured) !== '') {
 		throw new Error(
@@ -501,10 +596,10 @@ export function enforceOutputPath(configured: string, expected: string): void {
 	) {
 		throw new Error('[orkestrel-output-boundary] Build output must remain inside the workspace')
 	}
-	let current = WORKSPACE_ROOT
-	for (const segment of workspaceRelative.split(sep)) {
+	const segments = workspaceRelative.split(sep)
+	for (const [index, segment] of segments.entries()) {
 		if (segment.length === 0) continue
-		current = resolvePath(current, segment)
+		const current = resolvePath(WORKSPACE_ROOT, ...segments.slice(0, index + 1))
 		if (!existsSync(current)) continue
 		const status = lstatSync(current)
 		if (status.isSymbolicLink() || !status.isDirectory()) {
@@ -520,8 +615,7 @@ export function enforceOutputPath(configured: string, expected: string): void {
 
 export function outputBoundary(output: string): Plugin {
 	const expected = resolvePath(WORKSPACE_ROOT, output)
-	let configured = expected
-	let build = false
+	const state = new BuildState(expected)
 	return {
 		name: 'orkestrel-output-boundary',
 		enforce: 'pre',
@@ -549,11 +643,10 @@ export function outputBoundary(output: string): Plugin {
 					)
 				}
 			}
-			build = config.command === 'build'
-			configured = resolvePath(config.root, config.build.outDir)
+			state.resolve(config)
 		},
 		buildStart() {
-			if (build) enforceOutputPath(configured, expected)
+			if (state.building) enforceOutputPath(state.output, expected)
 		},
 	}
 }
@@ -778,23 +871,16 @@ export function rewriteBrowserSpecifier(content: string): string {
  * or at check.
  */
 export function declarationRollup(options: DeclarationRollupOptions): Plugin {
-	let output = WORKSPACE_ROOT
-	let source = ''
-	let build = false
+	const state = new BuildState()
 	return {
 		name: 'orkestrel-declaration-rollup',
 		configResolved(config) {
-			build = config.command === 'build'
-			output = resolvePath(config.root, config.build.outDir)
-			source =
-				config.build.lib !== false && typeof config.build.lib.entry === 'string'
-					? config.build.lib.entry
-					: ''
+			state.resolve(config)
 		},
 		closeBundle() {
-			if (!build) return
-			const declaration = source.replace(/\.tsx?$/, '.d.ts')
-			if (declaration === source) {
+			if (!state.building) return
+			const declaration = state.source.replace(/\.tsx?$/, '.d.ts')
+			if (declaration === state.source) {
 				throw new Error(
 					'[orkestrel-declaration-rollup] The face must build one TypeScript library entry',
 				)
@@ -811,7 +897,7 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
 				)
 			}
 			const scratch = mkdtempSync(join(tmpdir(), 'orkestrel-declarations-'))
-			const rollup = resolvePath(output, 'index.d.ts')
+			const rollup = resolvePath(state.output, 'index.d.ts')
 			try {
 				readCompilerOutput(compiler, [
 					'-p',
@@ -825,9 +911,8 @@ export function declarationRollup(options: DeclarationRollupOptions): Plugin {
 				])
 				const entry = resolvePath(scratch, relative(scope.root, declaration))
 				// A literal `import()` of the extractor reddens `tsc` in a workspace that does not
-				// install it, and a variable specifier reddens `import/no-dynamic-require`, so the
-				// literal `createRequire` call is the form that clears every gate in an app-only
-				// workspace.
+				// install it, so the literal `createRequire` call is the form that clears the
+				// typecheck in an app-only workspace.
 				const loaded: unknown = load('@microsoft/api-extractor')
 				if (!isExtractorModule(loaded)) {
 					throw new Error(
@@ -906,24 +991,15 @@ export async function environmentAssetSources(
 	const visitor = new Visitor({
 		ImportExpression(node) {
 			if (emitted) return
-			let value: string | undefined
-			if (node.source.type === 'Literal' && typeof node.source.value === 'string') {
-				value = node.source.value
-			} else if (node.source.type === 'TemplateLiteral' && node.source.expressions.length === 0) {
-				value = node.source.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw).join('')
-			} else {
-				const location = workspacePath(path)
-				if (
-					location !== undefined &&
-					/^(?:src\/server\/artifacts\/|tools\/artifacts\/|\.orkestrel\/[^/]+\/instruments\/(?:[^/]+\/)*tools\/artifacts\/).+\.(?:js|mjs|ts|mts)$/.test(
-						location,
-					)
-				)
-					return
-				throw new Error(
-					'[orkestrel-environment-boundary] Dynamic imports must use static string values',
-				)
-			}
+			const specifier = node.source
+			const value =
+				specifier.type === 'Literal' && typeof specifier.value === 'string'
+					? specifier.value
+					: specifier.type === 'TemplateLiteral' && specifier.expressions.length === 0
+						? specifier.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw).join('')
+						: undefined
+			// A computed specifier names no module to inspect statically.
+			if (value === undefined) return
 			const decoded = decodeAssetSource(value)
 			if (decoded === undefined) {
 				throw new Error('[orkestrel-environment-boundary] Module URLs must use valid URI encoding')
@@ -945,34 +1021,23 @@ export async function environmentAssetSources(
 			) {
 				return
 			}
-			let value: string | undefined
-			if (source?.type === 'Literal' && typeof source.value === 'string') {
-				const decoded = decodeAssetSource(source.value)
-				if (decoded === undefined) {
-					throw new Error('[orkestrel-environment-boundary] Asset URLs must use valid URI encoding')
-				}
-				value = decoded
-			} else if (source?.type === 'TemplateLiteral') {
-				const decodedQuasis: string[] = []
-				for (const quasi of source.quasis) {
-					const decoded = decodeAssetSource(quasi.value.cooked ?? quasi.value.raw)
-					if (decoded === undefined) {
-						throw new Error(
-							'[orkestrel-environment-boundary] Asset URLs must use valid URI encoding',
-						)
-					}
-					decodedQuasis.push(decoded)
-				}
-				if (source.expressions.length > 0) {
-					throw new Error(
-						'[orkestrel-environment-boundary] Asset URLs must use static string values',
-					)
-				}
-				value = decodedQuasis.join('__orkestrel__')
-			} else {
+			const parts =
+				source?.type === 'Literal' && typeof source.value === 'string'
+					? [source.value]
+					: source?.type === 'TemplateLiteral'
+						? source.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw)
+						: undefined
+			if (parts === undefined) {
 				throw new Error('[orkestrel-environment-boundary] Asset URLs must use static string values')
 			}
-			if (value === undefined) return
+			const decodedParts = parts.map((part) => decodeAssetSource(part))
+			if (decodedParts.includes(undefined)) {
+				throw new Error('[orkestrel-environment-boundary] Asset URLs must use valid URI encoding')
+			}
+			if (source?.type === 'TemplateLiteral' && source.expressions.length > 0) {
+				throw new Error('[orkestrel-environment-boundary] Asset URLs must use static string values')
+			}
+			const value = decodedParts.join('__orkestrel__')
 			if (
 				value.startsWith('.') ||
 				value.startsWith('/') ||
@@ -998,13 +1063,12 @@ export function environmentBoundary(
 		| 'app/server'
 		| 'app/vue',
 ): Plugin {
-	const trustedPackageRoots = new Set<string>()
-	let environmentRoot = WORKSPACE_ROOT
+	const state = new BuildState()
 	return {
 		name: 'orkestrel-environment-boundary',
 		enforce: 'pre',
 		configResolved(config) {
-			environmentRoot = physicalPath(config.root)
+			state.resolve(config)
 		},
 		async resolveId(source, importer) {
 			if (importer === undefined || !isWorkspaceBoundaryModule(importer)) return null
@@ -1014,7 +1078,7 @@ export function environmentBoundary(
 			if (sourceError !== undefined) this.error(sourceError)
 			const importerPath = workspacePath(importer)
 			const physicalImporter = physicalPath(importer)
-			const importerPackageRoot = trustedPackageRootFor(physicalImporter, trustedPackageRoots)
+			const importerPackageRoot = state.locate(physicalImporter)
 			if (importerPath === undefined && importerPackageRoot === undefined) return null
 			const [layer, environment] = importerPath?.split('/') ?? []
 			if (
@@ -1057,7 +1121,7 @@ export function environmentBoundary(
 							'Dependency package imports must resolve inside an exact physical package root',
 						)
 					}
-					trustedPackageRoots.add(mappedPackageRoot)
+					state.trust(mappedPackageRoot)
 				} else {
 					this.error('Dependency modules cannot import files outside their physical package root')
 				}
@@ -1074,7 +1138,7 @@ export function environmentBoundary(
 				if (packageRoot === undefined || !containedPath(packageRoot, physicalResolution)) {
 					return this.error('Resolved dependencies must remain inside their physical package root')
 				}
-				trustedPackageRoots.add(packageRoot)
+				state.trust(packageRoot)
 			}
 			const resolvedSource = workspacePath(resolution?.id ?? fallbackSource)
 			if (pathLike && resolvedSource === undefined && importerPackageRoot === undefined) {
@@ -1090,7 +1154,7 @@ export function environmentBoundary(
 		async load(id) {
 			if (!isWorkspaceBoundaryModule(id)) return null
 			const physicalImporter = physicalPath(id)
-			const trustedPackageRoot = trustedPackageRootFor(physicalImporter, trustedPackageRoots)
+			const trustedPackageRoot = state.locate(physicalImporter)
 			const inferredPackageRoot =
 				trustedPackageRoot === undefined ? packageRootForResolved(physicalImporter) : undefined
 			const packageRoot =
@@ -1144,12 +1208,12 @@ export function environmentBoundary(
 				}
 				for (const original of output.originalFileNames) {
 					const physical = physicalPath(
-						isAbsolute(original) ? original : resolvePath(environmentRoot, original),
+						isAbsolute(original) ? original : resolvePath(state.root, original),
 					)
 					if (isBoundaryExemptModule(original) || isBoundaryExemptModule(physical)) continue
 					const target = workspacePath(physical)
 					if (target === undefined) {
-						if (trustedPackageRootFor(physical, trustedPackageRoots) === undefined) {
+						if (state.locate(physical) === undefined) {
 							this.error('Environment modules cannot import files outside the workspace')
 						}
 						continue
@@ -1165,10 +1229,7 @@ export function environmentBoundary(
 				if (!isWorkspaceBoundaryModule(id)) continue
 				const target = workspacePath(id)
 				if (target === undefined) {
-					if (
-						isOutsideWorkspacePath(id) &&
-						trustedPackageRootFor(physicalPath(id), trustedPackageRoots) === undefined
-					) {
+					if (isOutsideWorkspacePath(id) && state.locate(physicalPath(id)) === undefined) {
 						this.error('Environment modules cannot import files outside the workspace')
 					}
 					continue
@@ -1183,7 +1244,7 @@ export function environmentBoundary(
 				if (!isWorkspaceBoundaryModule(id)) return null
 				const target = workspacePath(id)
 				const physicalImporter = physicalPath(id)
-				const importerPackageRoot = trustedPackageRootFor(physicalImporter, trustedPackageRoots)
+				const importerPackageRoot = state.locate(physicalImporter)
 				if (target === undefined) {
 					if (isOutsideWorkspacePath(id) && importerPackageRoot === undefined) {
 						this.error('Environment modules cannot import files outside the workspace')
@@ -1229,7 +1290,7 @@ export function environmentBoundary(
 									'Resolved dependencies must remain inside their physical package root',
 								)
 							}
-							trustedPackageRoots.add(packageRoot)
+							state.trust(packageRoot)
 						}
 						continue
 					}