@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/domains/middleware/memory-intervention.ts

@@ -78,13 +78,13 @@ export interface MemoryInterventionDeps {
 	everyNTools?: number;
 	/** Lazily resolves the explicitly configured background role. Null means rules-only. */
 	getModelClient?: () => TaskMemoryModelClient | null;
+	/** One alternative route after a client error; never used after timeout, cancellation or model output. */
+	getFallbackModelClient?: () => TaskMemoryModelClient | null;
 	/** Completion budget derived from the resolved background model capability. */
 	getModelMaxTokens?: (configuredMaxTokens: number) => number;
 	/**
-	 * True when the background target's inference endpoint is already serving the
-	 * chat target's stream. A memory step then either queues behind the operator's
-	 * own turn on a single-slot server or makes the server evict the resident
-	 * model to serve it, so the boundary is skipped and the skip is recorded.
+	 * True when known endpoint occupancy exhausts the resolved capacity bound.
+	 * A shared gateway URL alone is not evidence that its request slots are full.
 	 */
 	backgroundEndpointBusy?: () => boolean;
 	/**
@@ -92,6 +92,8 @@ export interface MemoryInterventionDeps {
 	 * routes it to the cost ledger; the middleware never prices anything.
 	 */
 	onStepUsage?: (usage: TaskMemoryStepUsage) => void;
+	/** Capture immutable accounting ownership at launch, before awaiting inference. */
+	captureStepUsage?: () => (usage: TaskMemoryStepUsage, isCurrent: boolean) => void;
 	/**
 	 * Bank entries an llm-tier reminder cited when it reached the operator. The
 	 * composition root proposes them into the durable memory store, which is what
@@ -139,6 +141,10 @@ export interface MemoryPromptedStepResult extends TaskMemoryPolicyResult {
 }
 
 export interface MemoryInterventionRegistration extends MiddlewareHookRegistration {
+	/** Invalidate pending content and discard all transient session/branch state. */
+	reset(): void;
+	/** Invalidate immediately without waiting for the model; refuse further work. */
+	dispose(): void;
 	evaluateAsync(
 		input: MiddlewareHookInput,
 		context?: MiddlewareHookEvaluationContext,
@@ -154,10 +160,9 @@ export interface MemoryInterventionRegistration extends MiddlewareHookRegistrati
 	/** True while a detached background memory step is still running. */
 	stepInFlight(): boolean;
 	/**
-	 * Resolves once no detached memory step is outstanding. Teardown does not
-	 * await it: a step runs tens of seconds on a local route and shutdown cannot
-	 * wait that long, which is why a surface with no next turn declines to start
-	 * one at all rather than starting one it will abandon.
+	 * Resolves when this generation's detached policy settles. Reset/shutdown
+	 * release the policy immediately; an abort-ignoring transport can still
+	 * finish later, with authority only to report its originating usage.
 	 */
 	whenIdle(): Promise<void>;
 }
@@ -167,6 +172,10 @@ export interface MemoryInterventionRegistration extends MiddlewareHookRegistrati
  * emits only cited, advisory reminders through the existing visible channel.
  */
 export function createMemoryInterventionRegistration(deps: MemoryInterventionDeps): MemoryInterventionRegistration {
+	let generation = 0;
+	let generationController = new AbortController();
+	let observedSessionId: string | undefined;
+	let disposed = false;
 	const pending = new Map<string, PendingToolStep>();
 	const trajectory: TrajectoryStep[] = [];
 	const failures = new Map<string, FailedAttempt>();
@@ -194,11 +203,17 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 	let consecutiveLlmTimeouts = 0;
 
 	return {
+		reset,
+		dispose(): void {
+			disposed = true;
+			reset();
+		},
 		id: MEMORY_INTERVENTION_REGISTRATION_ID,
 		description: "maintain bounded task execution memory and selectively remind after repeated failures or compaction",
 		hooks: ["before_tool", "after_tool", "turn_start", "turn_end", "on_compaction"],
 		evaluate(input): ReadonlyArray<MiddlewareEffect> {
-			if (!settings().enabled) return NO_EFFECTS;
+			observeSession(input);
+			if (disposed || !settings().enabled) return NO_EFFECTS;
 			try {
 				switch (input.hook) {
 					case "before_tool":
@@ -274,7 +289,8 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		 * would have been buffered anyway.
 		 */
 		async evaluateAsync(input, context): Promise<ReadonlyArray<MiddlewareEffect>> {
-			if (!settings().enabled || input.hook !== "turn_end" || pendingTriggers.size === 0) return NO_EFFECTS;
+			observeSession(input);
+			if (disposed || !settings().enabled || input.hook !== "turn_end" || pendingTriggers.size === 0) return NO_EFFECTS;
 			const boundary = input.turnId ?? input.metadata?.userTurnId?.toString() ?? `tool-step:${toolStep}`;
 			if (boundary === lastPromptedBoundary) return NO_EFFECTS;
 			// One row rather than none, so a headless operator reading the log sees
@@ -316,6 +332,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 				) ??
 					false);
 			rulesInjectedSincePromptedStep = false;
+			const stepGeneration = generation;
 			promptedStepInFlight = true;
 			outstandingStep = runPromptedStep({
 				deterministicTrigger: triggers.some((trigger) => trigger !== "interval"),
@@ -323,6 +340,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 				triggerReasons: triggers,
 			})
 				.then((result) => {
+					if (stepGeneration !== generation || disposed) return;
 					// A rules-only reminder can win the visible boundary while the optional
 					// background route resolves to null. Preserve the operator-visible
 					// injected outcome instead of overwriting it with that no-client silence.
@@ -336,13 +354,13 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 					// covers a throwing delivery sink, which must not surface anywhere.
 				})
 				.finally(() => {
-					promptedStepInFlight = false;
+					if (stepGeneration === generation) promptedStepInFlight = false;
 				});
 			return NO_EFFECTS;
 		},
 		runPromptedStep,
 		signalLoop(): void {
-			if (settings().enabled) pendingTriggers.add("loop_signal");
+			if (!disposed && settings().enabled) pendingTriggers.add("loop_signal");
 		},
 		lastDecision: () => lastDecision,
 		recentActivity: () => [...activity],
@@ -350,6 +368,43 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 		whenIdle: () => outstandingStep,
 	};
 
+	function observeSession(input: MiddlewareHookInput): void {
+		if (input.sessionId === undefined) return;
+		if (observedSessionId !== undefined && observedSessionId !== input.sessionId) reset();
+		observedSessionId = input.sessionId;
+	}
+
+	function reset(): void {
+		generation += 1;
+		generationController.abort();
+		generationController = new AbortController();
+		deps.bank.clear();
+		pending.clear();
+		trajectory.length = 0;
+		failures.clear();
+		toolStep = 0;
+		lastTurnEndStep = 0;
+		reactivateAfterCompaction = false;
+		lastInjectedOperationFingerprint = null;
+		currentTask = "(current task unavailable)";
+		toolsSinceMemoryStep = 0;
+		consecutiveErrors = 0;
+		lastPromptedBoundary = null;
+		lastInjectedMessage = null;
+		lastDecision = null;
+		pendingTriggers.clear();
+		activity.length = 0;
+		annotatedThisTurn.clear();
+		telemetryBankSnapshot = deps.bank.snapshot();
+		promptedStepInFlight = false;
+		promptedStepTier = "rules";
+		outstandingStep = Promise.resolve();
+		rulesInjectedSincePromptedStep = false;
+		annotatedSinceTurnEnd = false;
+		consecutiveLlmTimeouts = 0;
+		observedSessionId = undefined;
+	}
+
 	function settings(): MemoryInterventionSettings {
 		const live = deps.getSettings?.();
 		return {
@@ -377,12 +432,16 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 			effects: NO_EFFECTS,
 		});
 		const live = settings();
-		if (!live.enabled) {
+		const stepGeneration = generation;
+		const isCurrent = () => !disposed && stepGeneration === generation;
+		const usageSink = deps.captureStepUsage?.();
+		if (disposed || !live.enabled) {
 			const result = silent("no_client");
 			lastDecision = result.decision;
 			return result;
 		}
 		const started = process.hrtime.bigint();
+		let attemptStarted = started;
 		const triggers = input.triggerReasons?.length ? input.triggerReasons : ["manual" as const];
 		let tier: TaskMemoryTelemetryTier = "rules";
 		promptedStepTier = tier;
@@ -407,17 +466,58 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 				} else {
 					tier = "llm";
 					promptedStepTier = tier;
-					promptedResult = await runTaskMemoryPolicy(deps.bank, client, {
-						task: input.task?.trim() || currentTask,
-						trajectory: [...trajectory],
-						deterministicTrigger: input.deterministicTrigger,
-						maxTokens: live.maxTokens,
-						modelMaxTokens: positiveInteger(deps.getModelMaxTokens?.(live.maxTokens), live.maxTokens),
-						...(input.suppressIntervention === undefined ? {} : { suppressIntervention: input.suppressIntervention }),
-						previousReminder: lastInjectedMessage,
-						timeoutMs: live.timeoutMs,
-						...(deps.onEnvelope === undefined ? {} : { onEnvelope: deps.onEnvelope }),
-					});
+					const runClient = (selected: TaskMemoryModelClient, timeoutMs: number) =>
+						runTaskMemoryPolicy(deps.bank, selected, {
+							isCurrent,
+							signal: generationController.signal,
+							onStepUsage: (usage) => {
+								if (usageSink) usageSink(usage, isCurrent());
+								else deps.onStepUsage?.(usage);
+							},
+							task: input.task?.trim() || currentTask,
+							trajectory: [...trajectory],
+							deterministicTrigger: input.deterministicTrigger,
+							maxTokens: live.maxTokens,
+							modelMaxTokens: positiveInteger(deps.getModelMaxTokens?.(live.maxTokens), live.maxTokens),
+							...(input.suppressIntervention === undefined ? {} : { suppressIntervention: input.suppressIntervention }),
+							previousReminder: lastInjectedMessage,
+							timeoutMs,
+							...(deps.onEnvelope === undefined ? {} : { onEnvelope: deps.onEnvelope }),
+						});
+					const remainingMs = () => Math.floor(live.timeoutMs - Number(process.hrtime.bigint() - started) / 1_000_000);
+					const initialTimeoutMs = remainingMs();
+					promptedResult =
+						initialTimeoutMs <= 0
+							? { ...silent("deadline"), decision: "timeout" }
+							: await runClient(client, initialTimeoutMs);
+					if (promptedResult.reason === "client_error" && isCurrent() && remainingMs() > 0) {
+						let fallback: TaskMemoryModelClient | null = null;
+						let fallbackReady = false;
+						try {
+							fallback = deps.getFallbackModelClient?.() ?? null;
+							fallbackReady = fallback !== null && deps.backgroundEndpointBusy?.() !== true;
+						} catch {
+							/* Fail closed and preserve the original call if routing or capacity is unreadable. */
+						}
+						const fallbackTimeoutMs = remainingMs();
+						if (fallback !== null && fallbackReady && isCurrent() && fallbackTimeoutMs > 0) {
+							// Each attempted call keeps its own telemetry and origin usage.
+							// The returned policy result describes the final attempt only.
+							emitTelemetry(
+								triggers,
+								tier,
+								promptedResult.decision,
+								promptedResult.reason,
+								0,
+								promptedResult.inputTokens,
+								promptedResult.outputTokens,
+								started,
+								{ bankOperations: promptedResult.bankOperations, droppedOperations: promptedResult.droppedOperations },
+							);
+							attemptStarted = process.hrtime.bigint();
+							promptedResult = await runClient(fallback, fallbackTimeoutMs);
+						}
+					}
 				}
 			}
 		} catch (error) {
@@ -436,16 +536,11 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 				error: error instanceof Error ? error.message : "resolving the background model client failed",
 			});
 		}
