@brust/core 2.0.0-alpha.33 → 2.0.0-alpha.35

package/src/build/manifest.ts

@@ -36,6 +36,9 @@ export interface ChildRecord {
   exprs?: Record<string, string>
   /** F142 R34.43: the list of a `per-row-literal` instance (a constant the compiler read). */
   rows?: unknown[]
+  /** F502: the branch condition (`{truthy}`/`{eq}`/`{not}`/`{all}`/`{any}` over props paths) the server checks per instance before
+   * it runs the child's job: a row whose branch does not render the child gets no job. */
+  when?: unknown
 }
 
 export interface ComponentRecord {
@@ -97,6 +100,8 @@ export interface ManifestJson {
   actions: ActionsRecord | null
   /** L16 R16.3: an actions-only build (no routes, no templates); everything but the prefix is a 404 problem+json. */
   actions_only?: true
+  /** F495 `[server] base_path`: set only for an app mounted under a path. The server answers under it alone and every URL brust owns lies below it. */
+  base_path?: string
   /** L16 R16.4b: a page-only build: no local actions app, `base_url` points at the deployment that has it. */
   actions_remote?: { prefix: string }
   /** `[cache]` (cache adapters); absent without one (the manifest is then byte-identical). */
@@ -315,6 +320,7 @@ export function childRecords(c: Compiled, clientOnly: string[] = []): ChildRecor
     if (inst.literals && Object.keys(inst.literals).length > 0) rec.literals = { ...inst.literals }
     if (inst.exprs && Object.keys(inst.exprs).length > 0) rec.exprs = { ...inst.exprs }
     if (literal) rec.rows = inst.rows_literal
+    if (inst.when !== undefined && inst.when !== null) rec.when = inst.when
     return rec
   })
   for (const id of clientOnly) out.push({ id, instances: 'static', props: {} })

package/src/build/posix.ts

@@ -0,0 +1,35 @@
+// F485 (G5): the one choke point for path spelling. A path that leaves the filesystem layer (handed to the native
+// compiler, used as a Map/manifest key, matched against config prefixes, written into dist/*.js, dev.json or a wrangler
+// config) is `/`-separated; a path used only for fs calls stays native. Every helper takes the separator as a parameter
+// (default: the platform's), so a unit test can feed `C:\app\pages\X.tsx` on any OS and POSIX output stays byte-identical.
+import { isAbsolute, relative, sep } from 'node:path'
+
+/** `p` with the platform separator spelled `/`. A no-op on POSIX (a `\` there is a legal file name character). */
+export function posixOf(p: string, s: string = sep): string {
+  return s === '/' ? p : p.split(s).join('/')
+}
+
+/** The reverse of {@link posixOf}: a `/`-separated path (the compiler's spelling) as the platform spells it. */
+export function nativeOf(p: string, s: string = sep): string {
+  return s === '/' ? p : p.split('/').join(s)
+}
+
+/** `relative(base, file)` spelled with `/`. */
+export function relPosix(base: string, file: string, s: string = sep): string {
+  return posixOf(relative(base, file), s)
+}
+
+/** A `relative()` result that does not lie inside its base: `..`, `../x`, or an absolute path (another drive on Windows). */
+export function escapes(rel: string, s: string = sep): boolean {
+  const p = posixOf(rel, s)
+  return p === '..' || p.startsWith('../') || isAbsolute(rel) || (s !== '/' && /^[A-Za-z]:/.test(p)) // `c:x` is a legal POSIX dir name
+}
+
+/** `[build] server_only` (spec §8.2): is the app-root-relative `rel` inside a listed prefix? Prefixes are `/`-spelled
+ * (config.ts normalises them); `rel` is spelled with `s` and normalised here, so a Windows `lib\server\db.ts` matches
+ * `lib/server`. A path outside the app root never matches. */
+export function inServerOnlyPrefix(rel: string, prefixes: string[], s: string = sep): boolean {
+  if (escapes(rel, s)) return false
+  const p = posixOf(rel, s)
+  return prefixes.some((pre) => p.startsWith(pre))
+}

package/src/build/route-conflicts.ts

