@namzu/sdk 5.0.0 → 5.2.0

package/src/directory/scan.ts

@@ -0,0 +1,163 @@
+import type { Dirent } from 'node:fs'
+import { lstat, readdir, realpath } from 'node:fs/promises'
+import { basename, extname, join, relative, sep } from 'node:path'
+
+import { resolveWithinReal } from '../tools/paths.js'
+
+import type { DirectoryDiagnostic, DirectorySlot } from './types.js'
+
+/** Extensions Node can import directly, given its own type stripping. */
+const CODE_EXTENSIONS = new Set(['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'])
+
+export interface ScannedFile {
+	readonly path: string
+	readonly relativePath: string
+	readonly id: string
+}
+
+export interface ScanResult {
+	readonly files: readonly ScannedFile[]
+	readonly diagnostics: readonly DirectoryDiagnostic[]
+}
+
+/**
+ * List the code files directly inside one slot directory.
+ *
+ * **Symlinks are refused, not followed.** A directory handed to this loader is
+ * caller-supplied, and a link inside it pointing anywhere else is the
+ * link-following weakness (CWE-59) with the loader as the vehicle: the file
+ * that gets imported is not the file that was listed. The estate already
+ * decided this for its filesystem tools; the same rule applies to a directory
+ * whose author may not be the host.
+ *
+ * That is stricter than the SDK's own `discoverSkills`, and deliberately so —
+ * that function walks a host's own trusted tree, where following a link is a
+ * convenience rather than a hole. Reusing it here would have inherited a
+ * threat model chosen for a different caller.
+ *
+ * Only the top level is read. A nested directory is reported so an author
+ * learns their file was not picked up, except when its name starts with `.`
+ * or `_`, which is the conventional way to say "not for you" and is honoured
+ * silently.
+ */
+export async function scanSlot(
+	root: string,
+	slot: DirectorySlot,
+	dirName: string,
+): Promise<ScanResult> {
+	const dir = join(root, dirName)
+	const files: ScannedFile[] = []
+	const diagnostics: DirectoryDiagnostic[] = []
+
+	let entries: Dirent[]
+	try {
+		entries = await readdir(dir, { withFileTypes: true })
+	} catch {
+		// An absent optional directory is not news.
+		return { files, diagnostics }
+	}
+
+	for (const entry of entries) {
+		const name = entry.name
+		if (name.startsWith('.') || name.startsWith('_')) continue
+
+		const candidate = join(dir, name)
+
+		// `readdir(withFileTypes)` reports the link itself, so this catches a
+		// symlink before anything resolves it.
+		let stats: Awaited<ReturnType<typeof lstat>>
+		try {
+			stats = await lstat(candidate)
+		} catch {
+			continue
+		}
+
+		if (stats.isSymbolicLink()) {
+			diagnostics.push({
+				code: 'symlink_refused',
+				severity: 'warning',
+				message: `${dirName}/${name} is a symbolic link and was not loaded. The file that would be imported is not the file listed here, so links are refused rather than followed.`,
+				path: candidate,
+			})
+			continue
+		}
+
+		// Two slots hold DIRECTORIES rather than files: a skill is a folder
+		// with a SKILL.md, and a delegate is a whole project directory.
+		const directorySlot = slot === 'skills' || slot === 'agents'
+
+		if (stats.isDirectory()) {
+			if (directorySlot) {
+				files.push({
+					path: candidate,
+					relativePath: `${dirName}/${name}`,
+					id: name,
+				})
+				continue
+			}
+			diagnostics.push({
+				code: 'unscanned_directory',
+				severity: 'warning',
+				message: `${dirName}/${name}/ is a directory and was not scanned. Only files directly inside ${dirName}/ are loaded; prefix a directory with "." or "_" to declare it private and silence this.`,
+				path: candidate,
+			})
+			continue
+		}
+
+		if (!stats.isFile()) continue
+		// A loose file in a directory slot is not an error worth a diagnostic —
+		// a README beside the skill folders is normal.
+		if (directorySlot) continue
+
+		if (!CODE_EXTENSIONS.has(extname(name))) {
+			diagnostics.push({
+				code: 'unscanned_directory',
+				severity: 'warning',
+				message: `${dirName}/${name} is not a module this loader can import (expected one of ${[...CODE_EXTENSIONS].join(', ')}).`,
+				path: candidate,
+			})
+			continue
+		}
+
+		// Containment even though the path was built from a directory listing:
+		// the check costs nothing and it is the one place a future change to
+		// how `dir` is derived would otherwise escape unnoticed.
+		let contained: string
+		try {
+			contained = await resolveWithinReal(root, relative(root, candidate))
+		} catch {
+			diagnostics.push({
+				code: 'path_escapes_root',
+				severity: 'warning',
+				message: `${dirName}/${name} resolves outside the project root and was not loaded.`,
+				path: candidate,
+			})
+			continue
+		}
+
+		files.push({
+			path: contained,
+			relativePath: `${dirName}/${name}`,
+			id: basename(name, extname(name)),
+		})
+	}
+
+	files.sort((a, b) => a.relativePath.localeCompare(b.relativePath))
+	return { files, diagnostics }
+}
+
+/** Canonical absolute root, or undefined when the directory does not exist. */
+export async function canonicalRoot(dir: string): Promise<string | undefined> {
+	try {
+		const resolved = await realpath(dir)
+		const stats = await lstat(resolved)
+		return stats.isDirectory() ? resolved : undefined
+	} catch {
+		return undefined
+	}
+}
+
+/** Posix-normalised, for a `relativePath` that reads the same on every platform. */
+export function toPosix(value: string): string {
+	return value.split(sep).join('/')
+}

