@primafuture/contrib-kit-react 1.0.0

package/src/internal/outlet-commit-lease.ts

@@ -0,0 +1,216 @@
+import * as reactAdapterError from "../react-adapter-error.js";
+
+/** Privátní compile-time identita opaque outlet tokenu. */
+declare const outletInstanceTokenBrand: unique symbol;
+
+/** Render-pure opaque identita jedné budoucí outlet instance. */
+export interface OutletInstanceToken {
+	/** Privátní invariant bez runtime property nebo globálního brandu. */
+	readonly [outletInstanceTokenBrand]: "outlet-instance";
+}
+
+/** Druh commit-owned diagnostické identity. */
+export type OutletCommitOwnerKind = "outlet" | "boundary";
+
+/** Interní commit lease s přesnou epochovou autoritou. */
+export interface OutletCommitLease {
+	/** Scope-local opaque identita bez veřejného formátového kontraktu. */
+	readonly id: string;
+	/** Monotonická scope epocha, ve které lease vznikla. */
+	readonly epoch: number;
+	/** Ověří current lease, owner cycle i owning scope epoch. */
+	readonly isCurrent: () => boolean;
+	/** Idempotentně ukončí právě tuto committed lease. */
+	readonly release: () => void;
+}
+
+/** Deterministický microtask seam pro Strict grace finalizaci. */
+export type OutletCommitLeaseScheduler = (callback: () => void) => void;
+
+/** Probe přesné scope epochy bez převzetí jejího lifecycle. */
+export type OutletCommitEpochProbe = (epoch: number) => boolean;
+
+/** Jedna autoritativní nebo již zneplatněná sada souběžných leases. */
+interface OutletCommitOwnerCycle {
+	/** True pouze do owner release nebo epoch invalidace. */
+	authoritative: boolean;
+	/** Počet právě aktivních leases stejného owner tokenu. */
+	count: number;
+}
+
+/** Scope-local záznam jednoho commit-owned opaque tokenu. */
+interface OutletCommitOwnerRecord {
+	/** Exact token používaný také jako WeakMap klíč. */
+	readonly token: object;
+	/** Rozlišuje outlet a membership boundary identitu. */
+	readonly kind: OutletCommitOwnerKind;
+	/** Scope-local diagnostická identita. */
+	readonly id: string;
+	/** Scope epocha, ve které je možné ID znovu získat. */
+	readonly epoch: number;
+	/** Právě autoritativní nebo grace owner cycle. */
+	cycle: OutletCommitOwnerCycle;
+	/** Zda záznam přijímá Strict reacquire před finalizací. */
+	state: "active" | "grace" | "retired";
+	/** Monotonický guard všech naplánovaných finalizerů. */
+	finalizeToken: number;
+}
+
+/** Vytvoří nový owner cycle bez zděděné autority starých leases. */
+function createOwnerCycle(): OutletCommitOwnerCycle {
+	return { authoritative: true, count: 0 };
+}
+
+/** Vytvoří render-pure outlet token bez external identity nebo side effectu. */
+export function createOutletInstanceToken(): OutletInstanceToken {
+	return Object.freeze({}) as OutletInstanceToken;
+}
+
+/**
+ * Scope-local allocator a Strict grace registr commit-owned diagnostických identit.
+ */
+export class OutletCommitLeaseRegistry {
+	/** Deterministický scheduler zachycený při vytvoření owning adapter scope. */
+	readonly #scheduleMicrotask: OutletCommitLeaseScheduler;
+	/** Token-indexovaný stav bez process-global nebo cross-scope historie. */
+	readonly #recordsByToken = new WeakMap<object, OutletCommitOwnerRecord>();
+	/** Iterovatelná množina pouze dosud nereleased scope records. */
+	readonly #records = new Set<OutletCommitOwnerRecord>();
+	/** Monotonický scope-local allocator obou druhů identit. */
+	#nextIdentity = 0;
+
+	/** Zachytí jediný scheduler seam pro celý scope lifetime. */
+	public constructor(scheduleMicrotask: OutletCommitLeaseScheduler) {
+		this.#scheduleMicrotask = scheduleMicrotask;
+	}
+
+	/** Vrátí počet dosud nefinalizovaných owner records pro lifecycle testy. */
+	public readRetainedOwnerCount(): number {
+		return this.#records.size;
+	}
+
+	/**
+	 * Přijme jednu committed lease; grace reacquire zachová existující ID.
+	 */
+	public acquire(
+		epoch: number,
+		kind: OutletCommitOwnerKind,
+		token: object,
+		isEpochCurrent: OutletCommitEpochProbe,
+	): OutletCommitLease {
+		if (!Number.isSafeInteger(epoch) || epoch < 1) {
+			throw new reactAdapterError.ReactAdapterError(
+				"REACT_ADAPTER_DISPOSED",
+				"A commit lease requires an active adapter scope epoch.",
+				{ details: { field: "scope.epoch", phase: "lifecycle" } },
+			);
+		}
+
+		let record = this.#recordsByToken.get(token);
+		if (record !== undefined
+			&& (record.kind !== kind || record.epoch !== epoch || record.state === "retired")) {
+			this.#retireRecord(record);
+			record = undefined;
+		}
+
+		if (record === undefined) {
+			this.#nextIdentity += 1;
+			record = {
+				token,
+				kind,
+				id: `react-${kind}:${this.#nextIdentity}`,
+				epoch,
+				cycle: createOwnerCycle(),
+				state: "active",
+				finalizeToken: 0,
+			};
+			this.#recordsByToken.set(token, record);
+			this.#records.add(record);
+		} else if (record.state === "grace") {
+			record.finalizeToken += 1;
+			record.cycle = createOwnerCycle();
+			record.state = "active";
+		}
+
+		const currentRecord = record;
+		const cycle = currentRecord.cycle;
+		cycle.count += 1;
+		let active = true;
+		const registry = this;
+
+		/** Ověří přesnou lease bez reaktivace stale owner cycle. */
+		function isCurrent(): boolean {
+			return active
+				&& currentRecord.state === "active"
+				&& currentRecord.cycle === cycle
+				&& cycle.authoritative
+				&& isEpochCurrent(epoch);
+		}
+
+		/** Idempotentně odebere právě jednu lease a případně zahájí grace. */
+		function release(): void {
+			if (!active) {
+				return;
+			}
+			active = false;
+			cycle.count -= 1;
+			if (currentRecord.state !== "active"
+				|| currentRecord.cycle !== cycle
+				|| cycle.count !== 0) {
+				return;
+			}
+			registry.#beginRecordGrace(currentRecord);
+		}
+
+		return Object.freeze({ id: currentRecord.id, epoch, isCurrent, release });
+	}
+
+	/** Synchronně zneplatní všechny capability jedné scope epochy před cleanupem. */
+	public invalidateEpoch(epoch: number): void {
+		for (const record of [...this.#records]) {
+			if (record.epoch === epoch && record.state === "active") {
+				this.#beginRecordGrace(record);
+			}
+		}
+	}
+
+	/** Terminálně odstraní všechny owner records jedné retired scope epochy. */
+	public retireEpoch(epoch: number): void {
+		for (const record of [...this.#records]) {
+			if (record.epoch === epoch) {
+				this.#retireRecord(record);
+			}
+		}
+	}
+
+	/** Zneplatní current cycle a naplánuje tokenově chráněný finalizer. */
+	#beginRecordGrace(record: OutletCommitOwnerRecord): void {
+		if (record.state !== "active") {
+			return;
+		}
+		record.cycle.authoritative = false;
+		record.state = "grace";
+		record.finalizeToken += 1;
+		const finalizeToken = record.finalizeToken;
+		this.#scheduleMicrotask((): void => {
+			if (record.state !== "grace" || record.finalizeToken !== finalizeToken) {
+				return;
+			}
+			this.#retireRecord(record);
+		});
+	}
+
+	/** Odstraní record z iterovatelné i weak token projekce. */
+	#retireRecord(record: OutletCommitOwnerRecord): void {
+		if (record.state === "retired") {
+			return;
+		}
+		record.cycle.authoritative = false;
+		record.state = "retired";
+		record.finalizeToken += 1;
+		this.#records.delete(record);
+		if (this.#recordsByToken.get(record.token) === record) {
+			this.#recordsByToken.delete(record.token);
+		}
+	}
+}

