Add @dynamic filter selector; metadata-first scoped resolution for decorator filters; register new reserved env vars; docs

Author: theoephraim

packages/varlock-website/src/content/docs/guides/dynamic-config.mdx

@@ -82,13 +82,39 @@ See framework-specific recipes:
 
 ## Prerender/build guardrails
 
-Dynamic config should not be consumed in static prerender/build contexts unless explicitly designed for it.
+Baking a public+dynamic value into prerendered output defeats its purpose: you marked it `@dynamic` because the build-time value should not be frozen. Varlock catches this per framework:
 
-Varlock runtime can detect this and warn/error when dynamic keys are accessed during prerender/build phases, helping catch accidental usage early.
+- **Next.js**: accessing a public+dynamic key during server rendering marks the route dynamic (it will not be statically prerendered), including access from nested components.
+- **Vite-based frameworks** (Astro, SvelteKit, etc.): accessing a public+dynamic key while a build/prerender is running throws an error. Set `_VARLOCK_DYNAMIC_BUILD_ACCESS_MODE=warn` to downgrade it to a warning (e.g. while migrating an existing app).
+
+Sensitive values are not subject to this guard. Reading a sensitive value server-side during a static build (e.g. using an API key to fetch data while generating pages) is fine; leak detection separately errors if the value itself ends up in the built output.
+
+## Filtering by static/dynamic
+
+The [`--filter` selector language](/reference/cli-commands/#filtering-items) supports a `@dynamic` selector (negate it for static items), so you can scope a load or a generated file to one side of the split:
+
+```bash
+varlock load --filter="!@dynamic"            # only build-time-inlineable items
+varlock load --filter="@dynamic"             # only runtime-resolved items
+varlock run --filter="@dynamic" -- node app  # inject only runtime values
+```
+
+```env-spec title=".env.schema"
+# generate a module covering only runtime public values
+# @generateTsTypes(path=public-runtime-env.d.ts, filter="@dynamic,!@sensitive")
+```
+
+Like all filters, `@dynamic` filters scope **resolution and validation**, not just output: varlock resolves each item's decorator metadata first (cheap), then only resolves and validates the items the filter selects. So a build-time load can skip runtime-only vars entirely, including their `@required` checks and any value resolvers they use:
+
+```bash
+# runtime-only vars (e.g. platform-injected at runtime) don't exist yet at build
+# time - exclude them so their @required checks don't fail the build
+varlock load --filter='!@dynamic'
+```
 
 ## Guidance
 
-- Start with `@defaultDynamic=inferFromSensitive` for predictable defaults.
+- The default (`@defaultDynamic=inferFromSensitive`) keeps today's behavior: sensitive stays out of bundles, public gets inlined. You only need decorators when you want something different.
 - Mark intentional runtime public values with `@dynamic`.
 - Keep dynamic+public loading scoped to only the parts of your app that need it.
 - Prefer one app-level endpoint/payload shape per app unless you have a strong reason to split.

packages/varlock-website/src/content/docs/reference/cli-commands.mdx

@@ -62,7 +62,7 @@ Several commands share these flags. They behave identically wherever they appear
 
 - a key name or glob, e.g. `STRIPE_*` (matches `*` and `?`)
 - `!selector` to negate any of the below, e.g. `!STRIPE_DEBUG_KEY`
-- `@sensitive` / `@required` to select by decorator
+- `@sensitive` / `@required` / `@dynamic` to select by decorator (negate for the opposite, e.g. `!@dynamic` selects static items)
 - `#tagname` to select items tagged via [`@tag(tagname)`](/reference/item-decorators/#tag)
 
 **How selectors combine:** every non-negated selector is OR'd together into one inclusion set, regardless of kind: mixing a glob, a `@decorator`, and a `#tag` in the same filter just widens that set. Anything matching a negated (`!`) selector is then subtracted from that set, again regardless of kind. If a filter has no non-negated selectors at all, the inclusion set starts as "everything" before negations are subtracted.
@@ -72,6 +72,8 @@ varlock load --filter="KEY1,!NOT_THIS,STRIPE_*"  # KEY1 and STRIPE_* keys, excep
 varlock load --filter="@sensitive"               # only items marked @sensitive
 varlock load --filter="@required"                # only required items
 varlock load --filter="#billing"                 # only items tagged @tag(billing)
+varlock load --filter="@dynamic"                 # only runtime-resolved (dynamic) items
+varlock load --filter="!@dynamic,!@sensitive"     # inlineable public items only
 varlock load --filter="@sensitive,#billing"       # sensitive items OR billing-tagged items
 varlock load --filter="STRIPE_*,!@sensitive"      # STRIPE_* keys, minus any that are sensitive
 varlock load --filter="!#debug"                   # everything except items tagged @tag(debug)
@@ -87,7 +89,9 @@ Can also be set via the [`_VARLOCK_FILTER`](/reference/reserved-variables/#_varl
 
 A filter that matches no items (e.g. a typo'd key or tag) prints a warning to stderr. The command still succeeds, with empty output on `load` or no schema vars injected on `run`.
 
-**A key name/glob/tag-only filter also scopes resolution and validation**, not just output: only items it selects (plus their dependencies) are resolved, so an unrelated broken item outside the filter won't block `load`/`run`. This is useful for scoping validation differently across contexts, e.g. a build step that only needs `--filter="#frontend"` shouldn't fail because an unrelated backend-only var is misconfigured. `@sensitive`/`@required` selectors can't be scoped this way (which items match isn't knowable until the graph is already resolved), so a filter using either falls back to resolving and validating everything, same as no `--filter` at all.
+**A `--filter` also scopes resolution and validation**, not just output: only items it selects (plus their dependencies) are resolved, so an unrelated broken item outside the filter won't block `load`/`run`, and excluded items' value resolvers (exec commands, secrets managers, etc.) never run. This is useful for scoping validation differently across contexts, e.g. a build step that only needs `--filter="#frontend"` shouldn't fail because an unrelated backend-only var is misconfigured, and `--filter="!@dynamic"` at build time skips runtime-only vars (e.g. platform-injected values that don't exist yet at build time) including their `@required` checks.
+
+Decorator selectors match on *computed* state, which can be value-dependent (e.g. `@required=forEnv(prod)`), so for those varlock resolves each candidate item's decorator metadata first (cheap - no value resolvers run), then matches exactly and only resolves values for selected items. Values that decorator functions themselves reference (e.g. `@required=eq($OTHER, x)` needs `OTHER`) are true dependencies of evaluating the filter and do get resolved.
 
 ## Commands reference
 

packages/varlock-website/src/content/docs/reference/item-decorators.mdx

@@ -158,6 +158,8 @@ Sets whether the item is _dynamic_ - meaning integrations should avoid replacing
 
 By default, dynamic behavior follows sensitivity (sensitive items are dynamic, non-sensitive items are static), but this can be overridden globally with [`@defaultDynamic`](/reference/root-decorators/#defaultdynamic).
 
+Items can also be selected by this state via the `@dynamic` selector (or `!@dynamic` for static items) in the [`--filter` language](/reference/cli-commands/#filtering-items). See the [Static vs Dynamic Config guide](/guides/dynamic-config/) for the full model.
+
 ```env-spec
 # @dynamic
 PUBLIC_RUNTIME_FLAG=

packages/varlock-website/src/content/docs/reference/reserved-variables.mdx

@@ -44,6 +44,10 @@ Fallback for the [`--filter`](/reference/cli-commands/#filtering-items) flag on
 _VARLOCK_FILTER="#billing" varlock load --format json
 ```
 
+### `_VARLOCK_DYNAMIC_BUILD_ACCESS_MODE`
+
+Set to `warn` to downgrade the build/prerender-time guard on [public+dynamic](/guides/dynamic-config/) config access from an error to a one-time warning per key. Useful while migrating an existing app that still reads dynamic public values in prerendered pages.
+
 ### `_VARLOCK_THROW_ON_LOAD_ERROR`
 
 When set (`1` / `true`), [`varlock/auto-load`](/integrations/javascript/#reporting-load-failures) throws the error on a load failure instead of exiting, so an already-initialized error tracker (e.g. Sentry) can capture it via its `uncaughtException` handler. Setting a `globalThis._varlockOnLoadError` hook enables the same throw behavior. See [Reporting load failures](/integrations/javascript/#reporting-load-failures).
@@ -67,3 +71,7 @@ The serialized env graph (resolved config values plus metadata) injected by [`va
 ### `__VARLOCK_RUN`
 
 A marker set so a child process can detect that it is running under `varlock run`.
+
+### `__VARLOCK_EXECUTION_PHASE`
+
+Set to `build` by build-time integrations (e.g. the Vite plugin during `vite build`) so the runtime can detect app code executing during build/prerender and apply the [public+dynamic access guard](/guides/dynamic-config/#prerenderbuild-guardrails).

packages/varlock-website/src/content/docs/reference/root-decorators.mdx

@@ -537,7 +537,7 @@ Every `@generate*` decorator below is a root decorator that _can be called multi
 - `path`: Relative filepath to write the generated file to.
 - `auto`: Controls whether generation runs automatically on every load (defaults to `true`). Set to `false` to generate only when you run [`varlock codegen`](/reference/cli-commands/#codegen) explicitly, useful in a CI pipeline or a dedicated build step.
 - `executeWhenImported`: overrides the default of not executing when the containing file is imported (defaults to `false`).
-- `filter`: Restrict this generated file to a subset of items, using the same selector language as the CLI [`--filter` flag](/reference/cli-commands/#filtering-items): key names/globs, `!negations`, `@sensitive`/`@required`, and `#tagname` (set via [`@tag()`](/reference/item-decorators/#tag)). Quote the value if it has more than one comma-separated selector (the decorator parser splits args on unquoted commas), e.g. `filter="STRIPE_*,!STRIPE_DEBUG_KEY"`. Call the same decorator multiple times with different `path`/`filter` pairs to emit several subset files from one schema.
+- `filter`: Restrict this generated file to a subset of items, using the same selector language as the CLI [`--filter` flag](/reference/cli-commands/#filtering-items): key names/globs, `!negations`, `@sensitive`/`@required`/`@dynamic`, and `#tagname` (set via [`@tag()`](/reference/item-decorators/#tag)). Quote the value if it has more than one comma-separated selector (the decorator parser splits args on unquoted commas), e.g. `filter="STRIPE_*,!STRIPE_DEBUG_KEY"`. Call the same decorator multiple times with different `path`/`filter` pairs to emit several subset files from one schema.
 
 ```env-spec
 # only ship billing-tagged keys to the billing package's generated types

packages/varlock/src/cli/commands/load.command.ts

@@ -155,11 +155,12 @@ export const commandFn: TypedGunshiCommandFn<typeof commandSpec> = async (ctx) =
     // Generate types before resolving values — uses only non-env-specific schema info
     await envGraph.runCodeGeneratorsIfNeeded();
 
-    // A --filter using only keys/globs/tags scopes resolution (and validation) to what it
-    // selects plus dependencies — an unrelated broken item outside the filter won't block this
-    // load. @sensitive/@required selectors can't be scoped this way (see getResolveKeys), so
-    // those fall back to resolving everything, same as an unset --filter.
-    await envGraph.resolveEnvValues(itemFilter?.getResolveKeys(envGraph));
+    // A --filter scopes resolution (and validation) to what it selects plus dependencies — an
+    // unrelated broken item outside the filter won't block this load, and excluded items'
+    // value resolvers never run. Decorator selectors resolve item metadata first, then match
+    // exactly (see EnvGraph.resolveEnvValuesForFilter).
+    if (itemFilter) await itemFilter.resolveScoped(envGraph);
+    else await envGraph.resolveEnvValues();
 
     if (outputFormat === 'json-full') {
       checkForConfigErrors(envGraph, { showAll, noThrow: true });

packages/varlock/src/cli/commands/run.command.ts

@@ -186,12 +186,13 @@ export const commandFn: TypedGunshiCommandFn<typeof commandSpec> = async (ctx) =
   // Generate types before resolving values — uses only non-env-specific schema info
   await envGraph.runCodeGeneratorsIfNeeded();
 
-  // A --filter using only keys/globs/tags scopes resolution (and validation) to what it
-  // selects plus dependencies — an unrelated broken item outside the filter won't block this
-  // run. @sensitive/@required selectors can't be scoped this way (see getResolveKeys), so
-  // those fall back to resolving everything, same as an unset --filter.
+  // A --filter scopes resolution (and validation) to what it selects plus dependencies — an
+  // unrelated broken item outside the filter won't block this run, and excluded items'
+  // value resolvers never run. Decorator selectors resolve item metadata first, then match
+  // exactly (see EnvGraph.resolveEnvValuesForFilter).
   const itemFilter = getCliItemFilter(ctx.values.filter);
-  await envGraph.resolveEnvValues(itemFilter?.getResolveKeys(envGraph));
+  if (itemFilter) await itemFilter.resolveScoped(envGraph);
+  else await envGraph.resolveEnvValues();
   checkForConfigErrors(envGraph);
 
   // will fail above if there are any errors

packages/varlock/src/cli/helpers/item-filter.ts

@@ -6,15 +6,15 @@ import { CliExitError } from './exit-error';
 
 export type CliItemFilter = {
   /**
-   * Keys to pass to `resolveEnvValues()` (already includes transitive deps), so `load`/`run` can
-   * skip resolving (and validating) items outside the filter entirely — e.g. a build step scoped
-   * to `--filter="#frontend"` doesn't need an unrelated broken backend-only var to be valid.
-   * Returns `undefined` (= resolve everything) for filters using `@sensitive`/`@required`: their
-   * matches aren't knowable until the graph is resolved (see `usesDecoratorSelector`), so there's
-   * nothing to scope down to.
+   * Resolve only what the filter selects (see `EnvGraph.resolveEnvValuesForFilter()`), so
+   * `load`/`run` skip resolving (and validating) items outside the filter entirely — e.g. a
+   * build step scoped to `--filter="#frontend"` doesn't need an unrelated broken backend-only
+   * var to be valid, and `--filter="!@dynamic"` at build time skips runtime-only vars whose
+   * values (and `@required` checks) only make sense at runtime. Decorator selectors resolve
+   * item metadata first (cheap), then match exactly — excluded items' value resolvers never run.
    */
-  getResolveKeys(graph: EnvGraph): Array<string> | undefined;
-  /** the keys passing the filter — call after `resolveEnvValues()`, when decorator getters are accurate */
+  resolveScoped(graph: EnvGraph): Promise<void>;
+  /** the keys passing the filter — call after resolution, when decorator getters are accurate */
   getFilterKeys(items: Array<ConfigItem>): Set<string>;
 };
 
@@ -44,10 +44,8 @@ export function getCliItemFilter(flagValue: string | undefined): CliItemFilter |
   }
 
   return {
-    getResolveKeys(graph) {
-      if (parsed.usesDecoratorSelector) return undefined;
-      const matchedKeys = parsed.computeKeys(Object.values(graph.configSchema));
-      return [...graph.expandKeysWithTransitiveDeps(matchedKeys)];
+    async resolveScoped(graph) {
+      await graph.resolveEnvValuesForFilter(parsed);
     },
     getFilterKeys(items) {
       const keys = parsed.computeKeys(items);