@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/domains/middleware/marketplace-offer.ts

@@ -0,0 +1,339 @@
+import { randomUUID } from "node:crypto";
+import {
+	SKILL_INSTALL_OFFER_OPTION_NEVER,
+	SKILL_INSTALL_OFFER_OPTION_NOT_NOW,
+	SKILL_INSTALL_OFFER_OPTION_PROJECT,
+	SKILL_INSTALL_OFFER_OPTION_USER,
+} from "../../core/skill-activation.js";
+import { ToolNames } from "../../core/tool-names.js";
+import type { MarketplaceSkill } from "../resources/skills/marketplace.js";
+import {
+	assertPromotionInstallSource,
+	declineKey,
+	matchMarketplaceSkills,
+	type PromotionMatch,
+	readPromotionDeclines,
+	recordPromotionNeverDecline,
+} from "../resources/skills/promotion.js";
+import type { AutonomyLevel } from "../safety/autonomy.js";
+import type { MiddlewareHookRegistration } from "./runtime.js";
+import { isSubstantiveUserTurn } from "./skills-reminder.js";
+import { type MiddlewareEffect, type MiddlewareHookInput, metadataNumber } from "./types.js";
+
+/**
+ * Marketplace self-promotion offer. When the operator's request needs
+ * expertise no installed skill covers and the local marketplace has a match,
+ * this registration teaches the model to put one tight ask_user question to
+ * the operator; the after_tool observer then acts on the answer — a consented
+ * install runs harness-side through the injected installer, "Not now" is a
+ * session-only decline, and "Never offer this skill" persists.
+ *
+ * Firing is need-driven, not count-budgeted: any substantive turn whose text
+ * matches an uninstalled, undeclined marketplace skill may fire, but each
+ * skill is offered at most once per session so a repeated request never
+ * becomes a nag. Detection is the local lexical matcher in
+ * resources/skills/promotion.ts — no request text leaves the machine.
+ *
+ * At full-auto the offer collapses into an autonomous install, but ONLY from
+ * Clio's own marketplace: every promotion-flow install (consented or
+ * autonomous) passes `assertPromotionInstallSource`, the hard runtime gate
+ * that rejects public registries in code rather than prompt text.
+ *
+ * Coordinator-only by wiring: this registration is created in the
+ * orchestrator entry and never in a dispatch worker's loop, so workers can
+ * neither see nor trigger offers.
+ */
+
+export const MARKETPLACE_OFFER_REGISTRATION_ID = "observer.marketplace-offer";
+
+export interface MarketplaceOfferInstallResult {
+	path: string;
+	/** The source the skill was fetched from; surfaced so an autonomous install stays auditable. */
+	sourceUrl: string;
+	/** Normalized content hash of what was written; the integrity record the consent overlay would have shown. */
+	installedHash: string;
+}
+
+export interface MarketplaceOfferDeps {
+	/** Installed skill names the matcher must exclude. */
+	listInstalledSkillNames(): ReadonlyArray<string>;
+	/** The local marketplace lookup (catalog + index); already local-only. */
+	listMarketplaceEntries(): ReadonlyArray<MarketplaceSkill>;
+	/** The session's effective autonomy at evaluation time. */
+	getAutonomy(): AutonomyLevel;
+	/** Perform the install; the registration gates the source before calling. */
+	installEntry(entry: MarketplaceSkill, scope: "user" | "project"): MarketplaceOfferInstallResult;
+	/** Decline persistence; defaults to the promotion module's config-dir store. Keyed by name+version. */
+	declines?: {
+		readNever(): Readonly<Record<string, string>>;
+		recordNever(name: string, version?: string): void;
+	};
+	/** Per-offer binding tag source; injectable for deterministic tests. Defaults to a random id. */
+	newOfferTag?: () => string;
+}
+
+const NO_EFFECTS: ReadonlyArray<MiddlewareEffect> = [];
+
+/**
+ * The tag the model must echo verbatim in its ask_user question so the harness
+ * binds the answer to this specific offer and nothing else. The tag lives only
+ * in a system reminder (a trusted channel), so prompt-injected user or file
+ * content cannot forge it onto an unrelated question.
+ */
+export function offerBindingTag(offerTag: string): string {
+	return `[clio-install:${offerTag}]`;
+}
+
+export function marketplaceOfferReminder(entry: MarketplaceSkill, offerTag: string): string {
+	return (
+		`[Marketplace] This request may need expertise no installed skill covers. The local marketplace has ` +
+		`"${entry.name}" (not installed): ${entry.description} ` +
+		`First check the installed side with context(scope="skills"); if ${entry.name} is genuinely the right fit ` +
+		`and nothing installed serves, ask the operator with ask_user (mode=single_question, header "Install skill") ` +
+		`whether to install ${entry.name}, offering exactly these options in this order: ` +
+		`"${SKILL_INSTALL_OFFER_OPTION_PROJECT}", "${SKILL_INSTALL_OFFER_OPTION_USER}", ` +
+		`"${SKILL_INSTALL_OFFER_OPTION_NOT_NOW}", "${SKILL_INSTALL_OFFER_OPTION_NEVER}". ` +
+		`Include the exact tag ${offerBindingTag(offerTag)} verbatim in that question's text so the harness can bind ` +
+		`the answer to this offer; the harness acts only on an answer carrying this tag. ` +
+		`Then continue the task in the same turn. The harness handles the answer; never install or load a skill yourself. ` +
+		`If it is not actually needed, do not mention it.`
+	);
+}
+
+export function marketplaceAutoInstallReminder(entry: MarketplaceSkill, result: MarketplaceOfferInstallResult): string {
+	// Full-auto skips the operator's yes/no, never the integrity record. The
+	// consent overlay states the source and the SHA-256 of what it writes; the
+	// autonomous path computes the same hash and must surface it here, so an
+	// install nobody was asked about is still traceable to its source and bytes.
+	return (
+		`[Marketplace] Installed skill "${entry.name}" from Clio's own local marketplace (full-auto) to ${result.path}. ` +
+		`Source ${result.sourceUrl}, sha256 ${result.installedHash}. ${entry.description} ` +
+		`It is installed but not active — activation stays operator-gated. If it fits this task, ` +
+		`suggest /skill ${entry.name} to the operator; never load it yourself.`
+	);
+}
+
+interface AnswerLike {
+	question: string;
+	answer: string;
+	options?: ReadonlyArray<string>;
+}
+
+function answersFromDetails(details: Readonly<Record<string, unknown>> | undefined): AnswerLike[] {
+	const raw = details?.answers;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter(
+		(entry): entry is AnswerLike =>
+			typeof entry === "object" &&
+			entry !== null &&
+			typeof (entry as AnswerLike).question === "string" &&
+			typeof (entry as AnswerLike).answer === "string",
+	);
+}
+
+/** The offer option this answer chose, matched by exact label in options or by label substring in the one-line answer. */
+function chosenOfferOption(answer: AnswerLike): string | null {
+	const labels = [
+		SKILL_INSTALL_OFFER_OPTION_PROJECT,
+		SKILL_INSTALL_OFFER_OPTION_USER,
+		SKILL_INSTALL_OFFER_OPTION_NOT_NOW,
+		SKILL_INSTALL_OFFER_OPTION_NEVER,
+	];
+	for (const label of labels) {
+		if (answer.options?.includes(label)) return label;
+	}
+	for (const label of labels) {
+		if (answer.answer.includes(label)) return label;
+	}
+	return null;
+}
+
+export function createMarketplaceOfferRegistration(deps: MarketplaceOfferDeps): MiddlewareHookRegistration {
+	const declines = deps.declines ?? {
+		readNever: () => readPromotionDeclines().never,
+		recordNever: (name: string, version?: string) => recordPromotionNeverDecline(name, version),
+	};
+	const newOfferTag = deps.newOfferTag ?? (() => randomUUID());
+	// Per-session state, reset on a session id change (same adoption rule as
+	// the skills reminder: a fresh session's opening turn fires with a null id
+	// that the created session then fills in).
+	let lastSeenSessionId: string | null | undefined;
+	let offeredNames = new Set<string>();
+	let sessionDeclines = new Set<string>();
+	// Discovery parses and hashes every installed/catalog SKILL.md. On a real
+	// home with 31 entries per side that cost 36-92ms on every turn_start, while
+	// the lexical match itself stayed below 2ms. Inventory is stable within a
+	// session except for installs, so keep one session snapshot and revalidate
+	// installed names only when cached data is about to produce an offer.
+	let installedNamesCache: Set<string> | null = null;
+	let marketplaceEntriesCache: ReadonlyArray<MarketplaceSkill> | null = null;
+	// The offer put to the operator, consumed by the ask_user after_tool
+	// observer. Each offer carries a unique binding tag the model must echo in
+	// its question; the observer acts only on an answer whose question carries
+	// that tag, so an unrelated (or prompt-injected) ask_user answer can never
+	// bind the pending offer.
+	let pendingOffer: { entry: MarketplaceSkill; tag: string } | null = null;
+
+	const trackSession = (input: MiddlewareHookInput): void => {
+		const sessionId = input.sessionId ?? null;
+		if (lastSeenSessionId === undefined || (lastSeenSessionId === null && sessionId !== null)) {
+			lastSeenSessionId = sessionId;
+			return;
+		}
+		if (sessionId !== lastSeenSessionId) {
+			lastSeenSessionId = sessionId;
+			offeredNames = new Set<string>();
+			sessionDeclines = new Set<string>();
+			pendingOffer = null;
+			installedNamesCache = null;
+			marketplaceEntriesCache = null;
+		}
+	};
+
+	const bestMatch = (text: string): PromotionMatch | null => {
+		const installedWasCached = installedNamesCache !== null;
+		let never: Readonly<Record<string, string>>;
+		try {
+			installedNamesCache ??= new Set(deps.listInstalledSkillNames());
+			marketplaceEntriesCache ??= deps.listMarketplaceEntries();
+			never = declines.readNever();
+		} catch {
+			return null;
+		}
+		// offeredNames caps to one offer per skill per session, regardless of
+		// version. Declines are version-scoped: a "never"/"not now" on one catalog
+		// version does not suppress a later version of the same skill.
+		const declinedKeys = new Set<string>([...Object.keys(never), ...sessionDeclines]);
+		const findMatch = (): PromotionMatch | null =>
+			matchMarketplaceSkills(
+				text,
+				marketplaceEntriesCache ?? [],
+				new Set<string>([...(installedNamesCache ?? []), ...offeredNames]),
+			).find((candidate) => !declinedKeys.has(declineKey(candidate.entry.name, candidate.entry.version))) ?? null;
+		let match = findMatch();
+		if (match && installedWasCached) {
+			// A skills-hub or external install can happen after the session snapshot.
+			// Pay the installed-tree refresh only on the rare path that would surface
+			// an offer, then match again so an already-installed skill is never nagged.
+			try {
+				installedNamesCache = new Set(deps.listInstalledSkillNames());
+			} catch {
+				return null;
+			}
+			match = findMatch();
+		}
+		return match;
+	};
+
+	const installGated = (entry: MarketplaceSkill, scope: "user" | "project"): MarketplaceOfferInstallResult => {
+		assertPromotionInstallSource(entry);
+		const result = deps.installEntry(entry, scope);
+		installedNamesCache?.add(entry.name);
+		return result;
+	};
+
+	const evaluateAskUserAnswers = (input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> => {
+		const offer = pendingOffer;
+		if (!offer) return NO_EFFECTS;
+		const marker = offerBindingTag(offer.tag);
+		if (input.toolResultDetails?.cancelled === true) {
+			// A cancelled interview carries no question text, so it cannot be
+			// attributed to this offer. Do not bind it: an unrelated cancel must
+			// not decline our offer, and the offer stays armed for a later answer.
+			return NO_EFFECTS;
+		}
+		for (const answer of answersFromDetails(input.toolResultDetails)) {
+			// The answer binds only when its question carries this offer's tag.
+			if (!answer.question.includes(marker)) continue;
+			const option = chosenOfferOption(answer);
+			if (option === null) continue;
+			pendingOffer = null;
+			const offerKey = declineKey(offer.entry.name, offer.entry.version);
+			if (option === SKILL_INSTALL_OFFER_OPTION_NOT_NOW) {
+				sessionDeclines.add(offerKey);
+				return NO_EFFECTS;
+			}
+			if (option === SKILL_INSTALL_OFFER_OPTION_NEVER) {
+				sessionDeclines.add(offerKey);
+				try {
+					declines.recordNever(offer.entry.name, offer.entry.version);
+				} catch {
+					// Persistence failure degrades to a session decline.
+				}
+				return NO_EFFECTS;
+			}
+			const scope = option === SKILL_INSTALL_OFFER_OPTION_USER ? "user" : "project";
+			try {
+				const result = installGated(offer.entry, scope);
+				return [
+					{
+						kind: "annotate_tool_result",
+						severity: "info",
+						message:
+							`[Marketplace] Installed skill "${offer.entry.name}" (${scope} scope) to ${result.path}. ` +
+							`It is installed but not active; the operator activates it with /skill ${offer.entry.name}.`,
+					},
+				];
+			} catch (error) {
+				sessionDeclines.add(offerKey);
+				return [
+					{
+						kind: "annotate_tool_result",
+						severity: "warn",
+						message: `[Marketplace] Install of "${offer.entry.name}" failed: ${
+							error instanceof Error ? error.message : String(error)
+						}. Continue the task without it.`,
+					},
+				];
+			}
+		}
+		return NO_EFFECTS;
+	};
+
+	return {
+		id: MARKETPLACE_OFFER_REGISTRATION_ID,
+		description:
+			"offers an uninstalled marketplace skill via ask_user when the request matches it; consented installs run gated to Clio's own marketplace, declines are remembered",
+		hooks: ["turn_start", "after_tool"],
+		evaluate(input): ReadonlyArray<MiddlewareEffect> {
+			trackSession(input);
+			// The offer is deliberately NOT cleared at turn_end. The reminder asks
+			// the model to put the ask_user question in the same turn, but it often
+			// defers a turn; clearing here dropped that deferred answer on the floor,
+			// so the operator's "Install" installed nothing and the model got no
+			// signal to correct a likely success claim. The offer now stays armed
+			// until a tag-carrying answer binds it, a newer offer replaces it, or the
+			// session ends — safe because only a tagged answer can bind (see H4).
+			if (input.hook === "after_tool") {
+				return input.toolName === ToolNames.AskUser ? evaluateAskUserAnswers(input) : NO_EFFECTS;
+			}
+			if (input.hook !== "turn_start") return NO_EFFECTS;
+			if (!isSubstantiveUserTurn(input.text)) return NO_EFFECTS;
+			// The operator already chose a skill for this turn; an offer on top of
+			// that choice is noise.
+			const pendingSkillRequests = metadataNumber(input, "pendingSkillRequests");
+			if (pendingSkillRequests !== null && pendingSkillRequests > 0) return NO_EFFECTS;
+			const match = bestMatch(input.text ?? "");
+			if (!match) return NO_EFFECTS;
+			offeredNames.add(match.entry.name);
+			if (deps.getAutonomy() === "full-auto") {
+				try {
+					const result = installGated(match.entry, "project");
+					return [
+						{
+							kind: "inject_reminder",
+							severity: "info",
+							message: marketplaceAutoInstallReminder(match.entry, result),
+						},
+					];
+				} catch {
+					// Gate refusal or install failure: fall back to the consent offer
+					// so the operator still hears about the match.
+				}
+			}
+			const tag = newOfferTag();
+			pendingOffer = { entry: match.entry, tag };
+			return [{ kind: "inject_reminder", severity: "info", message: marketplaceOfferReminder(match.entry, tag) }];
+		},
+	};
+}

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