package/src/internal/outlet-error-pipeline.ts

@@ -0,0 +1,447 @@
+import type * as contribKitCore from "@primafuture/contrib-kit-core";
+
+import * as adapterConfiguration from "./adapter-configuration.js";
+import * as outletInput from "./outlet-input.js";
+import type * as contributionComponent from "../contribution-component.js";
+import * as reactAdapterDiagnostics from "../react-adapter-diagnostics.js";
+import type * as reactAdapterError from "../react-adapter-error.js";
+import type * as reactExtensionPoint from "../react-extension-point.js";
+
+/** Frozen capability doručená outlet `onError` callbacku. */
+export interface OutletContributionErrorEmission {
+	/** Rozlišuje contribution failure od budoucí resolve větve. */
+	readonly kind: "contribution";
+	/** Tentýž frozen primary event použitý sinkem a policy. */
+	readonly error: reactAdapterDiagnostics.ReactAdapterErrorEvent;
+	/** Generation-bound recovery command bez registry capability. */
+	readonly retry: () => void;
+}
+
+/** Autoritativní výsledek committed contribution error pipeline. */
+export type OutletPrimaryErrorDecision =
+	| {
+		/** Starý attempt byl reentrantně zneplatněn a nic dalšího nesmí publikovat. */
+		readonly kind: "stale";
+	}
+	| {
+		/** Membership zůstane skrytá při zachování logical placementu sourozenců. */
+		readonly kind: "hide";
+		/** Frozen primary event dostupný internímu boundary state. */
+		readonly error: reactAdapterDiagnostics.ReactAdapterErrorEvent;
+	}
+	| {
+		/** Host fallback se smí renderovat v oddělené reporter boundary. */
+		readonly kind: "renderFallback";
+		/** Frozen primary event dostupný fallback render state. */
+		readonly error: reactAdapterDiagnostics.ReactAdapterErrorEvent;
+	}
+	| {
+		/** Přesný primary cause se má v příštím renderu eskalovat hostu. */
+		readonly kind: "escalate";
+		/** Frozen primary event zůstává diagnostickou evidencí. */
+		readonly error: reactAdapterDiagnostics.ReactAdapterErrorEvent;
+		/** Exact captured cause; nikdy structured wrapper. */
+		readonly cause: unknown;
+	};
+
+/** Společná metadata jedné committed membership failure. */
+export interface OutletErrorIdentity<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Opaque commit-owned boundary identita. */
+	readonly boundaryId: string;
+	/** Exact outlet context bez automatické diagnostické publikace. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Bezpečný public contribution view. */
+	readonly contribution: contributionComponent.ExtensionContributionView<
+		contribKitCore.ExtensionPointData<Point>
+	>;
+	/** Opaque commit-owned outlet identita. */
+	readonly outletId: string;
+	/** Exact canonical React point. */
+	readonly point: Point;
+	/** Opaque Core activation identita dostupná pouze boundary pipeline. */
+	readonly registrationId: string;
+	/** Monotonická membership retry generation. */
+	readonly retryGeneration: number;
+}
+
+/** Vstup primary contribution failure pipeline po React commit pointu. */
+export interface OutletPrimaryErrorPipelineInput<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> extends OutletErrorIdentity<Point> {
+	/** Stabilní adapter error code zdroje failure. */
+	readonly code: reactAdapterError.ReactAdapterErrorCode;
+	/** Effective scope/outlet diagnostic konfigurace. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+	/** Přesný cizí nebo bezpečný syntetický cause. */
+	readonly cause: unknown;
+	/** Zda host poskytl oddělený contribution fallback renderer. */
+	readonly hasFallback: boolean;
+	/** `false` vypne contribution isolation bez volání policy. */
+	readonly isolateErrors: boolean;
+	/** Current authority checkpoint po každém user-observable kroku. */
+	readonly isCurrent: () => boolean;
+	/** Optional guarded outlet callback zachycený read-once. */
+	readonly onError: outletInput.CapturedOutletCallback<
+		OutletContributionErrorEmission,
+		unknown
+	> | undefined;
+	/** Přesná adapter phase zdroje primary failure. */
+	readonly phase: reactAdapterError.ReactAdapterErrorPhase;
+	/** Normalizovaný React component stack, existuje-li. */
+	readonly reactComponentStack?: string;
+	/** Generation-bound retry command. */
+	readonly retry: () => void;
+}
+
+/** Vstup sink-only fallback reporteru bez policy nebo callback recursion. */
+export interface OutletFallbackErrorInput<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> extends OutletErrorIdentity<Point> {
+	/** Effective diagnostic konfigurace owning outletu. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+	/** Exact fallback render cause eskalovaný hostu. */
+	readonly cause: unknown;
+	/** Ověří committed boundary/outlet autoritu před publikací. */
+	readonly isCurrent: () => boolean;
+	/** Normalizovaný React component stack, existuje-li. */
+	readonly reactComponentStack?: string;
+}
+
+/** Frozen committed event jednoho accepted retry. */
+export interface OutletRetryEvent {
+	/** Opaque committed boundary identita. */
+	readonly boundaryId: string;
+	/** Veřejná contribution identita bez dat. */
+	readonly contributionId: string;
+	/** Opaque committed outlet identita. */
+	readonly outletId: string;
+	/** Veřejná point identita. */
+	readonly pointId: string;
+	/** Opaque Core activation identita. */
+	readonly registrationId: string;
+	/** Nově committed retry generation. */
+	readonly retryGeneration: number;
+}
+
+/** Vstup guarded onRetry callbacku po commitu nové generation. */
+export interface OutletRetryCallbackInput<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> extends OutletErrorIdentity<Point> {
+	/** Effective sink pro případ callback failure. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+	/** Current generation authority. */
+	readonly isCurrent: () => boolean;
+	/** Optional read-once outlet callback. */
+	readonly onRetry: outletInput.CapturedOutletCallback<OutletRetryEvent, unknown> | undefined;
+}
+
+/** Vytvoří bezpečná contribution metadata bez čtení business data hodnoty. */
+function createProjectedContributionMetadata<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	identity: OutletErrorIdentity<Point>,
+): reactAdapterDiagnostics.ReadonlyContributionMetadata {
+	const contribution = identity.contribution;
+	return Object.freeze({
+		registrationId: identity.registrationId,
+		contributionId: contribution.contributionId,
+		...(contribution.contributorId === undefined
+			? {}
+			: { contributorId: contribution.contributorId }),
+		...(contribution.label === undefined ? {} : { label: contribution.label }),
+		...(contribution.localName === undefined
+			? {}
+			: { localName: contribution.localName }),
+	});
+}
+
+/** Vytvoří secondary event sdílející pouze bezpečné identity primary failure. */
+function createSecondaryErrorEvent<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	input: OutletErrorIdentity<Point>,
+	code: reactAdapterError.ReactAdapterErrorCode,
+	phase: reactAdapterError.ReactAdapterErrorPhase,
+	cause: unknown,
+): reactAdapterDiagnostics.ReactAdapterErrorEvent {
+	const point = reactAdapterDiagnostics.createPointMetadata(input.point);
+	return reactAdapterDiagnostics.createReactAdapterErrorEvent({
+		boundaryId: input.boundaryId,
+		code,
+		cause,
+		contribution: createProjectedContributionMetadata(input),
+		outletId: input.outletId,
+		phase,
+		...(point === undefined ? {} : { point }),
+		retryGeneration: input.retryGeneration,
+	});
+}
+
+/** Publikuje secondary diagnostiku bez callback nebo policy recursion. */
+function reportSecondaryFailure<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	input: OutletErrorIdentity<Point> & {
+		readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+	},
+	code: reactAdapterError.ReactAdapterErrorCode,
+	phase: reactAdapterError.ReactAdapterErrorPhase,
+	cause: unknown,
+): void {
+	const error = createSecondaryErrorEvent(input, code, phase, cause);
+	reactAdapterDiagnostics.reportReactAdapterDiagnostic(
+		reactAdapterDiagnostics.createErrorDiagnostic(error),
+		input.configuration,
+	);
+}
+
+/** Bezpečně spotřebuje callback return a reportuje nejvýše jednu rejection. */
+function consumeCallbackResult<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	result: unknown,
+	input: OutletErrorIdentity<Point> & {
+		readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+		readonly isCurrent: () => boolean;
+	},
+): void {
+	let reported = false;
+	/** Přeloží právě jednu current callback failure na sink-only diagnostiku. */
+	function reportCallbackFailure(cause: unknown): void {
+		if (reported || !input.isCurrent()) {
+			return;
+		}
+		reported = true;
+		reportSecondaryFailure(input, "REACT_CALLBACK_FAILED", "callback", cause);
+	}
+
+	try {
+		void Promise.resolve(result).catch(reportCallbackFailure);
+	} catch (cause: unknown) {
+		reportCallbackFailure(cause);
+	}
+}
+
+/** Zavolá guarded outlet callback s undefined receiverem a bezpečnou finalitou. */
+function callGuardedOutletCallback<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+	Argument,
+>(
+	callback: outletInput.CapturedOutletCallback<Argument, unknown>,
+	argument: Argument,
+	input: OutletErrorIdentity<Point> & {
+		readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+		readonly isCurrent: () => boolean;
+	},
+): void {
+	let result: unknown;
+	try {
+		result = outletInput.callCapturedOutletCallback(callback, argument);
+	} catch (cause: unknown) {
+		if (input.isCurrent()) {
+			reportSecondaryFailure(input, "REACT_CALLBACK_FAILED", "callback", cause);
+		}
+		return;
+	}
+	consumeCallbackResult(result, input);
+}
+
+/** Pure-synchronně projektuje context a případné selhání publikuje před primary. */
+function projectPrimaryContext<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	input: OutletErrorIdentity<Point> & {
+		readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+		readonly isCurrent: () => boolean;
+	},
+): { readonly hasProjection: boolean; readonly projection?: unknown } {
+	const projector = input.configuration.projectContext;
+	if (projector === undefined) {
+		return Object.freeze({ hasProjection: false });
+	}
+
+	try {
+		const projection = Reflect.apply(projector, undefined, [input.context]) as unknown;
+		return Object.freeze({ hasProjection: true, projection });
+	} catch (cause: unknown) {
+		if (input.isCurrent()) {
+			reportSecondaryFailure(
+				input,
+				"REACT_CONTEXT_PROJECTION_FAILED",
+				"projection",
+				cause,
+			);
+		}
+		return Object.freeze({ hasProjection: false });
+	}
+}
+
+/** Vytvoří primary event po jediné pure context projection. */
+function createPrimaryErrorEvent<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	input: OutletPrimaryErrorPipelineInput<Point>,
+	projection: { readonly hasProjection: boolean; readonly projection?: unknown },
+): reactAdapterDiagnostics.ReactAdapterErrorEvent {
+	const point = reactAdapterDiagnostics.createPointMetadata(input.point);
+	return reactAdapterDiagnostics.createReactAdapterErrorEvent({
+		boundaryId: input.boundaryId,
+		code: input.code,
+		cause: input.cause,
+		contribution: createProjectedContributionMetadata(input),
+		outletId: input.outletId,
+		phase: input.phase,
+		...(point === undefined ? {} : { point }),
+		...(input.reactComponentStack === undefined
+			? {}
+			: { reactComponentStack: input.reactComponentStack }),
+		retryGeneration: input.retryGeneration,
+		...(projection.hasProjection
+			? { contextProjection: projection.projection, hasContextProjection: true }
+			: {}),
+	});
+}
+
+/** Vyhodnotí captured nebo package-default contribution policy. */
+function evaluateErrorPolicy<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	input: OutletPrimaryErrorPipelineInput<Point>,
+	error: reactAdapterDiagnostics.ReactAdapterErrorEvent,
+): reactAdapterDiagnostics.ReactErrorAction | undefined {
+	const policy = input.configuration.errorPolicy;
+	if (policy === undefined) {
+		return input.hasFallback ? "renderFallback" : "hide";
+	}
+
+	let action: unknown;
+	try {
+		action = Reflect.apply(policy, undefined, [error]);
+	} catch (cause: unknown) {
+		reportSecondaryFailure(input, "REACT_ERROR_POLICY_FAILED", "policy", cause);
+		return undefined;
+	}
+	if (action !== "hide" && action !== "renderFallback" && action !== "escalate") {
+		reportSecondaryFailure(
+			input,
+			"REACT_ERROR_POLICY_FAILED",
+			"policy",
+			new TypeError("React error policy returned an unsupported action."),
+		);
+		return undefined;
+	}
+	return action;
+}
+
+/** Spustí přesně seřazenou committed contribution error pipeline. */
+export function runOutletPrimaryErrorPipeline<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	input: OutletPrimaryErrorPipelineInput<Point>,
+): OutletPrimaryErrorDecision {
+	if (!input.isCurrent()) {
+		return Object.freeze({ kind: "stale" });
+	}
+	const projection = projectPrimaryContext(input);
+	if (!input.isCurrent()) {
+		return Object.freeze({ kind: "stale" });
+	}
+	const error = createPrimaryErrorEvent(input, projection);
+	reactAdapterDiagnostics.reportReactAdapterDiagnostic(
+		reactAdapterDiagnostics.createErrorDiagnostic(error),
+		input.configuration,
+	);
+	if (!input.isCurrent()) {
+		return Object.freeze({ kind: "stale" });
+	}
+
+	if (input.onError !== undefined) {
+		const emission: OutletContributionErrorEmission = Object.freeze({
+			kind: "contribution",
+			error,
+			retry: input.retry,
+		});
+		callGuardedOutletCallback(input.onError, emission, input);
+		if (!input.isCurrent()) {
+			return Object.freeze({ kind: "stale" });
+		}
+	}
+
+	if (!input.isolateErrors) {
+		return Object.freeze({ kind: "escalate", error, cause: input.cause });
+	}
+	const action = evaluateErrorPolicy(input, error);
+	if (!input.isCurrent()) {
+		return Object.freeze({ kind: "stale" });
+	}
+	if (action === undefined || action === "escalate") {
+		return Object.freeze({ kind: "escalate", error, cause: input.cause });
+	}
+	if (action === "renderFallback") {
+		return input.hasFallback
+			? Object.freeze({ kind: "renderFallback", error })
+			: Object.freeze({ kind: "escalate", error, cause: input.cause });
+	}
+	return Object.freeze({ kind: "hide", error });
+}
+
+/** Reportuje fallback failure bez onError/policy recursion a vrátí exact cause. */
+export function reportOutletFallbackError<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	input: OutletFallbackErrorInput<Point>,
+): unknown {
+	if (!input.isCurrent()) {
+		return input.cause;
+	}
+	const point = reactAdapterDiagnostics.createPointMetadata(input.point);
+	const event = reactAdapterDiagnostics.createReactAdapterErrorEvent({
+		boundaryId: input.boundaryId,
+		code: "REACT_RENDER_FAILED",
+		cause: input.cause,
+		contribution: createProjectedContributionMetadata(input),
+		outletId: input.outletId,
+		phase: "fallback",
+		...(point === undefined ? {} : { point }),
+		...(input.reactComponentStack === undefined
+			? {}
+			: { reactComponentStack: input.reactComponentStack }),
+		retryGeneration: input.retryGeneration,
+	});
+	reactAdapterDiagnostics.reportReactAdapterDiagnostic(
+		reactAdapterDiagnostics.createErrorDiagnostic(event),
+		input.configuration,
+	);
+	return input.cause;
+}
+
+/** Doručí committed retry event nejvýše jednou volajícímu boundary lifecycle. */
+export function dispatchOutletRetryCallback<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	input: OutletRetryCallbackInput<Point>,
+): void {
+	if (input.onRetry === undefined || !input.isCurrent()) {
+		return;
+	}
+	const event: OutletRetryEvent = Object.freeze({
+		boundaryId: input.boundaryId,
+		contributionId: input.contribution.contributionId,
+		outletId: input.outletId,
+		pointId: input.point.pointId,
+		registrationId: input.registrationId,
+		retryGeneration: input.retryGeneration,
+	});
+	callGuardedOutletCallback(input.onRetry, event, input);
+}
+
+/** Normalizuje React component stack bez synthetic prázdného pole. */
+export function normalizeReactComponentStack(value: unknown): string | undefined {
+	if (typeof value !== "string") {
+		return undefined;
+	}
+	const normalized = value.replaceAll("\r\n", "\n").trim();
+	return normalized.length === 0 ? undefined : normalized;
+}