@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/domains/extensions/types.ts

@@ -27,6 +27,19 @@ export interface ExtensionDiagnostic {
 	path?: string;
 }
 
+export interface ExtensionProvenance {
+	id: string;
+	scope: ExtensionScope;
+	/** Path recorded in install state, when known. */
+	sourcePath?: string;
+	/** Canonical filesystem identity of the installed package root. */
+	canonicalRoot: string;
+	/** SHA-256 of the manifest bytes covered by the installed-tree digest. */
+	manifestDigest: string;
+	/** Installed-tree digest recorded at install and reverified on this load. */
+	contentDigest: string;
+}
+
 export interface InstalledExtension {
 	id: string;
 	name: string;
@@ -36,14 +49,28 @@ export interface InstalledExtension {
 	rootPath: string;
 	manifestPath: string;
 	enabled: boolean;
+	/** Whether the complete manifest and declared resource tree are valid. */
+	valid: boolean;
 	/** Whether this package admits the running Clio version. */
 	compatible: boolean;
 	effective: boolean;
+	/** The single admission decision for extension-owned resources and hooks. */
+	loadable: boolean;
+	/** Present exactly when the installed tree and manifest bytes were reverified. */
+	provenance?: ExtensionProvenance;
+	/** Digest observed while checking installed content on this load. */
+	observedContentDigest?: string;
 	resources: ExtensionManifestResources;
 	overriddenBy?: ExtensionScope;
 	diagnostics: ExtensionDiagnostic[];
 }
 
+export type LoadableExtension = InstalledExtension & { loadable: true; provenance: ExtensionProvenance };
+
+export function isLoadableExtension(entry: InstalledExtension): entry is LoadableExtension {
+	return entry.loadable && entry.provenance !== undefined;
+}
+
 export interface ExtensionCandidate {
 	path: string;
 	manifestPath?: string;
@@ -58,8 +85,88 @@ export interface ExtensionResourceRoot {
 	path: string;
 	rootPath: string;
 	source: string;
+	provenance: ExtensionProvenance;
+	/** Zero denotes an ephemeral, uncommitted projection. */
+	generation: number;
+}
+
+export interface ExtensionHookSource {
+	provenance: ExtensionProvenance;
+	/** SHA-256 of the captured hooks.yaml bytes. */
+	declarationsDigest: string;
+	/** Parsed captured YAML, or an empty list when parsing failed. */
+	declarations: unknown;
+	parseError?: string;
 }
 
+export interface ExtensionSnapshotDiagnostics {
+	entries: ReadonlyArray<ExtensionDiagnostic & { extensionId?: string }>;
+	truncated: number;
+}
+
+export interface ExtensionSnapshot {
+	version: 1;
+	generation: number;
+	cwd: string;
+	builtAt: string;
+	/** Content identity; generation, timestamp, and diagnostic text are excluded. */
+	digest: string;
+	packages: ReadonlyArray<InstalledExtension>;
+	resourceRoots: Readonly<Record<ExtensionResourceKind, ReadonlyArray<ExtensionResourceRoot>>>;
+	hookSources: ReadonlyArray<ExtensionHookSource>;
+	diagnostics: ExtensionSnapshotDiagnostics;
+}
+
+export type ExtensionReloadRejectionReason = "build-failed" | "reentrant" | "stale" | "workspace-changed";
+
+export interface ExtensionReloadRejection {
+	status: "rejected";
+	reason: ExtensionReloadRejectionReason;
+	/** Generation that remains committed. */
+	generation: number;
+	diagnostics: ExtensionSnapshotDiagnostics;
+}
+
+/**
+ * A fully built and validated generation that has not been published. The
+ * bundle holds at most one candidate at a time. `publish` is one reference
+ * assignment that never validates, refuses, throws, or calls out; the caller
+ * checks `current()` on the same stack immediately before it. `discard`
+ * releases the candidate without any visible change.
+ */
+export interface ExtensionReloadCandidate {
+	generation: number;
+	previousGeneration: number;
+	snapshot: ExtensionSnapshot;
+	/** False when the candidate digest equals the committed digest. */
+	changed: boolean;
+	added: ReadonlyArray<string>;
+	removed: ReadonlyArray<string>;
+	modified: ReadonlyArray<string>;
+	/** True while this is the in-flight candidate and the committed snapshot it was diffed against is still live. */
+	current(): boolean;
+	publish(): void;
+	discard(): void;
+}
+
+export type ExtensionReloadPrepareResult =
+	| { status: "prepared"; candidate: ExtensionReloadCandidate }
+	| ExtensionReloadRejection;
+
+export interface ExtensionReloadCommitted {
+	status: "committed";
+	generation: number;
+	previousGeneration: number;
+	changed: boolean;
+	digest: string;
+	added: ReadonlyArray<string>;
+	removed: ReadonlyArray<string>;
+	modified: ReadonlyArray<string>;
+	diagnostics: ExtensionSnapshotDiagnostics;
+}
+
+export type ExtensionReloadResult = ExtensionReloadCommitted | ExtensionReloadRejection;
+
 export interface ExtensionListOptions {
 	scope?: ExtensionScope;
 	cwd?: string;
@@ -72,17 +179,27 @@ export interface ExtensionInstallOptions extends ExtensionListOptions {
 
 export interface ExtensionInstallResult {
 	extension?: InstalledExtension;
+	recovery?: { stateBackup?: string; packageBackup?: string };
 	diagnostics: ExtensionDiagnostic[];
 }
 
 export interface ExtensionMutationResult {
 	extension?: InstalledExtension;
 	removed?: { id: string; scope: ExtensionScope; path: string };
+	recovery?: { stateBackup?: string; packageBackup?: string };
 	diagnostics: ExtensionDiagnostic[];
 }
 
+export interface ExtensionStateUpgradeReport {
+	scope: ExtensionScope;
+	statePath: string;
+	backupPath?: string;
+	upgraded: string[];
+	refused: Array<{ id: string; reason: string }>;
+}
+
 export interface ExtensionState {
 	version: 1;
 	disabled: string[];
-	installed: Record<string, { installedAt: string; source?: string }>;
+	installed: Record<string, { installedAt: string; source?: string; contentDigest?: string }>;
 }

package/src/domains/interop/registry.ts

@@ -94,8 +94,10 @@ export const INTEROP_AGENT_KINDS: ReadonlyArray<InteropAgentKind> = [
 		id: "antigravity",
 		label: "Antigravity CLI",
 		binaryNames: ["agy"],
-		userDir: ".antigravitycli",
-		projectDir: ".antigravitycli",
+		userDir: ".gemini/antigravity-cli",
+		legacyUserDirs: [".antigravitycli"],
+		projectDir: ".gemini/antigravity-cli",
+		legacyProjectDirs: [".antigravitycli"],
 		instructionFiles: [],
 	},
 	{
@@ -133,7 +135,9 @@ export function foreignAgentDirs(): ReadonlyArray<string> {
 	const dirs: string[] = [];
 	for (const kind of INTEROP_AGENT_KINDS) {
 		dirs.push(`~/${kind.userDir}/`);
+		for (const legacy of kind.legacyUserDirs ?? []) dirs.push(`~/${legacy}/`);
 		if (kind.projectDir !== undefined) dirs.push(`${kind.projectDir}/`);
+		for (const legacy of kind.legacyProjectDirs ?? []) dirs.push(`${legacy}/`);
 	}
 	return [...new Set(dirs)];
 }

package/src/domains/interop/types.ts

@@ -33,8 +33,12 @@ export interface InteropAgentKind {
 	binaryNames: ReadonlyArray<string>;
 	/** Home-relative directory the agent owns. */
 	userDir: string;
+	/** Older home-relative roots still owned by supported installations. */
+	legacyUserDirs?: ReadonlyArray<string>;
 	/** Project-relative directory the agent owns, when it has one distinct from the repo's own. */
 	projectDir?: string;
+	/** Older project-relative roots still protected from Clio writes. */
+	legacyProjectDirs?: ReadonlyArray<string>;
 	userSkillRoot?: string;
 	projectSkillRoot?: string;
 	userPromptRoot?: string;

package/src/domains/lifecycle/migrations/2026-09-01-extension-install-digests.ts

@@ -0,0 +1,27 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../../core/safe-resource-write.js";
+import { upgradeLegacyExtensionInstallState } from "../../extensions/state.js";
+import type { Migration } from "./index.js";
+
+export const EXTENSION_INSTALL_DIGESTS_MIGRATION_ID = "2026-09-01-extension-install-digests";
+
+function migrateExtensionInstallDigests(stateDir: string, cwd = process.cwd()): void {
+	const scopes = upgradeLegacyExtensionInstallState(cwd);
+	const reportDir = join(stateDir, "migration-reports");
+	mkdirSync(reportDir, { recursive: true });
+	safeResourceWrite(
+		join(reportDir, `${EXTENSION_INSTALL_DIGESTS_MIGRATION_ID}.json`),
+		`${JSON.stringify({ migration: EXTENSION_INSTALL_DIGESTS_MIGRATION_ID, scopes }, null, 2)}\n`,
+		{ encoding: "utf8", mode: 0o644 },
+	);
+}
+
+const migration: Migration = {
+	id: EXTENSION_INSTALL_DIGESTS_MIGRATION_ID,
+	async up(stateDir: string): Promise<void> {
+		migrateExtensionInstallDigests(stateDir);
+	},
+};
+
+export default migration;

package/src/domains/lifecycle/migrations/index.ts

@@ -34,6 +34,7 @@ import { join } from "node:path";
 
 import lmStudioRuntimeId from "./2026-08-18-lmstudio-runtime-id.js";
 import clioCoderNaming from "./2026-09-01-clio-coder-naming.js";
+import extensionInstallDigests from "./2026-09-01-extension-install-digests.js";
 import retirePanesKnobs from "./2026-09-01-retire-panes-knobs.js";
 import settingsV2 from "./2026-09-01-settings-v2.js";
 
@@ -61,6 +62,7 @@ export interface MigrationRunResult {
 // migration independently and for manifest continuity; it is a no-op on v2.
 const REGISTRY: ReadonlyArray<Migration> = Object.freeze([
 	settingsV2,
+	extensionInstallDigests,
 	clioCoderNaming,
 	retirePanesKnobs,
 	lmStudioRuntimeId,
@@ -70,6 +72,10 @@ export function listMigrations(): ReadonlyArray<Migration> {
 	return REGISTRY;
 }
 
+export function readMigrationManifest(stateDir: string): MigrationManifest {
+	return readManifest(manifestPath(stateDir));
+}
+
 function manifestPath(stateDir: string): string {
 	return join(stateDir, "migrations.json");
 }

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

@@ -9,12 +9,14 @@ import {
 	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 = [
@@ -35,6 +37,8 @@ export interface NamingResourceReport {
 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;
 }
@@ -206,14 +210,25 @@ function collectSkillFiles(root: string, current = root): string[] {
 	return out;
 }
 
-/** Read-only inventory of released skill metadata keys in selected Clio Coder roots. */
+/**
+ * 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"> = {},
+	options: Pick<NamingResourceOptions, "cwd" | "configDir" | "home"> = {},
 ): SkillMetadataNamingInspection[] {
 	const cwd = options.cwd ?? process.cwd();
 	const configDir = options.configDir ?? resolveClioDirs().config;
-	const roots = [path.join(configDir, "skills"), path.join(cwd, ".clio-coder", "skills")];
-	return roots.flatMap((root) =>
+	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")),

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

@@ -54,10 +54,14 @@ export function regenerateYaziNamingProfile(options: YaziNamingOptions = {}): Ya
 	const cacheDir = options.cacheDir ?? resolveClioDirs().cache;
 	const before = inspectYaziNaming(cacheDir);
 	if (!before.present) {
-		return { ...before, status: "absent", detail: "managed Yazi profile is absent; next open writes canonical names" };
+		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 Yazi profile already uses canonical names" };
+		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;
@@ -66,7 +70,8 @@ export function regenerateYaziNamingProfile(options: YaziNamingOptions = {}): Ya
 		return {
 			...before,
 			status: "removed-unresolved",
-			detail: "legacy managed profile removed; Yazi/ya is unresolved, so the next managed open will regenerate it",
+			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 });
@@ -74,8 +79,8 @@ export function regenerateYaziNamingProfile(options: YaziNamingOptions = {}): Ya
 		return {
 			...before,
 			status: "regeneration-failed",
-			detail: "legacy managed profile removed, but current Yazi rejected the regenerated profile",
+			detail: "legacy managed profile removed, but the files pane engine rejected the regenerated profile",
 		};
 	}
-	return { ...before, status: "regenerated", detail: "managed Yazi profile regenerated with canonical names" };
+	return { ...before, status: "regenerated", detail: "managed files pane profile regenerated with canonical names" };
 }

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

@@ -29,11 +29,16 @@ export interface TaskMemoryTrajectoryStep {
 	resultDigestProvenance: ToolResultDigestProvenance;
 }
 
+/** Admission changed while a client prepared; no inference request was sent. */
+export class TaskMemoryEndpointBusyError extends Error {}
+
 export interface TaskMemoryModelRequest {
 	systemPrompt: string;
 	userPrompt: string;
 	maxTokens: number;
 	signal: AbortSignal;
+	/** Known usage may arrive even when completion rejects or the policy has been canceled. */
+	onUsage?: (usage: TaskMemoryStepUsage) => void;
 }
 
 /**
@@ -116,10 +121,8 @@ export type TaskMemoryPolicyReason =
 	 */
 	| "timed_out"
 	/**
-	 * The step would have run on the endpoint the chat target is streaming
-	 * against, so it never started. A single-slot local server queues the memory
-	 * call behind the operator's own turn, or evicts the resident model to serve
-	 * it; neither is a cost a background step may impose.
+	 * Known occupancy exhausts the endpoint request capacity, so no step starts.
+	 * A shared gateway URL alone does not establish a one-slot capacity bound.
 	 */
 	| "endpoint_busy"
 	/** The model client threw: unreachable route, auth failure, malformed request. */
@@ -139,7 +142,9 @@ export type TaskMemoryPolicyReason =
 	/** Rules tier: the turn ended with no repeated failure worth reporting. */
 	| "no_repeated_failure"
 	/** Rules tier: compaction reactivation found no knowledge entries to restore. */
-	| "bank_empty";
+	| "bank_empty"
+	/** The owning session/branch generation was invalidated. */
+	| "scope_changed";
 
 /**
  * The model's own words for one step, handed to an observer before they are
@@ -161,6 +166,12 @@ export interface TaskMemoryEnvelope {
 }
 
 export interface TaskMemoryPolicyInput {
+	/** Content authority, checked after inference and before any bank write. */
+	isCurrent?: () => boolean;
+	/** Cancellation releases policy bookkeeping even if the transport ignores abort. */
+	signal?: AbortSignal;
+	/** Reports actual provider usage, including responses arriving after cancellation/deadline. */
+	onStepUsage?: (usage: TaskMemoryStepUsage) => void;
 	task: string;
 	trajectory: ReadonlyArray<TaskMemoryTrajectoryStep>;
 	deterministicTrigger: boolean;
@@ -246,10 +257,31 @@ export async function runTaskMemoryPolicy(
 	const timeoutMs = positiveInteger(input.timeoutMs, TASK_MEMORY_POLICY_DEFAULT_TIMEOUT_MS);
 	const timeoutMarker = Symbol("task-memory-timeout");
 	let timer: NodeJS.Timeout | undefined;
+	const cancelledMarker = Symbol("task-memory-cancelled");
+	let cancel: () => void = () => {};
+	const cancelled = new Promise<typeof cancelledMarker>((resolve) => {
+		cancel = () => {
+			controller.abort();
+			resolve(cancelledMarker);
+		};
+	});
+	input.signal?.addEventListener("abort", cancel, { once: true });
+	if (input.signal?.aborted) cancel();
 	let userPrompt = "";
 	let rawResponse = "";
 	let clientError: string | null = null;
 	let stepUsage: TaskMemoryStepUsage | null = null;
+	let usageReported = false;
+	const reportUsage = (usage: TaskMemoryStepUsage): void => {
+		if (usageReported) return;
+		usageReported = true;
+		stepUsage = usage;
+		try {
+			input.onStepUsage?.(usage);
+		} catch {
+			/* Accounting cannot steer content. */
+		}
+	};
 	// Every exit reports through here so the trace sees the same envelope the
 	// telemetry row summarizes, including the paths that used to throw away both.
 	const settle = (
@@ -263,54 +295,64 @@ export async function runTaskMemoryPolicy(
 			bankOperations: parts.bankOperations ?? 0,
 			droppedOperations: parts.droppedOperations ?? 0,
 			reminder: parts.reminder ?? null,
-			inputTokens: parts.inputTokens ?? 0,
-			outputTokens: parts.outputTokens ?? 0,
+			inputTokens: parts.inputTokens ?? stepUsage?.input ?? 0,
+			outputTokens: parts.outputTokens ?? stepUsage?.output ?? 0,
 			usage: stepUsage,
 		};
 		try {
-			input.onEnvelope?.({
-				systemPrompt: MEMORY_INTERVENTION_SYSTEM_PROMPT,
-				userPrompt,
-				response: rawResponse,
-				decision,
-				reason,
-				bankOperations: result.bankOperations,
-				droppedOperations: result.droppedOperations,
-				reminder: result.reminder,
-				error: clientError,
-			});
+			if (input.isCurrent?.() !== false)
+				input.onEnvelope?.({
+					systemPrompt: MEMORY_INTERVENTION_SYSTEM_PROMPT,
+					userPrompt,
+					response: rawResponse,
+					decision,
+					reason,
+					bankOperations: result.bankOperations,
+					droppedOperations: result.droppedOperations,
+					reminder: result.reminder,
+					error: clientError,
+				});
 		} catch {
 			// A failing observer is an operator's diagnostic, never the policy's problem.
 		}
 		return result;
 	};
 	try {
+		if (input.signal?.aborted || input.isCurrent?.() === false) return settle("silent", "scope_changed");
 		userPrompt = buildMemoryInterventionUserPrompt({
 			task: input.task.slice(0, TASK_PROMPT_MAX_CHARS),
 			bank: bank.render(input.maxTokens),
 			trajectory: renderTrajectory(input.trajectory),
 		});
-		const completion = client.complete({
-			systemPrompt: MEMORY_INTERVENTION_SYSTEM_PROMPT,
-			userPrompt,
-			maxTokens: positiveInteger(input.modelMaxTokens, input.maxTokens),
-			signal: controller.signal,
-		});
+		const completion = client
+			.complete({
+				systemPrompt: MEMORY_INTERVENTION_SYSTEM_PROMPT,
+				userPrompt,
+				maxTokens: positiveInteger(input.modelMaxTokens, input.maxTokens),
+				signal: controller.signal,
+				onUsage: reportUsage,
+			})
+			.then((response) => {
+				if (response.usage !== undefined) reportUsage(response.usage);
+				return response;
+			});
 		const timeout = new Promise<typeof timeoutMarker>((resolve) => {
 			timer = setTimeout(() => resolve(timeoutMarker), timeoutMs);
 		});
-		const response = await Promise.race([completion, timeout]);
+		const response = await Promise.race([completion, timeout, cancelled]);
+		if (response === cancelledMarker) return settle("silent", "scope_changed");
 		if (response === timeoutMarker) {
 			controller.abort();
 			void completion.catch(() => undefined);
 			return settle("timeout", "deadline");
 		}
 		rawResponse = typeof response.text === "string" ? response.text : "";
-		stepUsage = response.usage ?? null;
+		stepUsage = response.usage ?? stepUsage;
 		const usage = {
 			inputTokens: nonNegativeInteger(response.inputTokens ?? stepUsage?.input),
 			outputTokens: nonNegativeInteger(response.outputTokens ?? stepUsage?.output),
 		};
+		if (input.signal?.aborted || input.isCurrent?.() === false) return settle("silent", "scope_changed", usage);
 		const read = readPolicyStep(rawResponse);
 		if (!read.ok) return settle("malformed", read.reason, { ...usage, droppedOperations: read.dropped });
 		const operations = resolveOperations(bank, read.step.operations);
@@ -336,6 +378,7 @@ export async function runTaskMemoryPolicy(
 		bank.recordInjection(citedIds);
 		return settle("injected", "intervened", { ...counts, reminder });
 	} catch (error) {
+		if (error instanceof TaskMemoryEndpointBusyError) return settle("silent", "endpoint_busy");
 		clientError = errorMessage(error);
 		// A transport that aborted at its own deadline spent the whole budget and
 		// produced nothing. Reporting it as silence made a step that held a local
@@ -345,6 +388,7 @@ export async function runTaskMemoryPolicy(
 		return settle("silent", "client_error");
 	} finally {
 		if (timer !== undefined) clearTimeout(timer);
+		input.signal?.removeEventListener("abort", cancel);
 	}
 }
 

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

@@ -229,6 +229,7 @@ const REASONS = new Set<TaskMemoryPolicyReason>([
 	"llm_timeout_backoff",
 	"no_repeated_failure",
 	"bank_empty",
+	"scope_changed",
 ]);
 
 function entryDelta(

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;
-}