@@ -0,0 +1,39 @@
+// F496: the server's router refuses some pattern sets (`/{*rest}` next to `/{slug}`); without this the build passes and
+// the first `brust start` fails. The check is the router's own insertion (`routing/routes.rs` `find_pattern_conflict`,
+// through the addon the build already loads): there is no second matcher here.
+import type { FlatRoute } from '../routes'
+import { BuildError } from './errors'
+
+export interface PatternConflict {
+  /** Index into the patterns given of the pattern the router refused. */
+  index: number
+  /** Index of the earlier pattern it conflicts with, when there is one. */
+  withIndex?: number | null
+  /** The router's refusal, as `brust start` would print it. */
+  message: string
+}
+
+export type CheckPatterns = (patterns: string[]) => PatternConflict | null
+
+/** The addon's `checkRoutePatterns` (crates/brust-napi/src/compile.rs `check_route_patterns`). */
+export async function nativeCheckPatterns(): Promise<CheckPatterns> {
+  const { native } = await import('../native')
+  const b = native() as unknown as { checkRoutePatterns?: CheckPatterns }
+  if (typeof b.checkRoutePatterns !== 'function')
+    throw new BuildError('route-conflict', 'the native addon is older than this build (no checkRoutePatterns): rebuild it')
+  return b.checkRoutePatterns.bind(b)
+}
+
+/** Fails the build when the server's router would refuse the leaves' patterns. Catch-all (`*`) leaves never enter the
+ * router, so they are left out, as the server leaves them out. The error names the route ids. */
+export function assertRoutesInstallable(leaves: FlatRoute[], check: CheckPatterns): void {
+  const routed = leaves.filter((l) => !l.catchAll)
+  const found = check(routed.map((l) => l.pattern))
+  if (!found) return
+  const at = routed[found.index]
+  const partner = found.withIndex != null ? routed[found.withIndex] : undefined
+  const who = partner
+    ? `routes ${partner.id} (${partner.pattern}) and ${at?.id} (${at?.pattern}) cannot be installed together`
+    : `route ${at?.id} (${at?.pattern}) cannot be installed`
+  throw new BuildError('route-conflict', `${who}: ${found.message}`)
+}

package/src/build/ssg.ts

@@ -77,7 +77,8 @@ function checkValue(leaf: FlatRoute, i: number, name: string, rest: boolean, v:
 }
 
 /** Plans every page. `params` holds each dynamic route's resolved `ssg.params()` by route id. */
-export function planStatic(leaves: FlatRoute[], params: Map<string, unknown>): StaticPlan {
+/** F495: under `base` (`[server] base_path`) the not-found probe is a path under it, so the app's `*` route answers it rather than the server's plain 404. */
+export function planStatic(leaves: FlatRoute[], params: Map<string, unknown>, base = ''): StaticPlan {
   const pages: PlannedPage[] = []
   const skipped: StaticPlan['skipped'] = []
   let catchAll: FlatRoute | undefined
@@ -133,7 +134,7 @@ export function planStatic(leaves: FlatRoute[], params: Map<string, unknown>): S
     seen.set(key, p)
   }
   if (seen.has('404.html')) throw new BuildError('ssg-params', `${seen.get('404.html')!.path} would overwrite 404.html`)
-  if (catchAll) pages.push({ path: NOT_FOUND_PATH, file: '404.html', routeId: catchAll.id, pattern: catchAll.pattern, expect: 404 })
+  if (catchAll) pages.push({ path: `${base}${NOT_FOUND_PATH}`, file: '404.html', routeId: catchAll.id, pattern: catchAll.pattern, expect: 404 })
   return { pages, skipped, defaultNotFound: catchAll === undefined }
 }
 

package/src/build/static.ts

@@ -28,6 +28,7 @@ export async function prepareStatic(
   reads: ExprReads,
   log: (s: string) => void,
   cache?: Parameters<typeof assertNoCacheBindings>[0],
+  base = '',
 ): Promise<StaticPlan> {
   // L12: `[actions]` makes the output hybrid (static pages + a Pages Worker for the action prefix).
   if (actions) assertNoCacheBindings(cache)
@@ -65,7 +66,7 @@ export async function prepareStatic(
       throw new BuildError('ssg-params', `route ${leaf.id} (${leaf.pattern}) ssg.params() threw: ${(e as Error).message ?? String(e)}`)
     }
   }