package/src/directory/types.ts

@@ -0,0 +1,254 @@
+import type { AgentIdentity, RunAgentOptions } from '../agents/runAgent.js'
+import type { Message } from '../types/message/index.js'
+import type { LLMProvider } from '../types/provider/index.js'
+import type { Skill } from '../types/skills/index.js'
+import type { ToolDefinition } from '../types/tool/index.js'
+
+/**
+ * A directory in the convention this package reads.
+ *
+ * `channels/` and `schedules/` are deliberately absent. They were scoped in
+ * and then cut: a trigger definition of `{id, handler}` cannot express a
+ * signed webhook, because signature verification needs the RAW body and a
+ * handler that receives a parsed one can never check an HMAC. It carries no
+ * idempotency key either, while webhooks retry and schedules double-fire, and
+ * a cron field with no timezone story is a declaration nothing drives. Each of
+ * those is a `major` waiting to happen on a published type. The layering
+ * question — does a convention belong outside the kernel — was answered yes
+ * and stands; the shape question had simply never been asked.
+ */
+export type DirectorySlot = 'agent' | 'instructions' | 'tools' | 'skills' | 'agents'
+
+export const ALL_SLOTS: readonly DirectorySlot[] = [
+	'agent',
+	'instructions',
+	'tools',
+	'skills',
+	'agents',
+]
+
+/**
+ * Whether the loader executes the project's code.
+ *
+ * `'evaluate'` imports every module-backed file, and importing a module RUNS
+ * it — a top-level side effect in `tools/search.ts` happens during
+ * `loadDirectory`, in this process, with this process's privileges.
+ *
+ * `'skip'` imports nothing. The manifest still carries the full structural
+ * truth — every path, the instructions, the skills, duplicate and ambiguity
+ * detection — and module-backed entries report `'not_loaded'`. This is what a
+ * CI gate, a UI file tree, and triage of a directory you did not write all
+ * actually want, and it is the only mode that is safe against a directory
+ * whose author you are not.
+ */
+export type ModuleMode = 'evaluate' | 'skip'
+
+export type ModuleImporter = (fileUrl: string) => Promise<unknown>
+
+export type SourceOutcome =
+	| 'loaded'
+	| 'failed'
+	/** Refused, or not a code file. Carries a diagnostic unless `.`/`_`-prefixed. */
+	| 'skipped'
+	/** `modules: 'skip'` — never imported, so nothing is known about its exports. */
+	| 'not_loaded'
+	/**
+	 * The import outran `moduleTimeoutMs`.
+	 *
+	 * NOT a synonym for `'failed'`. `import()` cannot be cancelled: the module
+	 * is still executing, may still complete, and its top-level side effects
+	 * may land after `loadDirectory` has returned. Node then caches it, so a
+	 * second load in the same process can see the same file succeed instantly.
+	 * A distinct outcome because "we stopped waiting" and "it did not work"
+	 * lead a reader to different places.
+	 */
+	| 'abandoned'
+
+export interface SourceRef {
+	/** Absolute and canonical — symlinks already resolved. */
+	readonly path: string
+	/** Posix, relative to the project root: `tools/search.ts`. */
+	readonly relativePath: string
+	readonly slot: DirectorySlot
+	/** Path-derived, extension stripped. `tools/search.ts` → `search`. */
+	readonly id: string
+	readonly outcome: SourceOutcome
+}
+
+export type DirectoryDiagnosticSeverity = 'error' | 'warning'
+
+export type DirectoryDiagnosticCode =
+	| 'instructions_missing'
+	| 'instructions_empty'
+	| 'module_load_failed'
+	| 'module_load_abandoned'
+	| 'no_default_export'
+	| 'not_a_tool'
+	| 'duplicate_tool_name'
+	| 'invalid_config'
+	| 'skill_load_failed'
+	| 'symlink_refused'
+	| 'path_escapes_root'
+	| 'unscanned_directory'
+	| 'root_missing'
+	| 'subagent_load_failed'
+	| 'subagent_too_deep'
+
+/**
+ * Something the loader could not do, reported rather than dropped.
+ *
+ * A loader that quietly skips a broken tool produces a project running with
+ * half its capabilities and nothing to say so. Every refusal names its file
+ * and its reason, and an inspector can render the list without re-reading the
+ * directory.
+ */
+export interface DirectoryDiagnostic {
+	readonly code: DirectoryDiagnosticCode
+	readonly severity: DirectoryDiagnosticSeverity
+	readonly message: string
+	/** Absolute path, when the diagnostic is about a file. */
+	readonly path?: string
+	/**
+	 * The underlying error's message, when there was one.
+	 *
+	 * This package never reads file CONTENTS into a diagnostic. What appears
+	 * here is text produced by Node or thrown by the authored module, and is
+	 * exactly as trustworthy as that module — a `throw new Error(secret)` puts
+	 * the secret here, and no amount of redaction on our side changes that.
+	 */
+	readonly cause?: string
+}
+
+export interface ToolEntry {
+	readonly source: SourceRef
+	readonly definition: ToolDefinition
+}
+
+/**
+ * A delegate this project declares, loaded as a project in its own right.
+ *
+ * Recursion rather than a new concept: a sub-agent directory has the same
+ * shape as its parent, so `agents/researcher/` is read by the same loader
+ * that read the root. One level only — a delegate may not declare delegates of its
+ * own in this version. Unbounded nesting is a topology decision (who may
+ * spawn whom, and how deep) that belongs to whoever composes the system, and
+ * shipping it before that decision means shipping a default nobody chose.
+ */
+export interface SubAgentEntry {
+	readonly source: SourceRef
+	/** The delegate's own manifest — its instructions, tools and config. */
+	readonly manifest: DirectoryManifest
+	/** Directory-derived, and the id a supervisor delegates to. */
+	readonly id: string
+}
+
+export interface SkillEntry {
+	readonly source: SourceRef
+	readonly skill: Skill
+}
+
+/**
+ * What `agent.ts` may declare.
+ *
+ * Deliberately a plain object, default-exported, with no authoring helper. A
+ * `defineAgent` here would collide with the SDK's existing export of that
+ * name, and `export default { model: 'x' } satisfies DirectoryConfig` already
+ * gets the type checking a helper would provide.
+ *
+ * There is no factory form. It would buy environment-conditioned config that
+ * `model: process.env.MODEL` already does inside a module that is being
+ * evaluated anyway, and it would cost a user-function-invocation phase with a
+ * hang mode outside what `moduleTimeoutMs` promises to bound.
+ */
+export interface DirectoryConfig {
+	readonly model?: string
+	readonly temperature?: number
+	readonly maxIterations?: number
+	readonly tokenBudget?: number
+	readonly timeoutMs?: number
+	/** Names the agent in traces and events when declared. */
+	readonly name?: string
+	/** Free-form labels for an inspector. Never interpreted by this package. */
+	readonly metadata?: Readonly<Record<string, string>>
+}
+
+export interface DirectoryManifest {
+	/** Absolute, canonical path to the `agent/` directory. */
+	readonly root: string
+	/**
+	 * A DISPLAY LABEL — `config.name`, else the directory's basename, else
+	 * `'agent'`.
+	 *
+	 * Not a trace key, and `deriveRunOptions` forwards it to `runAgent` only
+	 * when `agent.ts` declared one. A name guessed from a directory basename
+	 * would collide across sibling projects and silently merge their traces,
+	 * which is worse than the SDK's own default.
+	 */
+	readonly name: string
+	/** Verbatim `instructions.md`, trailing whitespace removed. */
+	readonly instructions: string
+	readonly config: DirectoryConfig
+	readonly tools: readonly ToolEntry[]
+	readonly skills: readonly SkillEntry[]
+	/** Delegates this project declares. Empty unless it has an `agents/` slot. */
+	readonly agents: readonly SubAgentEntry[]
+	/** Every file considered, with its outcome. An inspector's ground truth. */
+	readonly sources: readonly SourceRef[]
+	/** Which slots were scanned. What `ok` is scoped to. */
+	readonly included: readonly DirectorySlot[]
+	readonly modules: ModuleMode
+}
+
+export interface DirectoryLoadResult {
+	readonly manifest: DirectoryManifest
+	readonly diagnostics: readonly DirectoryDiagnostic[]
+	/**
+	 * True when no diagnostic is an error.
+	 *
+	 * Scoped to `manifest.included`: it means "every slot you asked for is
+	 * sound", never "this directory is complete". A caller that scanned only
+	 * `tools` learns nothing here about `instructions`.
+	 */
+	readonly ok: boolean
+}
+
+export interface LoadDirectoryOptions {
+	/** See {@link ModuleMode}. Default `'evaluate'`. */
+	readonly modules?: ModuleMode
+	/**
+	 * Replace the import.
+	 *
+	 * The exit for a project Node's own type stripping cannot read — enums,
+	 * decorators, tsconfig path aliases — where a host passes `jiti.import` or
+	 * a `tsx`-registered importer. Three lines in the host, and no bundler
+	 * dependency in this tree; the same rule `LLMProvider` follows.
+	 *
+	 * Ignored under `modules: 'skip'`, where nothing is imported at all.
+	 */
+	readonly importModule?: ModuleImporter
+	/**
+	 * Slots to scan. Default: all of them.
+	 *
+	 * The tuple type makes an empty array unrepresentable in TypeScript on
+	 * purpose. This is an allow-list, and an allow-list that admits everything
+	 * when empty is the fail-open shape this estate removed elsewhere; here an
+	 * empty list scans nothing, which is the closed reading.
+	 */
+	readonly include?: readonly [DirectorySlot, ...DirectorySlot[]]
+	/**
+	 * Per-module deadline. Default 10_000ms.
+	 *
+	 * Bounds THIS LOADER, not the module. An import that expires is not
+	 * cancelled — see {@link SourceOutcome} `'abandoned'`.
+	 */
+	readonly moduleTimeoutMs?: number
+}
+
+export interface DeriveRunOptionsInput {
+	readonly provider: LLMProvider
+	readonly prompt: string | Message[]
+	/** Wins over `agent.ts`. Required when `agent.ts` names no model. */
+	readonly model?: string
+	readonly identity?: AgentIdentity
+	readonly overrides?: Partial<Omit<RunAgentOptions, 'provider' | 'prompt'>>
+}