+		if (!isCurrent()) return { ...promptedResult, reminder: null, effects: NO_EFFECTS };
+		if (promptedResult.reason === "endpoint_busy") telemetryDecision = "dropped";
 		if (tier === "llm" && promptedResult.decision === "timeout") consecutiveLlmTimeouts += 1;
 		else if (tier === "llm" && telemetryDecision !== "dropped") consecutiveLlmTimeouts = 0;
 		lastDecision = promptedResult.decision;
-		if (promptedResult.usage !== null) {
-			try {
-				deps.onStepUsage?.(promptedResult.usage);
-			} catch {
-				// Accounting is bookkeeping. A failing sink never changes memory behavior.
-			}
-		}
 		if (promptedResult.decision === "injected") reportInjectedEntries(promptedResult.reminder);
 		emitTelemetry(
 			triggers,
@@ -455,7 +550,7 @@ export function createMemoryInterventionRegistration(deps: MemoryInterventionDep
 			citedEntryCount(promptedResult.reminder),
 			promptedResult.inputTokens,
 			promptedResult.outputTokens,
-			started,
+			attemptStarted,
 			{ bankOperations: promptedResult.bankOperations, droppedOperations: promptedResult.droppedOperations },
 		);
 		return {

package/src/domains/middleware/memory-step-endpoint.ts

@@ -50,8 +50,9 @@ export function announceMemoryStepEndpoint<Request, Response>(
 	const { bus, endpointKey, targetId } = deps;
 	if (endpointKey === null) return complete;
 	return async (request: Request): Promise<Response> => {
-		// `runPromptedStep` performs its busy check before it invokes `complete`,
-		// so this registration counts the outgoing request without self-refusing.
+		// The production client rechecks capacity after asynchronous preparation,
+		// immediately before calling this wrapper. Register synchronously so no
+		// local foreground launch can interleave between that check and this hold.
 		const releaseEndpointSlot = registerForegroundStream(endpointKey);
 		try {
 			return await complete(request);

package/src/domains/middleware/registrations.ts

@@ -0,0 +1,326 @@
+/**
+ * Ordered, copy-on-write registration table behind a middleware contract.
+ *
+ * Three tiers share one id namespace and one evaluation list:
+ *
+ *   - fixed: declarative rules (builtin plus composition-root definitions),
+ *     immutable for the life of the contract and always evaluated first;
+ *   - host: coded registrations appended by the composition root through
+ *     registerHook, append-only, first id wins;
+ *   - owned: registration sets replaced as one unit by an owner under a
+ *     strictly increasing generation. Today the only owner is "user-hooks".
+ *
+ * The whole table is one immutable state object held behind a single
+ * reference. Every writer computes a complete next state and publishes it
+ * with one assignment; readers capture the reference once per evaluation, so
+ * an evaluation that started before a publish finishes against the state it
+ * started with, including across an await. Preparation never runs user code:
+ * conflicts are returned as frozen data and a caller emits them through the
+ * diagnostic sink only after publication.
+ */
+
+import type { MiddlewareDiagnostic, MiddlewareDiagnosticSink, MiddlewareHookRegistration } from "./runtime.js";
+
+export const MIDDLEWARE_REGISTRATION_OWNERS = ["user-hooks"] as const;
+
+export type MiddlewareRegistrationOwner = (typeof MIDDLEWARE_REGISTRATION_OWNERS)[number];
+
+export type MiddlewareRegistrationConflictTier = "builtin" | "host" | "owned";
+
+export interface MiddlewareRegistrationConflict {
+	id: string;
+	conflictsWith: MiddlewareRegistrationConflictTier;
+}
+
+export type ReplaceRegistrationsRejection = "stale" | "unknown-owner";
+
+export type RegistrationConflictDiagnostic = Extract<MiddlewareDiagnostic, { kind: "registration_conflict" }>;
+
+export interface ReplaceRegistrationsReport {
+	applied: boolean;
+	owner: MiddlewareRegistrationOwner;
+	/** Generation active for the owner after the call. */
+	activeGeneration: number;
+	reason?: ReplaceRegistrationsRejection;
+	/** Offered registrations dropped for colliding with a builtin, host, or earlier owned id. */
+	dropped: ReadonlyArray<MiddlewareRegistrationConflict>;
+	/**
+	 * Remove this generation's registrations if the owner still holds it. A
+	 * disposer for a superseded generation is a no-op, so a late disposal can
+	 * never remove a newer generation's registrations.
+	 */
+	dispose(): void;
+}
+
+/**
+ * A validated replacement whose complete next table state is already built.
+ * `publish` is one reference assignment: it does not validate, refuse,
+ * throw, or call out. The caller checks `current()` on the same stack
+ * immediately before publishing, then emits `conflicts` afterwards.
+ */
+export interface MiddlewareRegistrationReplacement {
+	owner: MiddlewareRegistrationOwner;
+	generation: number;
+	dropped: ReadonlyArray<MiddlewareRegistrationConflict>;
+	/** Diagnostics for `dropped`, as data. Nothing was emitted during preparation. */
+	conflicts: ReadonlyArray<RegistrationConflictDiagnostic>;
+	/** Registrations that will be active for the owner after publish. */
+	size: number;
+	/** True while the table state this replacement was prepared against is still the live one. */
+	current(): boolean;
+	/** Assignment-only publication of the prepared state. */
+	publish(): void;
+	/** Send `conflicts` to the diagnostic sink. Call only after publication. */
+	emitConflicts(): void;
+	/** Remove this generation's registrations if the owner still holds it. */
+	dispose(): void;
+	discard(): void;
+}
+
+export type PrepareRegistrationReplacementResult =
+	| { status: "prepared"; replacement: MiddlewareRegistrationReplacement }
+	| {
+			status: "rejected";
+			owner: MiddlewareRegistrationOwner;
+			reason: ReplaceRegistrationsRejection;
+			activeGeneration: number;
+	  };
+
+export interface MiddlewareRegistrationTable {
+	/** The current frozen evaluation list. Capture once per evaluation. */
+	list(): ReadonlyArray<MiddlewareHookRegistration>;
+	registerHook(registration: MiddlewareHookRegistration): void;
+	prepareReplacement(
+		owner: MiddlewareRegistrationOwner,
+		generation: number,
+		registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	): PrepareRegistrationReplacementResult;
+	replaceRegistrations(
+		owner: MiddlewareRegistrationOwner,
+		generation: number,
+		registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	): ReplaceRegistrationsReport;
+	ownedGeneration(owner: MiddlewareRegistrationOwner): number;
+}
+
+interface OwnerSlot {
+	generation: number;
+	registrations: ReadonlyArray<MiddlewareHookRegistration>;
+	/** Host index the slot sits before; fixed at the owner's first replacement. */
+	anchor: number;
+}
+
+/** One immutable table state. Replaced wholesale, never mutated. */
+interface TableState {
+	host: ReadonlyArray<MiddlewareHookRegistration>;
+	hostIds: ReadonlySet<string>;
+	slots: ReadonlyMap<MiddlewareRegistrationOwner, OwnerSlot>;
+	list: ReadonlyArray<MiddlewareHookRegistration>;
+}
+
+export interface MiddlewareRegistrationTableOptions {
+	fixed: ReadonlyArray<MiddlewareHookRegistration>;
+	/** Resolved per emission so the composition root can swap the sink later. */
+	diagnosticSink: () => MiddlewareDiagnosticSink;
+}
+
+function isRegistrationOwner(value: string): value is MiddlewareRegistrationOwner {
+	return (MIDDLEWARE_REGISTRATION_OWNERS as ReadonlyArray<string>).includes(value);
+}
+
+export function createMiddlewareRegistrationTable(
+	options: MiddlewareRegistrationTableOptions,
+): MiddlewareRegistrationTable {
+	const fixed = Object.freeze([...options.fixed]);
+	const fixedIds = new Set(fixed.map((registration) => registration.id));
+
+	const buildList = (
+		host: ReadonlyArray<MiddlewareHookRegistration>,
+		slots: ReadonlyMap<MiddlewareRegistrationOwner, OwnerSlot>,
+	): ReadonlyArray<MiddlewareHookRegistration> => {
+		const list: MiddlewareHookRegistration[] = [...fixed];
+		const slotAt = (index: number): void => {
+			for (const owner of MIDDLEWARE_REGISTRATION_OWNERS) {
+				const slot = slots.get(owner);
+				if (slot !== undefined && slot.anchor === index) list.push(...slot.registrations);
+			}
+		};
+		for (let index = 0; index < host.length; index += 1) {
+			slotAt(index);
+			list.push(host[index] as MiddlewareHookRegistration);
+		}
+		slotAt(host.length);
+		return Object.freeze(list);
+	};
+
+	const makeState = (
+		host: ReadonlyArray<MiddlewareHookRegistration>,
+		slots: ReadonlyMap<MiddlewareRegistrationOwner, OwnerSlot>,
+	): TableState =>
+		Object.freeze({
+			host: Object.freeze([...host]),
+			hostIds: new Set(host.map((registration) => registration.id)),
+			slots: new Map(slots),
+			list: buildList(host, slots),
+		});
+
+	// The single live reference. Every publish below is `state = next`.
+	let state: TableState = makeState([], new Map());
+
+	const emit = (diagnostic: MiddlewareDiagnostic): void => {
+		try {
+			options.diagnosticSink()(diagnostic);
+		} catch {
+			// A diagnostics sink must never affect registration bookkeeping.
+		}
+	};
+
+	const slotFor = (base: TableState, owner: MiddlewareRegistrationOwner): OwnerSlot =>
+		base.slots.get(owner) ?? { generation: 0, registrations: [], anchor: base.host.length };
+
+	const disposeGeneration = (owner: MiddlewareRegistrationOwner, generation: number): void => {
+		const base = state;
+		const held = base.slots.get(owner);
+		if (held === undefined || held.generation !== generation || held.registrations.length === 0) return;
+		const slots = new Map(base.slots);
+		slots.set(owner, { ...held, registrations: Object.freeze([]) });
+		state = makeState(base.host, slots);
+	};
+
+	const table: MiddlewareRegistrationTable = {
+		list: () => state.list,
+		registerHook(registration) {
+			const base = state;
+			if (fixedIds.has(registration.id) || base.hostIds.has(registration.id)) return;
+			const evictions: RegistrationConflictDiagnostic[] = [];
+			const slots = new Map(base.slots);
+			for (const [owner, slot] of base.slots) {
+				if (!slot.registrations.some((entry) => entry.id === registration.id)) continue;
+				slots.set(owner, {
+					...slot,
+					registrations: Object.freeze(slot.registrations.filter((entry) => entry.id !== registration.id)),
+				});
+				evictions.push({
+					kind: "registration_conflict",
+					registrationId: registration.id,
+					owner,
+					generation: slot.generation,
+					conflictsWith: "host",
+					action: "evicted",
+				});
+			}
+			state = makeState([...base.host, registration], slots);
+			// Diagnostics only after the publish; a sink that registers another
+			// host hook re-enters against the already-published state.
+			for (const eviction of evictions) emit(eviction);
+		},
+		prepareReplacement(owner, generation, registrations) {
+			if (!isRegistrationOwner(owner)) {
+				return { status: "rejected", owner, reason: "unknown-owner", activeGeneration: 0 };
+			}
+			const base = state;
+			const slot = slotFor(base, owner);
+			if (!Number.isInteger(generation) || generation <= slot.generation) {
+				return { status: "rejected", owner, reason: "stale", activeGeneration: slot.generation };
+			}
+			const dropped: MiddlewareRegistrationConflict[] = [];
+			const conflicts: RegistrationConflictDiagnostic[] = [];
+			const accepted: MiddlewareHookRegistration[] = [];
+			const seen = new Set<string>();
+			for (const registration of registrations) {
+				const conflictsWith: MiddlewareRegistrationConflictTier | null = fixedIds.has(registration.id)
+					? "builtin"
+					: base.hostIds.has(registration.id)
+						? "host"
+						: seen.has(registration.id)
+							? "owned"
+							: null;
+				if (conflictsWith !== null) {
+					dropped.push({ id: registration.id, conflictsWith });
+					conflicts.push({
+						kind: "registration_conflict",
+						registrationId: registration.id,
+						owner,
+						generation,
+						conflictsWith,
+						action: "dropped",
+					});
+					continue;
+				}
+				seen.add(registration.id);
+				accepted.push(registration);
+			}
+			const slots = new Map(base.slots);
+			slots.set(owner, { generation, registrations: Object.freeze(accepted), anchor: slot.anchor });
+			const prepared = makeState(base.host, slots);
+			let settled = false;
+			const frozenDropped = Object.freeze(dropped);
+			const frozenConflicts = Object.freeze(conflicts);
+			const replacement: MiddlewareRegistrationReplacement = {
+				owner,
+				generation,
+				dropped: frozenDropped,
+				conflicts: frozenConflicts,
+				size: accepted.length,
+				// Reference identity on the base state covers every kind of
+				// intervening change: host appends, other replacements, disposals.
+				current: () => !settled && state === base,
+				publish() {
+					settled = true;
+					state = prepared;
+				},
+				emitConflicts() {
+					for (const conflict of frozenConflicts) emit(conflict);
+				},
+				dispose() {
+					disposeGeneration(owner, generation);
+				},
+				discard() {
+					settled = true;
+				},
+			};
+			return { status: "prepared", replacement };
+		},
+		replaceRegistrations(owner, generation, registrations) {
+			const prepared = table.prepareReplacement(owner, generation, registrations);
+			if (prepared.status === "rejected") {
+				return {
+					applied: false,
+					owner: prepared.owner,
+					activeGeneration: prepared.activeGeneration,
+					reason: prepared.reason,
+					dropped: [],
+					dispose: () => undefined,
+				};
+			}
+			const replacement = prepared.replacement;
+			// Nothing ran between prepare and here, so current() holds; the
+			// check is kept so the one-call form has the same shape as a caller
+			// that validates on its own stack.
+			if (!replacement.current()) {
+				replacement.discard();
+				return {
+					applied: false,
+					owner,
+					activeGeneration: table.ownedGeneration(owner),
+					reason: "stale",
+					dropped: replacement.dropped,
+					dispose: () => undefined,
+				};
+			}
+			replacement.publish();
+			replacement.emitConflicts();
+			return {
+				applied: true,
+				owner,
+				activeGeneration: generation,
+				dropped: replacement.dropped,
+				dispose: () => replacement.dispose(),
+			};
+		},
+		ownedGeneration(owner) {
+			return state.slots.get(owner)?.generation ?? 0;
+		},
+	};
+	return table;
+}

package/src/domains/middleware/runtime.ts

@@ -1,4 +1,5 @@
 import { createHookBudgetTracker, type HookBudgetStats, type HookBudgetTracker } from "./budget.js";
+import type { MiddlewareRegistrationConflictTier, MiddlewareRegistrationOwner } from "./registrations.js";
 import { listMiddlewareRuleDefinitions } from "./rules.js";
 import {
 	MIDDLEWARE_HOOK_TEXT_MAX_CHARS,
@@ -90,6 +91,20 @@ export type MiddlewareDiagnostic =
 			steadyStateWarn: boolean;
 			/** Rolling-window stats (p50/p95/over-count) for diagnosis. */
 			stats: HookBudgetStats;
+	  }
+	| {
+			/**
+			 * An owned registration set offered an id already held by a builtin
+			 * rule or a host registration (dropped), or a later host registration
+			 * took an id an owner held (evicted). Bookkeeping only; nothing was
+			 * evaluated.
+			 */
+			kind: "registration_conflict";
+			registrationId: string;
+			owner: MiddlewareRegistrationOwner;
+			generation: number;
+			conflictsWith: MiddlewareRegistrationConflictTier;
+			action: "dropped" | "evicted";
 	  };
 
 export type MiddlewareDiagnosticSink = (diagnostic: MiddlewareDiagnostic) => void;
@@ -106,6 +121,10 @@ export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnost
 		);
 		return;
 	}
+	if (diagnostic.kind === "registration_conflict") {
+		process.stderr.write(`[clio-coder:middleware] ${formatRegistrationConflict(diagnostic)}\n`);
+		return;
+	}
 	// A single post-warmup spike is telemetry, not operator-facing noise: only
 	// consistent slowness prints, unless CLIO_CODER_HOOK_BUDGET_DEBUG=1 asks for all.
 	if (!diagnostic.steadyStateWarn && process.env.CLIO_CODER_HOOK_BUDGET_DEBUG !== "1") return;
@@ -120,6 +139,15 @@ export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnost
 	);
 }
 
+/** One operator line for a registration_conflict diagnostic. */
+export function formatRegistrationConflict(
+	diagnostic: Extract<MiddlewareDiagnostic, { kind: "registration_conflict" }>,
+): string {
+	return diagnostic.action === "dropped"
+		? `${diagnostic.owner} registration '${diagnostic.registrationId}' (generation ${diagnostic.generation}) dropped: id is held by a ${diagnostic.conflictsWith} registration`
+		: `${diagnostic.owner} registration '${diagnostic.registrationId}' (generation ${diagnostic.generation}) evicted by a ${diagnostic.conflictsWith} registration with the same id`;
+}
+
 /**
  * Wrap a declarative rule definition as a degenerate coded registration so a
  * single ordered evaluation path serves both. The wrapped `evaluate` keeps the