-  return planStatic(leaves, params)
+  return planStatic(leaves, params, base)
 }
 
 export interface StaticReport {
@@ -167,7 +168,7 @@ export async function writeStatic(
   const dir = join(dist, 'static')
   rmSync(dir, { recursive: true, force: true })
   const assetsStage = join(dist, '.ssg-assets')
-  const assets = layoutAssets(dist, assetsStage, o.version)
+  const assets = layoutAssets(dist, assetsStage, o.version, (JSON.parse(readFileSync(join(dist, 'manifest.json'), 'utf8')) as { base_path?: string }).base_path ?? '')
   renameSync(join(assetsStage, 'assets'), dir)
   rmSync(assetsStage, { recursive: true, force: true })
   const warnings = [...assets.warnings]

package/src/build/swap.ts

@@ -0,0 +1,47 @@
+// F485 P8: replacing `dist` by the finished temp dir. On Windows a rename of a directory fails (EPERM / EBUSY /
+// EACCES) while anything holds a handle inside it (a running `brust start`, an indexer, an antivirus scan), so the
+// rename is retried briefly and then fails with a message that says what to stop. On POSIX the first try succeeds.
+import { existsSync, renameSync, rmSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { BuildError } from './errors'
+
+const BUSY = new Set(['EPERM', 'EBUSY', 'EACCES'])
+export const RENAME_TRIES = 5
+export const RENAME_WAIT_MS = 100
+
+export interface SwapOps {
+  rename: (from: string, to: string) => void
+  sleep: (ms: number) => void
+}
+
+const real: SwapOps = {
+  rename: renameSync,
+  sleep: (ms) => void Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms),
+}
+
+/** `renameSync` that retries a held-handle failure `RENAME_TRIES` times, `RENAME_WAIT_MS` apart. */
+export function renameRetry(from: string, to: string, dist: string, ops: SwapOps = real): void {
+  for (let i = 1; ; i++) {
+    try {
+      ops.rename(from, to)
+      return
+    } catch (e) {
+      const code = (e as NodeJS.ErrnoException).code
+      if (code === undefined || !BUSY.has(code)) throw e
+      if (i >= RENAME_TRIES)
+        throw new BuildError('dist-busy', `cannot replace ${dist} (${code}): stop a running \`brust start\` or anything holding files in it, then build again`)
+      ops.sleep(RENAME_WAIT_MS)
+    }
+  }
+}
+
+/** Puts `tmp` in place of `dist`; the previous dist goes through `.<name>.brust-old` and is removed after. */
+export function swapDist(tmp: string, dist: string, ops: SwapOps = real): void {
+  if (existsSync(dist)) {
+    const old = join(dirname(dist), `.${basename(dist)}.brust-old`)
+    rmSync(old, { recursive: true, force: true })
+    renameRetry(dist, old, dist, ops)
+    renameRetry(tmp, dist, dist, ops)
+    rmSync(old, { recursive: true, force: true })
+  } else renameRetry(tmp, dist, dist, ops)
+}

package/src/build/tailwind.ts

@@ -68,8 +68,15 @@ const addCommand = (v: string) => `bun add -d --exact ${TAILWIND_PACKAGES.map((p
 /** The Tailwind plugin of the CSS build, resolved from the app. Missing packages → `tailwind-missing` with the
  * exact install command; versions that differ → one warning through `log` with the command that aligns them.
  * `uses(file)` says whether a stylesheet needs the compiler (it, or a relative `@import` of it, uses Tailwind);
- * other stylesheets stay Bun's. */
-export async function loadTailwind(appRoot: string, usedBy: string, uses: (file: string) => boolean, log?: (s: string) => void): Promise<BunPlugin> {
+ * other stylesheets stay Bun's. `ownOutput`: app-root-relative, `/`-separated directories of brust's own output that no
+ * scan may read (F501). */
+export async function loadTailwind(
+  appRoot: string,
+  usedBy: string,
+  uses: (file: string) => boolean,
+  log?: (s: string) => void,
+  ownOutput: string[] = [],
+): Promise<BunPlugin> {
   const v = tailwindVersions(appRoot)
   const missing = TAILWIND_PACKAGES.filter((p) => versionFrom(p, appRoot) === undefined)
   if (missing.length > 0)
@@ -105,7 +112,10 @@ export async function loadTailwind(appRoot: string, usedBy: string, uses: (file:
         const compiler = await node.compile(css, { base: dirname(a.path), from: a.path, shouldRewriteUrls: true, onDependency: () => {} })
         const root: SourceEntry[] =
           compiler.root === 'none' ? [] : compiler.root === null ? [{ base: appRoot, pattern: '**/*', negated: false }] : [{ ...compiler.root, negated: false }]
-        const scanner = new oxide.Scanner({ sources: [...root, ...compiler.sources] })
+        // F501: brust's own output (the dist dir, `.brust`) is never a source, whatever the ignore files say and whatever
+        // the stylesheet's `source(...)` and `@source` lines add: last, so a stale build can never feed the next one.
+        const own: SourceEntry[] = ownOutput.map((dir) => ({ base: appRoot, pattern: `${dir}/**`, negated: true }))
+        const scanner = new oxide.Scanner({ sources: [...root, ...compiler.sources, ...own] })
         let out = compiler.build(scanner.scan())
         // `@reference "./app.css"` pulls in Tailwind's license banner too; only the file that imports Tailwind ships it
         // (one banner per page, as before)

package/src/build/tsconfig-paths.ts

@@ -3,7 +3,7 @@
 // this module reads out of the app's own `tsconfig.json` / `jsconfig.json`. v1 reads that one file: no `extends`, no
 // `references` (a named fallback below); exact and single-`*` patterns only. The bundler resolves the same specifiers
 // natively; `checkAliasAgreement` fails the build if the two ever disagree.
-import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
 import { dirname, isAbsolute, join, normalize, relative, sep } from 'node:path'
 import { BuildError } from './errors'
 
@@ -26,10 +26,21 @@ export function readPathAliases(appRoot: string): { aliases: PathAlias[]; notes:
   }
   const notes: string[] = []
   const paths = json?.compilerOptions?.paths
-  if (json?.extends !== undefined || json?.references !== undefined)
+  const name = relative(appRoot, file)
+  const hasPaths = !!paths && typeof paths === 'object'
+  // TS semantics: a local `compilerOptions.paths` replaces any inherited `paths`, so beside a local `paths` an `extends`
+  // can only matter through the `baseUrl` it supplies (F497). Without local `paths` the aliases live elsewhere.
+  if (hasPaths ? json?.references !== undefined : json?.extends !== undefined || json?.references !== undefined)
     notes.push(
-      `${relative(appRoot, file)} uses \`${json.extends !== undefined ? 'extends' : 'references'}\`, which brust does not follow: \`paths\` aliases written in another tsconfig stay package imports (put \`paths\` in ${relative(appRoot, file)})`,
+      `${name} uses \`${json.extends !== undefined && !hasPaths ? 'extends' : 'references'}\`, which brust does not follow: \`paths\` aliases written in another tsconfig stay package imports (put \`paths\` in ${name})`,
     )
+  if (hasPaths && json?.extends !== undefined && typeof json.compilerOptions?.baseUrl !== 'string') {
+    const from = inheritedBaseUrlFile(file, json.extends)
+    if (from)
+      notes.push(
+        `\`baseUrl\` comes from ${relative(appRoot, from).split(sep).join('/')}, which brust does not follow: aliases resolve from ${name}'s directory (set \`baseUrl\` in ${name})`,
+      )
+  }
   if (!paths || typeof paths !== 'object') return { aliases: [], notes }
   const base = typeof json.compilerOptions?.baseUrl === 'string' ? json.compilerOptions.baseUrl : '.'
   const aliases: PathAlias[] = []
@@ -52,6 +63,23 @@ export function readPathAliases(appRoot: string): { aliases: PathAlias[]; notes:
   return { aliases, notes }
 }
 
+/** The extended tsconfig that sets `baseUrl`, when `extends` names a relative file (one level, JSONC; a package specifier,
+ * an unreadable file or a file without `baseUrl` is none). */
+function inheritedBaseUrlFile(file: string, extendsValue: unknown): string | null {
+  const refs = Array.isArray(extendsValue) ? extendsValue : [extendsValue]
+  for (const ref of refs) {
+    if (typeof ref !== 'string' || !(ref.startsWith('./') || ref.startsWith('../'))) continue
+    const base = join(dirname(file), ref)
+    const target = [base, `${base}.json`].find((f) => existsSync(f) && statSync(f).isFile())
+    if (!target) continue
+    try {
+      const ext = Bun.JSONC.parse(readFileSync(target, 'utf8')) as { compilerOptions?: { baseUrl?: unknown } } | null
+      if (typeof ext?.compilerOptions?.baseUrl === 'string') return target
+    } catch {}
+  }
+  return null
+}
+
 /** The compiler's answer for every alias import must be the file the bundler resolves the same specifier to. */
 export function checkAliasAgreement(appRoot: string, imports: { from: string; spec: string; target: string }[]): void {
   for (const { from, spec, target } of imports) {

package/src/cache-adapter/conformance.ts

@@ -129,6 +129,48 @@ export function runConformance(make: () => CacheAdapter | Promise<CacheAdapter>,
       expect((await s.get(k2)).page).not.toBeNull()
     })
 
+    if (caps.invalidate !== false) test('F493: prefix + path drops that prefix\'s page only', async () => {
+      const { s } = await store()
+      const [a, b, none] = [key(), key(), key()]
+      await s.set(a, page('a'), meta({ path: '/x', prefix: 'a.test' }))
+      await s.set(b, page('b'), meta({ path: '/x', prefix: 'b.test' }))
+      await s.set(none, page('n'), meta({ path: '/x', prefix: '' }))
+      await s.invalidate({ prefix: 'a.test', path: '/x' })
+      expect((await s.get(a)).page).toBeNull()
+      expect((await s.get(b)).page).not.toBeNull()
+      expect((await s.get(none)).page).not.toBeNull()
+      // `''` is exact: it matches the entry with no prefix only.
+      await s.invalidate({ prefix: '', path: '/x' })
+      expect((await s.get(none)).page).toBeNull()
+      expect((await s.get(b)).page).not.toBeNull()
+    })
+
+    if (caps.invalidate !== false) test('F493: prefix + tags drops that prefix\'s tagged pages; the other prefix stays tagged', async () => {
+      const { s } = await store()
+      const [a, b, a2] = [key(), key(), key()]
+      await s.set(a, page('a'), meta({ tags: ['page'], path: '/p', prefix: 'a.test' }))
+      await s.set(b, page('b'), meta({ tags: ['page'], path: '/p', prefix: 'b.test' }))
+      await s.set(a2, page('a2'), meta({ tags: ['other'], path: '/q', prefix: 'a.test' }))
+      await s.invalidate({ prefix: 'a.test', tags: ['page'] })
+      expect((await s.get(a)).page).toBeNull()
+      expect((await s.get(b)).page).not.toBeNull()
+      expect((await s.get(a2)).page).not.toBeNull()
+      await s.invalidate({ tags: ['page'] })
+      expect((await s.get(b)).page).toBeNull()
+    })
+
+    if (caps.invalidate !== false) test('F493: prefix alone drops every page of that prefix', async () => {
+      const { s } = await store()
+      const [a1, a2, b] = [key(), key(), key()]
+      await s.set(a1, page('1'), meta({ path: '/x', prefix: 'a.test' }))
+      await s.set(a2, page('2'), meta({ tags: ['t'], path: '/y', prefix: 'a.test' }))
+      await s.set(b, page('b'), meta({ path: '/x', prefix: 'b.test' }))
+      await s.invalidate({ prefix: 'a.test' })
+      expect((await s.get(a1)).page).toBeNull()
+      expect((await s.get(a2)).page).toBeNull()
+      expect((await s.get(b)).page).not.toBeNull()
+    })
+
     test('key invalidation is a store no-op', async () => {
       const { s } = await store()
       const k = key()
@@ -168,6 +210,41 @@ export function runConformance(make: () => CacheAdapter | Promise<CacheAdapter>,
       })
     }
 
+    if (caps.guard) {
+      test('F493: a set whose stamp predates an invalidation of its prefix is refused; another prefix lands', async () => {
+        const { a, s } = await store()
+        const [k, other] = [key(), key()]
+        // A path of its own: a store's namespace may outlive one case (an earlier case's path marker must not refuse it).
+        const path = `/${k}`
+        const g = await s.get(k)
+        await s.invalidate({ prefix: 'a.test' })
+        await a.broadcast?.publish({ prefix: 'a.test' }, 'conf')
+        expect(await s.set(k, page('stale'), meta({ path, prefix: 'a.test', stamp: g.stamp }))).toBe(false)
+        expect((await s.get(k)).page).toBeNull()
+        expect(await s.set(other, page('b'), meta({ path, prefix: 'b.test', stamp: g.stamp }))).toBe(true)
+        const g2 = await s.get(k)
+        expect(await s.set(k, page('fresh'), meta({ path, prefix: 'a.test', stamp: g2.stamp }))).toBe(true)
+      })
+    }
+
+    test('F493: the broadcast carries prefix in its args', async () => {
+      const a = await fresh()
+      if (!a.broadcast?.subscribe && !a.broadcast?.since) return
+      const args = { prefix: 'a.test', path: '/b' }
+      if (a.broadcast.subscribe) {
+        const got: InvalidationEvent[] = []
+        const stop = await a.broadcast.subscribe(e => got.push(e), () => {})
+        const seq = await a.broadcast.publish(args, 'o1')
+        await until('delivery', () => got.length === 1)
+        expect(got[0]).toEqual({ seq, origin: 'o1', args })
+        await stop()
+      } else {
+        const base = (await a.broadcast.since!(0)).seq
+        await a.broadcast.publish(args, 'o1')
+        expect((await a.broadcast.since!(base)).events.map(e => e.args)).toEqual([args])
+      }
+    })
+
     test('publish seqs strictly increase; get().stamp is the last seq (one space)', async () => {
       const a = await fresh()
       if (!a.broadcast) return

package/src/cache-adapter/memory.ts

@@ -32,6 +32,8 @@ interface Entry {
   tags: string[]
   method: string
   path: string
+  /** The route-cache key prefix (F493); `''` = none. */
+  prefix: string
   entryStamp: number | null
   storedAt: number
   expiresAt: number
@@ -57,6 +59,42 @@ export type MemoryAdapter = CacheAdapter & { store: CacheStore; __test: MemoryAd
 
 const pathName = (method: string | undefined, path: string) => `${method ?? 'GET'} ${path}`
 
+// Marker names (F493: scoped by prefix, so one prefix's invalidation refuses only that prefix's stale
+// writes). A prefix is JSON-quoted: self-delimiting, so names of different prefixes never meet.
+const tagName = (t: string) => `t:${t}`
+const pName = (m: string | undefined, p: string) => `p:${pathName(m, p)}`
+const px = (prefix: string) => `px:${JSON.stringify(prefix)}`
+const ptName = (prefix: string, t: string) => `pt:${JSON.stringify(prefix)}${t}`
+const ppName = (prefix: string, m: string | undefined, p: string) => `pp:${JSON.stringify(prefix)}${pathName(m, p)}`
+
+/** The marker names an invalidation raises. `{ prefix }` alone ignores `method` (conservative). */
+function invalidationNames(a: InvalidateArgs): string[] {
+  const tags = a.tags ?? []
+  const pre = a.prefix
+  if (pre === undefined) return [...tags.map(tagName), ...(a.path !== undefined ? [pName(a.method, a.path)] : [])]
+  if (!tags.length && a.path === undefined) return [px(pre)]
+  return [...tags.map(t => ptName(pre, t)), ...(a.path !== undefined ? [ppName(pre, a.method, a.path)] : [])]
+}
+
+/** Every marker name that covers an entry. */
+function entryNames(e: { tags: string[]; method: string; path: string; prefix: string }): string[] {
+  return [
+    ...e.tags.map(tagName),
+    pName(e.method, e.path),
+    px(e.prefix),
+    ...e.tags.map(t => ptName(e.prefix, t)),
+    ppName(e.prefix, e.method, e.path),
+  ]
+}
+
+/** Does `a` delete `e`? (`key` alone deletes nothing: the store holds pages only.) */
+function covers(a: InvalidateArgs, e: Entry): boolean {
+  if (a.prefix !== undefined && e.prefix !== a.prefix) return false
+  const tags = a.tags ?? []
+  if (!tags.length && a.path === undefined) return a.prefix !== undefined && (a.method === undefined || a.method === e.method)
+  return e.tags.some(t => tags.includes(t)) || (a.path !== undefined && pathName(e.method, e.path) === pathName(a.method, a.path))
+}
+
 export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
   const mode = o.broadcast ?? 'push'
   const ringCap = o.ring ?? 1024
@@ -64,8 +102,7 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
   const maxBodyBytes = o.maxBodyBytes ?? 8_388_608
   const now = o.now ?? Date.now
   const entries = new Map<string, Entry>()
-  const tagSeq = new Map<string, number>()
-  const pathSeq = new Map<string, number>()
+  const nameSeq = new Map<string, number>()
   let seq = 0
   // Drawn on first use: a Workers module may not make random values at global scope.
   let genValue: string | null = null
@@ -86,10 +123,8 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
     fail = false
     return true
   }
-  const raise = (m: Map<string, number>, k: string, s: number) => m.set(k, Math.max(m.get(k) ?? 0, s))
   const mark = (args: InvalidateArgs, s: number) => {
-    for (const t of args.tags ?? []) raise(tagSeq, t, s)
-    if (args.path !== undefined) raise(pathSeq, pathName(args.method, args.path), s)
+    for (const n of invalidationNames(args)) nameSeq.set(n, Math.max(nameSeq.get(n) ?? 0, s))
   }
 
   const store: CacheStore = {
@@ -113,10 +148,10 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
     async set(key: string, page: StoredPage, meta: SetMeta): Promise<boolean> {
       if (failing()) throw new Error('memory adapter: injected failure')
       if (page.body.length > maxBodyBytes) return false
+      const prefix = meta.prefix ?? ''
       if (meta.stamp !== null) {
         const s = meta.stamp
-        const stale = (m: Map<string, number>, k: string) => (m.get(k) ?? 0) > s
-        if (meta.tags.some(t => stale(tagSeq, t)) || stale(pathSeq, pathName(meta.method, meta.path))) return false
+        if (entryNames({ ...meta, prefix }).some(n => (nameSeq.get(n) ?? 0) > s)) return false
       }
       const at = now()
       entries.set(key, {
@@ -124,6 +159,7 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
         tags: [...meta.tags],
         method: meta.method,
         path: meta.path,
+        prefix,
         entryStamp: meta.stamp,
         storedAt: at,
         expiresAt: at + meta.ttlMs,
@@ -140,11 +176,7 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
       // L7b: the marker first, at the seq the matching publish will take (seq + 1), so a set whose
       // stamp was read before this call is refused from now on; then the delete.
       mark(args, seq + 1)
-      const tags = new Set(args.tags ?? [])
-      const p = args.path === undefined ? null : pathName(args.method, args.path)
-      for (const [k, e] of entries) {
-        if (e.tags.some(t => tags.has(t)) || (p !== null && pathName(e.method, e.path) === p)) entries.delete(k)
-      }
+      for (const [k, e] of entries) if (covers(args, e)) entries.delete(k)
     },
   }
 

package/src/cache-adapter/types.ts

@@ -21,6 +21,11 @@ export interface SetMeta {
   tags: string[]
   method: string
   path: string
+  /**
+   * The entry's evaluated route-cache key prefix (`''` = none), for `invalidate({ prefix })` (F493).
+   * Absent only from callers older than F493: treat it as `''`.
+   */
+  prefix?: string
   /** The `stamp` the lookup returned (read before the render); `null` = unguarded write. */
   stamp: number | null
 }
@@ -45,7 +50,8 @@ export interface CacheStore {
   /**
    * Shared-side delete by tags/path (`key` is a no-op: the store holds pages only). Records the
    * invalidation marker BEFORE deleting, so a concurrent stale `set` is refused even before the
-   * publish (ruling L7b).
+   * publish (ruling L7b). With `prefix` (F493) only entries whose `SetMeta.prefix` equals it are
+   * deleted (`{ prefix }` alone: every page of that prefix); entries of other prefixes stay.
    */
   invalidate(args: InvalidateArgs): Promise<void>
   readonly maxBodyBytes: number

package/src/cache.ts

@@ -9,8 +9,19 @@ import { type InvalidateArgs, type InvalidateResult, cacheInvalidate } from './n
 export type { ComponentCacheOptions } from './cache-core'
 
 const NO_SERVER = 'cache.invalidate needs a running server (call it inside `brust start`)'
+/** Same text as brust-core `PREFIX_WITH_KEY` (the Rust hosts refuse it too). */
+export const PREFIX_WITH_KEY = 'cache.invalidate: `prefix` narrows page entries; `key` names a job entry — call them separately'
+
+/** F493: `prefix` is a string and never comes with `key`. Throws a TypeError otherwise. */
+export function checkInvalidateArgs(args: InvalidateArgs): void {
+  const prefix = (args as { prefix?: unknown } | null | undefined)?.prefix
+  if (prefix === undefined) return
+  if (typeof prefix !== 'string') throw new TypeError(`cache.invalidate: \`prefix\` must be a string (got ${prefix === null ? 'null' : typeof prefix})`)
+  if (args.key !== undefined) throw new TypeError(PREFIX_WITH_KEY)
+}
 
 function invalidate(args: InvalidateArgs): InvalidateResult {
+  checkInvalidateArgs(args)
   let r: InvalidateResult
   try {
     r = cacheInvalidate(args)

package/src/cf.ts

@@ -2,6 +2,9 @@
 // Same names as `index.ts` minus what needs a host process: no `run`, no `loadConfig`. `cache.invalidate` goes through
 // the CF bundle's napi stub to the runtime the wasm glue installed at start (`server-handlers` `install`).
 export { buildTime } from './build-time'
+
+/** F495 `[server] base_path` (see index.ts). The Cloudflare build bakes the manifest's value into the Worker bundle (`process.env.BRUST_BASE_PATH` is a `define`), `''` at the root. */
+export const basePath: string = typeof process === 'undefined' ? '' : (process.env.BRUST_BASE_PATH ?? '')
 export { navigate } from './navigate'
 export type { NavErrorDetail, NavLoadDetail, NavigateOptions, NavSuccessDetail, NavTrigger } from './navigate'
 export { cache } from './cache'

package/src/config.ts

@@ -2,7 +2,7 @@
 //   env (BRUST_ADDR / BRUST_PORT / BRUST_WORKERS / BRUST_RENDER_SLOTS / BRUST_DRAIN_TIMEOUT_MS /
 //        BRUST_BOOT_TIMEOUT_MS / BRUST_CALL_TIMEOUT_MS / BRUST_SLOT_BYTES / BRUST_MAX_LOADER_RESPONSE_BYTES)
 //   > CLI flags (`brust start --port/--workers`) and `run({ config })`
-//   > brust.toml ([server] address / port / max_loader_response_bytes, [workers] count / slot_bytes, [cors], [actions] base_url / credentials)
+//   > brust.toml ([server] address / port / base_path / max_loader_response_bytes, [workers] count / slot_bytes, [cors], [actions] base_url / credentials)
 //   > defaults (localhost, 1337, availableParallelism(), 1, 10000, 30000, 30000, 262144, 8388608).
 // L16 R16.1: `actionsBaseUrl` follows env (BRUST_ACTIONS_BASE_URL) > run({ config }) > toml `[actions] base_url`.
 // `cors` has no env layer; `run({ config: { cors } })` replaces a toml `[cors]` as a whole (never merged), and
@@ -43,6 +43,10 @@ export interface BrustConfig {
   maxLoaderResponseBytes: number
   /** `run({ config: { cors } })` over brust.toml `[cors]` (a whole-object replace); absent = CORS off. No env layer. */
   cors?: CorsConfig
+  /** F495 `[server] base_path` / `run({ config: { basePath } })`: the path the app is mounted under on a shared origin (`/portal`; `''` = the
+   * root), absent when nothing set it. A build setting too (`brust build` bakes it into the manifest): `brust start` refuses a manifest
+   * built for another one, and with none set serves the one the manifest names. */
+  basePath?: string
   /** L16 R16.1: the origin the browser `client()` calls (page script `__BRUST_ACTION_BASE__`); absent = same origin. */
   actionsBaseUrl?: string
   /** L16 R16.2: the client's default `RequestInit.credentials` (`__BRUST_ACTION_CREDENTIALS__`); absent = `same-origin`. */
@@ -52,6 +56,19 @@ export interface BrustConfig {
 /** What `run({ config })` / `loadConfig`'s `cli` accepts: any setting, and `cors: null` to turn a toml `[cors]` off. */
 export type ConfigOverrides = Omit<Partial<BrustConfig>, 'cors'> & { cors?: (Omit<CorsConfig, 'credentials'> & { credentials?: boolean }) | null }
 
+/** F495: `[server] base_path`, validated: `/seg[/seg…]`, no trailing `/`, each segment `[A-Za-z0-9._~-]+` (not `.`/`..`), the
+ * same alphabet as the actions prefix, so it needs no percent-encoding anywhere it is printed. `""` and `"/"` mean the
+ * root (`""`). Returns the value, or the reason it is refused. */
+export function normalizeBasePath(raw: unknown): { ok: true; value: string } | { ok: false; why: string } {
+  if (typeof raw !== 'string') return { ok: false, why: `must be a string (got ${JSON.stringify(raw)})` }
+  if (raw === '' || raw === '/') return { ok: true, value: '' }
+  if (!raw.startsWith('/')) return { ok: false, why: `must start with '/' (got ${JSON.stringify(raw)})` }
+  if (raw.endsWith('/')) return { ok: false, why: `must not end with '/' (got ${JSON.stringify(raw)})` }
+  if (raw.slice(1).split('/').some((seg) => !/^[A-Za-z0-9._~-]+$/.test(seg) || seg === '.' || seg === '..'))
+    return { ok: false, why: `segments must be [A-Za-z0-9._~-]+ and not '.'/'..' (got ${JSON.stringify(raw)})` }
+  return { ok: true, value: raw }
+}
+
 export class BrustConfigError extends Error {
   override name = 'BrustConfigError'
   constructor(
@@ -112,6 +129,7 @@ export async function loadConfig(cwd: string = process.cwd(), cli: ConfigOverrid
     maxLoaderResponseBytes: env.maxLoaderResponseBytes ?? cli.maxLoaderResponseBytes ?? fromToml.maxLoaderResponseBytes ?? DEFAULTS.maxLoaderResponseBytes,
     ioThreads: env.ioThreads ?? cli.ioThreads,
     ...(cors ? { cors } : {}),
+    ...pick('basePath', cli.basePath ?? fromToml.basePath),
     ...pick('actionsBaseUrl', env.actionsBaseUrl ?? cli.actionsBaseUrl ?? fromToml.actionsBaseUrl),
     ...pick('actionsCredentials', cli.actionsCredentials ?? fromToml.actionsCredentials),
   }
@@ -150,6 +168,11 @@ function checkCli(cli: ConfigOverrides): void {
   check('ioThreads', cli.ioThreads, 1, MAX_IO_THREADS)
   check('slotBytes', cli.slotBytes, MIN_SLOT_BYTES, MAX_SLOT_BYTES)
   check('maxLoaderResponseBytes', cli.maxLoaderResponseBytes, MIN_LOADER_RESPONSE_BYTES, MAX_LOADER_RESPONSE_BYTES)
+  if (cli.basePath !== undefined) {
+    const r = normalizeBasePath(cli.basePath)
+    if (!r.ok) throw new BrustConfigError(`config.basePath ${r.why}`, null)
+    cli.basePath = r.value
+  }
   if (cli.actionsBaseUrl !== undefined) {
     const why = baseUrlError(cli.actionsBaseUrl)
     if (why) throw new BrustConfigError(`config.actionsBaseUrl ${why}`, null)
@@ -176,6 +199,11 @@ function fromTomlTable(parsed: unknown, file: string): Partial<BrustConfig> {
   if ('server' in root) {
     const server = table(root.server, '[server]', file)
     const { port, address } = server
+    if (server.base_path !== undefined) {
+      const r = normalizeBasePath(server.base_path)
+      if (!r.ok) throw new BrustConfigError(`${file}: server.base_path ${r.why}`, file)
+      out.basePath = r.value
+    }
     const cap = tomlInt(server.max_loader_response_bytes, 'server.max_loader_response_bytes', MIN_LOADER_RESPONSE_BYTES, MAX_LOADER_RESPONSE_BYTES, file)
     if (cap !== undefined) out.maxLoaderResponseBytes = cap
     if (port !== undefined) {