package/src/plugin/__tests__/path-containment.test.ts

@@ -0,0 +1,107 @@
+import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import { PluginRegistry } from '../../registry/plugin/index.js'
+import { ToolRegistry } from '../../registry/tool/execute.js'
+import { getRootLogger } from '../../utils/logger.js'
+import { PluginLifecycleManager } from '../lifecycle.js'
+import { discoverPlugins } from '../loader.js'
+
+/**
+ * The plugin subsystem loads THIRD-PARTY code, which makes it the worst place
+ * in this repo to be missing the containment its filesystem tools got this
+ * week. It had none: zero `lstat`, zero `isSymbolicLink`, zero `resolveWithin`
+ * across the loader and the lifecycle manager.
+ *
+ * Two holes, and the second is the serious one.
+ *
+ * `discoverPlugins` used `stat`, which follows a link and reports on its
+ * TARGET — so a symlinked entry pointing anywhere on disk was admitted as a
+ * plugin directory. The directory listed was not the directory loaded.
+ *
+ * And `PluginLifecycleManager` built its import path with
+ * `join(plugin.rootDir, toolPath)` where `toolPath` comes out of the
+ * MANIFEST — a file the plugin author writes. `"tools": ["../../../evil.js"]`
+ * left the plugin directory entirely and was imported, which runs it.
+ */
+
+const CAN_SYMLINK = (() => {
+	try {
+		const probe = mkdtempSync(join(tmpdir(), 'namzu-plug-sym-'))
+		symlinkSync(probe, join(probe, 'self'), 'dir')
+		return true
+	} catch {
+		return false
+	}
+})()
+
+function pluginsDir(): string {
+	return mkdtempSync(join(tmpdir(), 'namzu-plugins-'))
+}
+
+function writePlugin(parent: string, name: string, manifest: Record<string, unknown>): string {
+	const dir = join(parent, name)
+	mkdirSync(dir, { recursive: true })
+	writeFileSync(
+		join(dir, 'plugin.json'),
+		JSON.stringify({ name, version: '1.0.0', description: 'test', ...manifest }),
+	)
+	return dir
+}
+
+describe('plugin discovery refuses a symlinked directory', () => {
+	it.skipIf(!CAN_SYMLINK)('does not admit a link as a plugin directory', async () => {
+		const outside = mkdtempSync(join(tmpdir(), 'namzu-outside-'))
+		writePlugin(outside, 'evil', { tools: [] })
+
+		const parent = pluginsDir()
+		writePlugin(parent, 'honest', { tools: [] })
+		symlinkSync(join(outside, 'evil'), join(parent, 'linked'), 'dir')
+
+		const found = await discoverPlugins(parent)
+
+		expect(found.map((p) => p.split(/[\\/]/).pop())).toEqual(['honest'])
+	})
+
+	it('still finds an ordinary plugin directory', async () => {
+		const parent = pluginsDir()
+		writePlugin(parent, 'ordinary', { tools: [] })
+
+		expect(await discoverPlugins(parent)).toHaveLength(1)
+	})
+})
+
+function managerFor(def: unknown): PluginLifecycleManager {
+	const pluginRegistry = new PluginRegistry()
+	pluginRegistry.register(def as never)
+	return new PluginLifecycleManager({
+		pluginRegistry,
+		toolRegistry: new ToolRegistry(),
+		log: getRootLogger(),
+	} as never)
+}
+
+describe('a manifest cannot name a file outside its own plugin', () => {
+	it('refuses a tool path that climbs out', async () => {
+		// The manifest is written by the plugin author. Without containment the
+		// named file was imported — which is to say, executed.
+		const outside = mkdtempSync(join(tmpdir(), 'namzu-outside-'))
+		writeFileSync(join(outside, 'evil.js'), 'export const tools = []')
+		const parent = pluginsDir()
+		const escaping = join('..', outside.split(/[\/]/).pop() as string, 'evil.js')
+		const dir = writePlugin(parent, 'sneaky', { tools: [escaping] })
+
+		const manager = managerFor({
+			id: 'sneaky',
+			manifest: { name: 'sneaky', version: '1.0.0', description: 't', tools: [escaping] },
+			scope: 'project',
+			status: 'installed',
+			rootDir: dir,
+			installedAt: 0,
+		})
+
+		await expect(manager.enable('sneaky' as never)).rejects.toThrow(/escapes the working directory/)
+	})
+})

