@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/domains/lifecycle/naming-resources.ts

@@ -0,0 +1,276 @@
+import {
+	cpSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { parse as parseYaml } from "yaml";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { fsyncDirectory } from "../../core/safe-resource-write.js";
+import { resolveClioDirs } from "../../core/xdg.js";
+import { INTEROP_AGENT_KINDS } from "../interop/registry.js";
+import { normalizedSkillHash, stripProvenanceFrontmatter } from "../resources/skills/content-hash.js";
+
+const LEGACY_SKILL_NAMES = [
+	["clio-dev", "clio-coder-dev"],
+	["clio-test", "clio-coder-test"],
+] as const;
+
+export type NamingResourceStatus = "absent" | "canonical-present" | "modified" | "renamable" | "renamed";
+
+export interface NamingResourceReport {
+	kind: "skill";
+	legacyPath: string;
+	canonicalPath: string;
+	status: NamingResourceStatus;
+	detail: string;
+}
+
+export interface NamingResourceOptions {
+	cwd?: string;
+	configDir?: string;
+	/** Home directory whose interop skill roots are inspected; defaults to the OS home. */
+	home?: string;
+	packageRoot?: string;
+	fix?: boolean;
+}
+
+function canonicalizeNamingText(text: string): string {
+	return text
+		.replaceAll("clio-dev", "clio-coder-dev")
+		.replaceAll("clio-test", "clio-coder-test")
+		.replace(/^clio:/gmu, "clio-coder:")
+		.replace(/^(\s*source:\s*)clio\s*$/gmu, "$1clio-coder");
+}
+
+function installedHash(raw: string): string | null {
+	const match = raw.match(/^\s*installed-hash:\s*["']?([0-9a-f]{64})["']?\s*$/mu);
+	return match?.[1] ?? null;
+}
+
+function regularFiles(root: string, current = root): string[] {
+	const out: string[] = [];
+	for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+		const full = path.join(current, entry.name);
+		if (entry.isDirectory()) out.push(...regularFiles(root, full));
+		else if (entry.isFile()) out.push(path.relative(root, full));
+		else return [];
+	}
+	return out;
+}
+
+function provesUnmodifiedShippedCopy(legacyDir: string, canonicalBundleDir: string): boolean {
+	let legacyFiles: string[];
+	let canonicalFiles: string[];
+	try {
+		legacyFiles = regularFiles(legacyDir);
+		canonicalFiles = regularFiles(canonicalBundleDir);
+	} catch {
+		return false;
+	}
+	if (legacyFiles.length === 0 || legacyFiles.join("\0") !== canonicalFiles.join("\0")) return false;
+	for (const relative of legacyFiles) {
+		const legacyRaw = readFileSync(path.join(legacyDir, relative), "utf8");
+		const canonicalRaw = readFileSync(path.join(canonicalBundleDir, relative), "utf8");
+		if (relative === "SKILL.md") {
+			const recordedHash = installedHash(legacyRaw);
+			if (recordedHash === null || recordedHash !== normalizedSkillHash(legacyRaw)) return false;
+			if (canonicalizeNamingText(stripProvenanceFrontmatter(legacyRaw)) !== stripProvenanceFrontmatter(canonicalRaw))
+				return false;
+			continue;
+		}
+		if (canonicalizeNamingText(legacyRaw) !== canonicalRaw) return false;
+	}
+	return true;
+}
+
+function rewriteStagedCopy(stage: string, canonicalBundleDir: string): void {
+	const canonicalSkillHash = normalizedSkillHash(readFileSync(path.join(canonicalBundleDir, "SKILL.md"), "utf8"));
+	for (const relative of regularFiles(stage)) {
+		const file = path.join(stage, relative);
+		let next = canonicalizeNamingText(readFileSync(file, "utf8"));
+		if (relative === "SKILL.md") {
+			next = next.replace(/^(\s*installed-hash:\s*).+$/mu, `$1"${canonicalSkillHash}"`);
+		}
+		writeFileSync(file, next, "utf8");
+	}
+}
+
+let resourceSwapSequence = 0;
+
+function migrateProvenSkill(legacyDir: string, canonicalDir: string, canonicalBundleDir: string): void {
+	const suffix = `${process.pid}-${++resourceSwapSequence}`;
+	const stage = `${canonicalDir}.clio-coder-naming-stage-${suffix}`;
+	const backup = `${legacyDir}.clio-coder-naming-backup-${suffix}`;
+	mkdirSync(path.dirname(canonicalDir), { recursive: true });
+	cpSync(legacyDir, stage, { recursive: true });
+	try {
+		rewriteStagedCopy(stage, canonicalBundleDir);
+		renameSync(legacyDir, backup);
+		try {
+			renameSync(stage, canonicalDir);
+		} catch (error) {
+			renameSync(backup, legacyDir);
+			throw error;
+		}
+		rmSync(backup, { recursive: true, force: true });
+		fsyncDirectory(path.dirname(canonicalDir));
+	} catch (error) {
+		rmSync(stage, { recursive: true, force: true });
+		throw error;
+	}
+}
+
+function existingDirectory(candidate: string): boolean {
+	try {
+		return statSync(candidate).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** Inspect only the selected user root and current project; never scan arbitrary repositories. */
+export function inspectInstalledNamingResources(options: NamingResourceOptions = {}): NamingResourceReport[] {
+	const cwd = options.cwd ?? process.cwd();
+	const configDir = options.configDir ?? resolveClioDirs().config;
+	const packageRoot = options.packageRoot ?? resolvePackageRoot();
+	const roots = [path.join(configDir, "skills"), path.join(cwd, ".clio-coder", "skills")];
+	const reports: NamingResourceReport[] = [];
+	for (const root of roots) {
+		for (const [legacyName, canonicalName] of LEGACY_SKILL_NAMES) {
+			const legacyPath = path.join(root, legacyName);
+			const canonicalPath = path.join(root, canonicalName);
+			if (!existingDirectory(legacyPath)) {
+				reports.push({ kind: "skill", legacyPath, canonicalPath, status: "absent", detail: "legacy skill absent" });
+				continue;
+			}
+			if (existsSync(canonicalPath)) {
+				reports.push({
+					kind: "skill",
+					legacyPath,
+					canonicalPath,
+					status: "canonical-present",
+					detail: "canonical skill already exists; legacy copy left untouched",
+				});
+				continue;
+			}
+			const canonicalBundleDir = path.join(packageRoot, "skills", "meta", canonicalName);
+			if (!existingDirectory(canonicalBundleDir) || !provesUnmodifiedShippedCopy(legacyPath, canonicalBundleDir)) {
+				reports.push({
+					kind: "skill",
+					legacyPath,
+					canonicalPath,
+					status: "modified",
+					detail: "frontmatter/provenance/hash do not prove an unmodified shipped copy; left untouched",
+				});
+				continue;
+			}
+			if (options.fix) migrateProvenSkill(legacyPath, canonicalPath, canonicalBundleDir);
+			reports.push({
+				kind: "skill",
+				legacyPath,
+				canonicalPath,
+				status: options.fix ? "renamed" : "renamable",
+				detail: options.fix
+					? "proven unmodified shipped copy renamed and canonicalized"
+					: "proven unmodified shipped copy can be renamed by doctor --fix",
+			});
+		}
+	}
+	return reports;
+}
+
+export interface ModelOverlayNamingInspection {
+	path: string;
+	legacyFile: boolean;
+	legacyMetadataKeys: number;
+}
+
+export interface SkillMetadataNamingInspection {
+	path: string;
+	legacyMetadataKey: boolean;
+}
+
+function collectSkillFiles(root: string, current = root): string[] {
+	if (!existingDirectory(current)) return [];
+	const out: string[] = [];
+	for (const entry of readdirSync(current, { withFileTypes: true })) {
+		const full = path.join(current, entry.name);
+		if (entry.isDirectory()) out.push(...collectSkillFiles(root, full));
+		else if (entry.isFile() && entry.name === "SKILL.md") out.push(full);
+	}
+	return out;
+}
+
+/**
+ * Read-only inventory of released skill metadata keys in every root the skill
+ * loader reads: the Clio user and project roots plus each interop agent's
+ * user and project compatibility roots (`.claude/skills`, `.agents/skills`,
+ * ...). The loader warns for a legacy key in any of them, so the doctor has to
+ * look where the loader looks or it reports "canonical" while boot warns.
+ */
+export function inspectSkillMetadataNaming(
+	options: Pick<NamingResourceOptions, "cwd" | "configDir" | "home"> = {},
+): SkillMetadataNamingInspection[] {
+	const cwd = options.cwd ?? process.cwd();
+	const configDir = options.configDir ?? resolveClioDirs().config;
+	const home = options.home ?? homedir();
+	const roots = new Set<string>([path.join(configDir, "skills"), path.join(cwd, ".clio-coder", "skills")]);
+	for (const kind of INTEROP_AGENT_KINDS) {
+		if (kind.userSkillRoot !== undefined) roots.add(path.join(home, kind.userSkillRoot));
+		if (kind.projectSkillRoot !== undefined) roots.add(path.join(cwd, kind.projectSkillRoot));
+	}
+	return [...roots].flatMap((root) =>
+		collectSkillFiles(root).map((file) => ({
+			path: file,
+			legacyMetadataKey: /^clio:\s*(?:#.*)?$/mu.test(readFileSync(file, "utf8")),
+		})),
+	);
+}
+
+function countLegacyModelMetadata(value: unknown): number {
+	if (Array.isArray(value)) return value.reduce((count, entry) => count + countLegacyModelMetadata(entry), 0);
+	if (typeof value !== "object" || value === null) return 0;
+	const record = value as Record<string, unknown>;
+	return (
+		(Object.hasOwn(record, "clio") ? 1 : 0) +
+		Object.values(record).reduce<number>((count, entry) => count + countLegacyModelMetadata(entry), 0)
+	);
+}
+
+/** Read-only overlay inventory. User catalog files are never silently rewritten. */
+export function inspectModelOverlayNaming(
+	options: Pick<NamingResourceOptions, "cwd" | "configDir"> = {},
+): ModelOverlayNamingInspection[] {
+	const cwd = options.cwd ?? process.cwd();
+	const configDir = options.configDir ?? resolveClioDirs().config;
+	const roots = [path.join(configDir, "model-catalog.d"), path.join(cwd, ".clio-coder", "model-catalog.d")];
+	const inspections: ModelOverlayNamingInspection[] = [];
+	for (const root of roots) {
+		if (!existingDirectory(root)) continue;
+		for (const entry of readdirSync(root, { withFileTypes: true })) {
+			if (!entry.isFile() || (!entry.name.endsWith(".yaml") && !entry.name.endsWith(".yml"))) continue;
+			const file = path.join(root, entry.name);
+			let legacyMetadataKeys = 0;
+			try {
+				legacyMetadataKeys = countLegacyModelMetadata(parseYaml(readFileSync(file, "utf8")));
+			} catch {
+				// The catalog loader owns the parse diagnostic; naming still reports the filename.
+			}
+			inspections.push({
+				path: file,
+				legacyFile: entry.name === "clio-local-coding-targets.yaml",
+				legacyMetadataKeys,
+			});
+		}
+	}
+	return inspections;
+}

package/src/domains/lifecycle/naming-tool-markers.ts

@@ -0,0 +1,139 @@
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+import { fsyncDirectory } from "../../core/safe-resource-write.js";
+import { resolveClioDirs } from "../../core/xdg.js";
+import { findPinnedTool } from "../toolchain/registry.js";
+
+export const LEGACY_TOOL_MARKER = "clio-install.json";
+export const CANONICAL_TOOL_MARKER = "clio-coder-install.json";
+
+interface ValidToolMarker {
+	id: string;
+	version: string;
+	sha256: string;
+}
+
+export type ToolMarkerNamingStatus =
+	| "renamable"
+	| "renamed"
+	| "invalid-legacy"
+	| "canonical-conflict"
+	| "agreeing-duplicate"
+	| "duplicate-removed";
+
+export interface ToolMarkerNamingReport {
+	tool: string;
+	version: string;
+	legacyPath: string;
+	canonicalPath: string;
+	status: ToolMarkerNamingStatus;
+	detail: string;
+}
+
+export interface ToolMarkerNamingOptions {
+	dataDir?: string;
+	fix?: boolean;
+}
+
+function childDirectories(root: string): string[] {
+	try {
+		return readdirSync(root, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+			.map((entry) => entry.name)
+			.sort((left, right) => left.localeCompare(right));
+	} catch {
+		return [];
+	}
+}
+
+function readValidMarker(path: string, tool: string, version: string): ValidToolMarker | null {
+	try {
+		const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+		const marker = value as Record<string, unknown>;
+		if (marker.id !== tool || marker.version !== version) return null;
+		if (typeof marker.sha256 !== "string" || !/^[0-9a-f]{64}$/u.test(marker.sha256)) return null;
+		return { id: tool, version, sha256: marker.sha256 };
+	} catch {
+		return null;
+	}
+}
+
+function sameFacts(left: ValidToolMarker, right: ValidToolMarker): boolean {
+	return left.id === right.id && left.version === right.version && left.sha256 === right.sha256;
+}
+
+/**
+ * Inspect or migrate released tool markers only below known tool/version
+ * directories in the selected Clio Coder data root. Unknown tool roots and
+ * symlinks are never traversed.
+ */
+export function inspectToolMarkerNaming(options: ToolMarkerNamingOptions = {}): ToolMarkerNamingReport[] {
+	const toolsRoot = join(options.dataDir ?? resolveClioDirs().data, "tools");
+	const reports: ToolMarkerNamingReport[] = [];
+	for (const tool of childDirectories(toolsRoot)) {
+		if (findPinnedTool(tool) === null) continue;
+		for (const version of childDirectories(join(toolsRoot, tool))) {
+			const dir = join(toolsRoot, tool, version);
+			const legacyPath = join(dir, LEGACY_TOOL_MARKER);
+			if (!existsSync(legacyPath)) continue;
+			const canonicalPath = join(dir, CANONICAL_TOOL_MARKER);
+			const legacy = readValidMarker(legacyPath, tool, version);
+			if (legacy === null) {
+				reports.push({
+					tool,
+					version,
+					legacyPath,
+					canonicalPath,
+					status: "invalid-legacy",
+					detail: "legacy marker does not match its known tool/version path and checksum shape; left untouched",
+				});
+				continue;
+			}
+			if (!existsSync(canonicalPath)) {
+				if (options.fix) {
+					renameSync(legacyPath, canonicalPath);
+					fsyncDirectory(dir);
+				}
+				reports.push({
+					tool,
+					version,
+					legacyPath,
+					canonicalPath,
+					status: options.fix ? "renamed" : "renamable",
+					detail: options.fix ? "validated legacy marker renamed atomically" : "validated legacy marker can be renamed",
+				});
+				continue;
+			}
+			const canonical = readValidMarker(canonicalPath, tool, version);
+			if (canonical === null || !sameFacts(legacy, canonical)) {
+				reports.push({
+					tool,
+					version,
+					legacyPath,
+					canonicalPath,
+					status: "canonical-conflict",
+					detail:
+						"canonical and legacy marker facts disagree or canonical is invalid; canonical wins and legacy is left untouched",
+				});
+				continue;
+			}
+			if (options.fix) {
+				rmSync(legacyPath);
+				fsyncDirectory(dir);
+			}
+			reports.push({
+				tool,
+				version,
+				legacyPath,
+				canonicalPath,
+				status: options.fix ? "duplicate-removed" : "agreeing-duplicate",
+				detail: options.fix
+					? "validated agreeing legacy duplicate removed; canonical marker kept"
+					: "canonical and legacy facts agree; legacy duplicate can be removed",
+			});
+		}
+	}
+	return reports;
+}

package/src/domains/lifecycle/naming-yazi.ts

@@ -0,0 +1,86 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveClioDirs } from "../../core/xdg.js";
+import { ensureYaziProfile, resetYaziProfile, yaziProfileDir } from "../mux/yazi/profile.js";
+import { resolveToolBinary } from "../toolchain/resolve.js";
+
+export interface YaziNamingInspection {
+	profileDir: string;
+	present: boolean;
+	legacyEvents: number;
+	legacyEnvironmentNames: number;
+}
+
+export interface YaziNamingRegenerationReport extends YaziNamingInspection {
+	status: "absent" | "canonical" | "regenerated" | "removed-unresolved" | "regeneration-failed";
+	detail: string;
+}
+
+export interface YaziNamingOptions {
+	cacheDir?: string;
+	yaziPath?: string | null;
+	yaPath?: string | null;
+}
+
+function occurrences(text: string, pattern: RegExp): number {
+	return [...text.matchAll(pattern)].length;
+}
+
+/** Inspect only the generated keymap below the selected Clio Coder cache root. */
+export function inspectYaziNaming(cacheDir: string = resolveClioDirs().cache): YaziNamingInspection {
+	const profileDir = yaziProfileDir(cacheDir);
+	const present = statSync(profileDir, { throwIfNoEntry: false })?.isDirectory() === true;
+	let keymap = "";
+	try {
+		keymap = readFileSync(join(profileDir, "keymap.toml"), "utf8");
+	} catch {
+		// Missing or unreadable generated material is handled as disposable cache.
+	}
+	return {
+		profileDir,
+		present,
+		legacyEvents: occurrences(keymap, /(?<!clio-coder-)clio-pick/gmu),
+		legacyEnvironmentNames: occurrences(keymap, /\$CLIO_YAZI_PICK_TOKEN\b/gmu),
+	};
+}
+
+/**
+ * Replace the disposable managed profile from current inputs. Resolution is
+ * performed before removal so the report can state why a profile could not be
+ * rebuilt, while deletion remains confined to `<cache>/yazi/profile`.
+ */
+export function regenerateYaziNamingProfile(options: YaziNamingOptions = {}): YaziNamingRegenerationReport {
+	const cacheDir = options.cacheDir ?? resolveClioDirs().cache;
+	const before = inspectYaziNaming(cacheDir);
+	if (!before.present) {
+		return {
+			...before,
+			status: "absent",
+			detail: "managed files pane profile is absent; next open writes canonical names",
+		};
+	}
+	if (before.legacyEvents === 0 && before.legacyEnvironmentNames === 0) {
+		return { ...before, status: "canonical", detail: "managed files pane profile already uses canonical names" };
+	}
+	const yaziPath = options.yaziPath === undefined ? resolveToolBinary("yazi").binaryPath : options.yaziPath;
+	const yaPath = options.yaPath === undefined ? resolveToolBinary("ya").binaryPath : options.yaPath;
+	resetYaziProfile(before.profileDir);
+	if (!yaziPath || !yaPath) {
+		return {
+			...before,
+			status: "removed-unresolved",
+			detail:
+				"legacy managed profile removed; the files pane engine is unresolved, so the next managed open will regenerate it",
+		};
+	}
+	const profile = ensureYaziProfile({ yaziPath, yaPath, profileDir: before.profileDir });
+	if (!profile) {
+		return {
+			...before,
+			status: "regeneration-failed",
+			detail: "legacy managed profile removed, but the files pane engine rejected the regenerated profile",
+		};
+	}
+	return { ...before, status: "regenerated", detail: "managed files pane profile regenerated with canonical names" };
+}

package/src/domains/lifecycle/upgrade-notice.ts

@@ -27,7 +27,7 @@ const KEYBOARD_FACING_CHANGES: Readonly<Record<string, string>> = Object.freeze(
  */
 export function describeUpgradeNotice(transition: UpgradeTransition): string {
 	const changes = KEYBOARD_FACING_CHANGES[transition.to];
-	const head = `clio: upgraded ${transition.from} → ${transition.to}.`;
+	const head = `clio-coder: upgraded ${transition.from} → ${transition.to}.`;
 	const tail = `Full notes: CHANGELOG.md, section ${transition.to}.`;
 	return changes === undefined
 		? `${head} What changed is in CHANGELOG.md, section ${transition.to}.`

package/src/domains/memory/task-memory-handoff.ts

@@ -11,7 +11,8 @@ import {
 } from "./task-bank.js";
 
 export const TASK_MEMORY_HANDOFF_VERSION = 2;
-export const TASK_MEMORY_HANDOFF_LANGUAGE = "clio-task-memory";
+export const TASK_MEMORY_HANDOFF_LANGUAGE = "clio-coder-task-memory";
+const LEGACY_TASK_MEMORY_HANDOFF_LANGUAGE = "clio-task-memory";
 const HANDOFF_MAX_BYTES = 1_000_000;
 
 export interface TaskMemoryHandoffEntry {
@@ -134,8 +135,10 @@ export function renderTaskMemoryHandoffSource(
 
 export function parseTaskMemoryHandoffSnapshot(text: string): TaskMemoryHandoffSnapshot | null {
 	if (typeof text !== "string" || text.length === 0 || text.length > HANDOFF_MAX_BYTES) return null;
-	const escapedLanguage = TASK_MEMORY_HANDOFF_LANGUAGE.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-	const match = new RegExp(`(?:^|\\n)\\x60{3}${escapedLanguage}\\r?\\n([^\\r\\n]+)\\r?\\n\\x60{3}(?:$|\\n)`, "u").exec(
+	const languages = [TASK_MEMORY_HANDOFF_LANGUAGE, LEGACY_TASK_MEMORY_HANDOFF_LANGUAGE]
+		.map((language) => language.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"))
+		.join("|");
+	const match = new RegExp(`(?:^|\\n)\\x60{3}(?:${languages})\\r?\\n([^\\r\\n]+)\\r?\\n\\x60{3}(?:$|\\n)`, "u").exec(
 		text,
 	);
 	if (match?.[1] === undefined) return null;

package/src/domains/middleware/contract.ts

@@ -1,3 +1,8 @@
+import type {
+	MiddlewareRegistrationOwner,
+	PrepareRegistrationReplacementResult,
+	ReplaceRegistrationsReport,
+} from "./registrations.js";
 import type { MiddlewareDiagnosticSink, MiddlewareHookRegistration } from "./runtime.js";
 import type {
 	MiddlewareEffect,
@@ -32,4 +37,25 @@ export interface MiddlewareContract {
 	 * stderr writer default.
 	 */
 	setDiagnosticSink(sink: MiddlewareDiagnosticSink): void;
+	/**
+	 * Validate an owner's replacement registration set against the current
+	 * builtin and host ids and build its evaluation list without publishing.
+	 * Rejected when `generation` is not strictly greater than the owner's
+	 * active generation. The returned replacement publishes with one reference
+	 * assignment that cannot refuse or call out, so a composition root can publish it
+	 * back-to-back with another domain's generation on the same stack.
+	 */
+	prepareRegistrationReplacement(
+		owner: MiddlewareRegistrationOwner,
+		generation: number,
+		registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	): PrepareRegistrationReplacementResult;
+	/** Prepare, check currentness, publish, then emit any conflict diagnostics. */
+	replaceRegistrations(
+		owner: MiddlewareRegistrationOwner,
+		generation: number,
+		registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	): ReplaceRegistrationsReport;
+	/** Active generation for an owner; 0 when nothing was ever applied. */
+	ownedGeneration(owner: MiddlewareRegistrationOwner): number;
 }

package/src/domains/middleware/extension.ts

@@ -6,6 +6,7 @@ import {
 	resolveHookBudgetTunablesFromEnv,
 } from "./budget.js";
 import type { MiddlewareContract } from "./contract.js";
+import { createMiddlewareRegistrationTable } from "./registrations.js";
 import { cloneMiddlewareRule, listMiddlewareRuleDefinitions } from "./rules.js";
 import {
 	type MiddlewareDiagnosticSink,
@@ -14,6 +15,7 @@ import {
 	registrationFromRuleDefinition,
 	runMiddlewareAsyncRegistrations,
 	runMiddlewareRegistrations,
+	writeMiddlewareDiagnosticToStderr,
 } from "./runtime.js";
 import { createMiddlewareSnapshot } from "./snapshot.js";
 
@@ -54,18 +56,28 @@ export interface MiddlewareBundleOptions {
 
 export function createMiddlewareBundle(options: MiddlewareBundleOptions = {}): DomainBundle<MiddlewareContract> {
 	const ruleDefinitions = combineRuleDefinitions(listMiddlewareRuleDefinitions(), options.ruleDefinitions ?? []);
-	const registrations = combineRegistrations(ruleDefinitions, options.registrations ?? []);
-	const registeredIds = new Set(registrations.map((registration) => registration.id));
 	let diagnosticSink = options.onDiagnostic;
+	// Declarative rules are the fixed tier; construction-time coded
+	// registrations are the first host entries, deduplicated first-wins across
+	// the shared id namespace exactly as before.
+	const table = createMiddlewareRegistrationTable({
+		fixed: ruleDefinitions.map(registrationFromRuleDefinition),
+		diagnosticSink: () => diagnosticSink ?? writeMiddlewareDiagnosticToStderr,
+	});
+	for (const registration of options.registrations ?? []) table.registerHook(registration);
 	const budgetTracker = options.budgetTracker ?? createEnvHookBudgetTracker();
 	const contract: MiddlewareContract = {
 		runHook(input) {
+			// Capture the list once; a replacement published mid-evaluation
+			// takes effect for the next evaluation, never this one.
+			const registrations = table.list();
 			return runMiddlewareRegistrations(input, registrations, {
 				budgetTracker,
 				...(diagnosticSink !== undefined ? { onDiagnostic: diagnosticSink } : {}),
 			});
 		},
 		runAsyncHook(input, priorEffects = []) {
+			const registrations = table.list();
 			return runMiddlewareAsyncRegistrations(input, registrations, priorEffects, {
 				...(diagnosticSink !== undefined ? { onDiagnostic: diagnosticSink } : {}),
 			});
@@ -77,13 +89,20 @@ export function createMiddlewareBundle(options: MiddlewareBundleOptions = {}): D
 			return createMiddlewareSnapshot(ruleDefinitions.map((definition) => definition.rule));
 		},
 		registerHook(registration) {
-			if (registeredIds.has(registration.id)) return;
-			registeredIds.add(registration.id);
-			registrations.push(registration);
+			table.registerHook(registration);
 		},
 		setDiagnosticSink(sink) {
 			diagnosticSink = sink;
 		},
+		prepareRegistrationReplacement(owner, generation, registrations) {
+			return table.prepareReplacement(owner, generation, registrations);
+		},
+		replaceRegistrations(owner, generation, registrations) {
+			return table.replaceRegistrations(owner, generation, registrations);
+		},
+		ownedGeneration(owner) {
+			return table.ownedGeneration(owner);
+		},
 	};
 	return {
 		extension: {
@@ -108,22 +127,3 @@ function combineRuleDefinitions(
 	}
 	return combined;
 }
-
-/**
- * One ordered evaluation list: declarative rules first (builtin, then
- * composition-root), then coded registrations, deduplicated across the shared
- * id namespace with the earlier entry winning.
- */
-function combineRegistrations(
-	ruleDefinitions: ReadonlyArray<MiddlewareRuleDefinition>,
-	coded: ReadonlyArray<MiddlewareHookRegistration>,
-): MiddlewareHookRegistration[] {
-	const seen = new Set<string>(ruleDefinitions.map((definition) => definition.rule.id));
-	const combined: MiddlewareHookRegistration[] = ruleDefinitions.map(registrationFromRuleDefinition);
-	for (const registration of coded) {
-		if (seen.has(registration.id)) continue;
-		seen.add(registration.id);
-		combined.push(registration);
-	}
-	return combined;
-}