package/src/plugin/lifecycle.ts

@@ -1,4 +1,3 @@
-import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { mcpToolToToolDefinition } from '../connector/mcp/adapter.js'
 import { MCPClient } from '../connector/mcp/client.js'
@@ -12,6 +11,7 @@ import {
 	PLUGIN_NAMESPACE_SEPARATOR,
 } from '../constants/plugin/index.js'
 import type { PluginRegistry } from '../registry/plugin/index.js'
+import { resolveWithinReal } from '../tools/paths.js'
 import type { PluginId } from '../types/ids/index.js'
 import type {
 	PluginDefinition,
@@ -218,7 +218,7 @@ export class PluginLifecycleManager {
 			// Load tools
 			if (manifest.tools && manifest.tools.length > 0) {
 				for (const toolPath of manifest.tools) {
-					const absolutePath = join(plugin.rootDir, toolPath)
+					const absolutePath = await resolveWithinReal(plugin.rootDir, toolPath)
 					const fileUrl = pathToFileURL(absolutePath).href
 					const mod = (await import(fileUrl)) as { tools?: ToolDefinition[] }
 
@@ -240,7 +240,7 @@ export class PluginLifecycleManager {
 			// Load hooks
 			if (manifest.hooks && manifest.hooks.length > 0) {
 				for (const hookPath of manifest.hooks) {
-					const absolutePath = join(plugin.rootDir, hookPath)
+					const absolutePath = await resolveWithinReal(plugin.rootDir, hookPath)
 					const fileUrl = pathToFileURL(absolutePath).href
 					const mod = (await import(fileUrl)) as { hooks?: PluginHookDefinition[] }
 

package/src/plugin/loader.ts

@@ -1,4 +1,4 @@
-import { readFile, readdir, stat } from 'node:fs/promises'
+import { lstat, readFile, readdir, stat } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import {
@@ -23,7 +23,17 @@ export async function discoverPlugins(parentDir: string): Promise<string[]> {
 		for (const entry of entries) {
 			if (entry.startsWith('.') || entry.startsWith('_')) continue
 			const fullPath = join(parentDir, entry)
-			const s = await stat(fullPath)
+			// `lstat`, not `stat`: `stat` follows the link and reports on its
+			// TARGET, so a symlinked entry pointing anywhere on disk was
+			// admitted as a plugin directory and its manifest read from there.
+			// A plugins directory holds third-party code by definition, which
+			// makes following a link out of it the worse half of CWE-59 — the
+			// directory listed is not the directory loaded.
+			const s = await lstat(fullPath)
+			if (s.isSymbolicLink()) {
+				logger.warn('Refusing a symlinked plugin directory', { path: fullPath })
+				continue
+			}
 			if (!s.isDirectory()) continue
 
 			const manifestPath = join(fullPath, PLUGIN_MANIFEST_FILENAME)

package/src/provider/__tests__/model-version.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+
+import { modelVersionAtLeast, parseVersionedModelId } from '../model-version.js'
+import type { ModelIdGrammar } from '../model-version.js'
+
+/**
+ * The defect this module exists to end: the minor-version group was `\d+`, so
+ * it swallowed the 8-digit release date. An id naming no minor therefore
+ * parsed as `major.<the date>` and compared as enormously NEWER than one that
+ * does, inverting every capability gate keyed on `minor >= n` — a model was
+ * told it supported features it does not.
+ *
+ * Three drivers had each written the same matcher, and all three had it. The
+ * vocabulary below is deliberately invented: the shape is what lives here, and
+ * a test that needed real product names would be testing the wrong layer.
+ */
+
+const GRAMMAR: ModelIdGrammar = {
+	product: 'widget',
+	families: ['small', 'large'],
+	routingPrefix: 'vendor/',
+}
+
+describe('a date suffix is not a minor version', () => {
+	it.each([
+		['widget-small-4-20250514', 'small', 4, 0],
+		['widget-large-4-20250514', 'large', 4, 0],
+		['widget-small-3-20240307', 'small', 3, 0],
+	])('%s parses as %s %d.%d', (id, family, major, minor) => {
+		expect(parseVersionedModelId(id, GRAMMAR)).toEqual({ family, major, minor })
+	})
+
+	it('still reads a real minor that is followed by a date', () => {
+		expect(parseVersionedModelId('widget-large-4-1-20250805', GRAMMAR)).toEqual({
+			family: 'large',
+			major: 4,
+			minor: 1,
+		})
+		expect(parseVersionedModelId('widget-small-4-5-20250929', GRAMMAR)?.minor).toBe(5)
+	})
+
+	it('treats a missing minor as .0 rather than as absent', () => {
+		expect(parseVersionedModelId('widget-large-5', GRAMMAR)).toEqual({
+			family: 'large',
+			major: 5,
+			minor: 0,
+		})
+	})
+
+	it('tolerates the routing prefix, the other separators, and case', () => {
+		expect(parseVersionedModelId('vendor/widget-large-4-5', GRAMMAR)?.minor).toBe(5)
+		expect(parseVersionedModelId('widget-large-4.5', GRAMMAR)?.minor).toBe(5)
+		expect(parseVersionedModelId('WIDGET-LARGE-4-5', GRAMMAR)?.major).toBe(4)
+	})
+
+	it('returns undefined for what the grammar does not describe', () => {
+		for (const id of ['other-large-4', 'widget', 'widget-large', 'widget-medium-4', '']) {
+			expect(parseVersionedModelId(id, GRAMMAR)).toBeUndefined()
+		}
+	})
+
+	it('escapes regex metacharacters in the grammar', () => {
+		// A product or prefix containing `.` or `+` must match literally, not
+		// as a wildcard. `.map(escape)` — the global, deprecated one — would
+		// percent-encode instead, and pass every other test in this file
+		// because no ordinary name contains a character it changes.
+		const odd: ModelIdGrammar = { product: 'a.b', families: ['c+d'] }
+
+		expect(parseVersionedModelId('a.b-c+d-4', odd)?.major).toBe(4)
+		expect(parseVersionedModelId('axb-cxd-4', odd)).toBeUndefined()
+	})
+})
+
+describe('modelVersionAtLeast', () => {
+	it('does not let a dated id clear a gate it is below', () => {
+		// The whole point. With the old `\d+` minor this was `true`, because
+		// 4.20250514 >= 4.5.
+		expect(modelVersionAtLeast('widget-small-4-20250514', GRAMMAR, 4, 5)).toBe(false)
+		expect(modelVersionAtLeast('widget-large-4-20250514', GRAMMAR, 4, 7)).toBe(false)
+	})
+
+	it('admits versions that genuinely clear it', () => {
+		expect(modelVersionAtLeast('widget-small-4-5-20250929', GRAMMAR, 4, 5)).toBe(true)
+		expect(modelVersionAtLeast('widget-large-5', GRAMMAR, 4, 7)).toBe(true)
+		expect(modelVersionAtLeast('widget-large-4-1', GRAMMAR, 4, 5)).toBe(false)
+	})
+
+	it('refuses a name it cannot parse rather than opening the gate', () => {
+		// Fail-safe: a capability gate must not open for an id it does not
+		// understand.
+		expect(modelVersionAtLeast('something-else', GRAMMAR, 4, 5)).toBe(false)
+	})
+})