@primafuture/contrib-kit-react 1.0.0

package/src/internal/adapter-scope.ts

@@ -0,0 +1,500 @@
+import type * as contribKitCore from "@primafuture/contrib-kit-core";
+
+import * as adapterConfiguration from "./adapter-configuration.js";
+import * as adapterRegistryBridge from "./adapter-registry-bridge.js";
+import * as adapterRegistryProtocol from "./adapter-registry-protocol.js";
+import * as outletCommitLease from "./outlet-commit-lease.js";
+import * as reactAdapterError from "../react-adapter-error.js";
+
+/** Deterministický microtask seam používaný lifecycle grace periodou. */
+export type AdapterScopeMicrotaskScheduler = (callback: () => void) => void;
+
+/** Best-effort seam pro interní lifecycle diagnostiku. */
+export type AdapterScopeLifecycleReporter = (
+	error: reactAdapterError.ReactAdapterError,
+) => void;
+
+/** Idempotentní fyzický cleanup spuštěný až po zneplatnění celé scope epochy. */
+export type AdapterScopeAbortDispatch = () => void;
+
+/** Synchronní invalidace jednoho epoch-owned abortable resource. */
+export type AdapterScopeAbortableInvalidation = () => AdapterScopeAbortDispatch;
+
+/** Pure konfigurace jedné provider generation bez resource ownershipu. */
+export interface AdapterScopeGeneration {
+	/** Default registry protocol provideru; explicitní hook registry jej nepřepisuje. */
+	readonly defaultProtocol: adapterRegistryProtocol.AdapterRegistryProtocolSnapshot;
+	/** Efektivní nearest-provider konfigurace všech tří nezávislých os. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+}
+
+/** Interní external-store kontrakt připravený pro budoucí React hook. */
+export interface AdapterExternalStoreBinding {
+	/** Commit-time acquire point consumer membership. */
+	readonly subscribe: (
+		listener: adapterRegistryBridge.AdapterExternalStoreListener,
+	) => contribKitCore.Unsubscribe;
+	/** Pure client snapshot selector bez resource creation. */
+	readonly getSnapshot: () => adapterRegistryBridge.AdapterExternalStoreSnapshot;
+	/** Package-constant server/hydration snapshot selector. */
+	readonly getServerSnapshot: () => typeof adapterRegistryBridge.ADAPTER_SERVER_SNAPSHOT;
+	/** První bridge fault pro budoucí render-time error projection. */
+	readonly readFault: () => reactAdapterError.ReactAdapterError | undefined;
+	/** Poslední známý committed registry lifecycle stav. */
+	readonly readRegistryState: () => contribKitCore.ExtensionRegistryState;
+}
+
+/** Volitelné interní host seams bez veřejného package kontraktu. */
+export interface AdapterScopeRuntimeOptions {
+	/** Vlastní deterministický scheduler pro lifecycle testy. */
+	readonly scheduleMicrotask?: AdapterScopeMicrotaskScheduler;
+	/** Bezpečný lifecycle reporter; jeho failure se vždy pohltí. */
+	readonly reportLifecycleFailure?: AdapterScopeLifecycleReporter;
+}
+
+/** Stav jedné monotonické committed scope epochy. */
+type AdapterScopeEpochState = "active" | "grace" | "retired";
+
+/** Resource ownership oddělený od stabilní provider scope identity. */
+interface AdapterScopeEpoch {
+	/** Monotonická identita bez veřejného formátového kontraktu. */
+	readonly epoch: number;
+	/** Pure provider generation, kterou epocha materializuje. */
+	readonly generation: AdapterScopeGeneration;
+	/** Nejvýše jeden bridge pro každou exact raw registry referenci. */
+	readonly bridges: Map<object, adapterRegistryBridge.AdapterRegistryBridge>;
+	/** Pending abortable resources, které musí být stale před prvním abortem. */
+	readonly abortables: Set<AdapterScopeAbortableRecord>;
+	/** Počet aktivních provider owner leases. */
+	ownerCount: number;
+	/** Current lifecycle stav epochy. */
+	state: AdapterScopeEpochState;
+	/** Token rušící stale grace finalizer. */
+	finalizeToken: number;
+}
+
+/** Jedna odpojitelná invalidace vlastněná přesnou resource epochou. */
+interface AdapterScopeAbortableRecord {
+	/** False po explicitním odpojení nebo epoch retirementu. */
+	active: boolean;
+	/** Vrátí fyzický abort až po synchronním odstranění resource autority. */
+	readonly invalidate: AdapterScopeAbortableInvalidation;
+}
+
+/**
+ * Použije platformní microtask bez importu Node nebo DOM ambient API.
+ */
+function schedulePlatformMicrotask(callback: () => void): void {
+	queueMicrotask(callback);
+}
+
+/**
+ * Vytvoří stabilní lifecycle chybu bez raw registry nebo config callbacků.
+ */
+function createStaleScopeError(): reactAdapterError.ReactAdapterError {
+	return new reactAdapterError.ReactAdapterError(
+		"REACT_ADAPTER_DISPOSED",
+		"The React adapter scope epoch is no longer active.",
+		{ details: { field: "scope.epoch", phase: "lifecycle" } },
+	);
+}
+
+/**
+ * Pure factory provider generation; resource vzniká až committed acquire cestou.
+ */
+export function createAdapterScopeGeneration(
+	defaultProtocol: adapterRegistryProtocol.AdapterRegistryProtocolSnapshot,
+	configuration: adapterConfiguration.AdapterScopeConfiguration,
+): AdapterScopeGeneration {
+	return Object.freeze({ defaultProtocol, configuration });
+}
+
+/**
+ * Porovná generation podle raw host capabilities, nikoli nových wrapper referencí.
+ */
+export function isSameAdapterScopeGeneration(
+	left: AdapterScopeGeneration,
+	right: AdapterScopeGeneration,
+): boolean {
+	return left.defaultProtocol.rawRegistry === right.defaultProtocol.rawRegistry
+		&& left.defaultProtocol.registryId === right.defaultProtocol.registryId
+		&& adapterConfiguration.isSameAdapterScopeConfiguration(
+			left.configuration,
+			right.configuration,
+		);
+}
+
+/**
+ * Stabilní provider-scope identity s oddělenými, monotonickými resource epochami.
+ */
+export class AdapterScopeRuntime {
+	/** Read-once scheduler používaný všemi epochami scope. */
+	readonly #scheduleMicrotask: AdapterScopeMicrotaskScheduler;
+	/** Read-once best-effort lifecycle reporter. */
+	readonly #reportLifecycleFailure: AdapterScopeLifecycleReporter | undefined;
+	/** Poslední monotonická epoch identity. */
+	#nextEpoch = 0;
+	/** Právě aktivní nebo Strict-grace resource epocha. */
+	#currentEpoch: AdapterScopeEpoch | undefined;
+	/** Opaque committed attempty již doručené diagnostickému sinku. */
+	readonly #reportedDiagnosticAttempts = new WeakSet<object>();
+	/** Scope-local committed owner identities bez process-global historie. */
+	readonly #commitLeases: outletCommitLease.OutletCommitLeaseRegistry;
+
+	/** Vytvoří resource-free scope; žádný Core read ani subscribe zde nevzniká. */
+	public constructor(options: AdapterScopeRuntimeOptions = {}) {
+		this.#scheduleMicrotask = options.scheduleMicrotask ?? schedulePlatformMicrotask;
+		this.#reportLifecycleFailure = options.reportLifecycleFailure;
+		this.#commitLeases = new outletCommitLease.OutletCommitLeaseRegistry(
+			(callback: () => void): void => {
+				this.#schedule(callback);
+			},
+		);
+	}
+
+	/** Vrátí current monotonické číslo pouze pro deterministickou interní evidenci. */
+	public readCurrentEpoch(): number | undefined {
+		return this.#currentEpoch?.epoch;
+	}
+
+	/** Vrátí current pure provider generation bez její aktivace. */
+	public readCurrentGeneration(): AdapterScopeGeneration | undefined {
+		return this.#currentEpoch?.generation;
+	}
+
+	/** Ověří, že přesná generation právě vlastní aktivní committed epochu. */
+	public isGenerationActive(generation: AdapterScopeGeneration): boolean {
+		const current = this.#currentEpoch;
+		return current !== undefined
+			&& current.state === "active"
+			&& isSameAdapterScopeGeneration(current.generation, generation);
+	}
+
+	/** Atomicky přijme první committed diagnostiku jednoho opaque attempt tokenu. */
+	public claimDiagnosticAttempt(token: object): boolean {
+		if (this.#reportedDiagnosticAttempts.has(token)) {
+			return false;
+		}
+		this.#reportedDiagnosticAttempts.add(token);
+		return true;
+	}
+
+	/** Vrátí počet scope-local owner records pouze pro interní lifecycle důkaz. */
+	public readRetainedCommitOwnerCount(): number {
+		return this.#commitLeases.readRetainedOwnerCount();
+	}
+
+	/**
+	 * Commit-time acquire outlet nebo boundary identity v exact current epoše.
+	 */
+	public acquireCommitLease(
+		generation: AdapterScopeGeneration,
+		kind: outletCommitLease.OutletCommitOwnerKind,
+		token: object,
+	): outletCommitLease.OutletCommitLease {
+		const epoch = this.#acquireEpoch(generation);
+		return this.#commitLeases.acquire(
+			epoch.epoch,
+			kind,
+			token,
+			(epochNumber: number): boolean => {
+				return this.#currentEpoch === epoch
+					&& epoch.epoch === epochNumber
+					&& epoch.state === "active"
+					&& isSameAdapterScopeGeneration(epoch.generation, generation);
+			},
+		);
+	}
+
+	/**
+	 * Commit-time owner acquire. Strict reacquire stejné generation zachová epochu.
+	 */
+	public acquireOwner(generation: AdapterScopeGeneration): contribKitCore.Unsubscribe {
+		const epoch = this.#acquireEpoch(generation);
+		epoch.ownerCount += 1;
+		let active = true;
+		const scope = this;
+		/** Idempotentně uvolní právě jednu provider owner lease. */
+		function releaseOwner(): void {
+			if (!active) {
+				return;
+			}
+			active = false;
+			epoch.ownerCount -= 1;
+			if (epoch.ownerCount === 0 && scope.#currentEpoch === epoch) {
+				scope.#beginEpochGrace(epoch);
+			}
+		}
+
+		return releaseOwner;
+	}
+
+	/**
+	 * Připojí committed abortable resource k právě existující scope epoše.
+	 *
+	 * Registrace nikdy neaktivuje novou epochu. Pokud owning epocha již zmizela,
+	 * resource se okamžitě zneplatní a uklidí bez možnosti pozdějšího startu.
+	 */
+	public registerEpochAbortable(
+		generation: AdapterScopeGeneration,
+		invalidate: AdapterScopeAbortableInvalidation,
+	): contribKitCore.Unsubscribe {
+		const epoch = this.#currentEpoch;
+		if (epoch === undefined
+			|| epoch.state === "retired"
+			|| !isSameAdapterScopeGeneration(epoch.generation, generation)) {
+			this.#runAbortDispatch(this.#callAbortableInvalidation(invalidate));
+			return (): void => {};
+		}
+		const owningEpoch = epoch;
+
+		const record: AdapterScopeAbortableRecord = { active: true, invalidate };
+		owningEpoch.abortables.add(record);
+		let attached = true;
+		/** Odpojí settled nebo lokálně invalidovaný resource bez druhého cleanupu. */
+		function unregisterEpochAbortable(): void {
+			if (!attached) {
+				return;
+			}
+			attached = false;
+			record.active = false;
+			owningEpoch.abortables.delete(record);
+		}
+		return unregisterEpochAbortable;
+	}
+
+	/**
+	 * Vytvoří pure external-store closures; žádný bridge ani cell zatím nevzniká.
+	 */
+	public createExternalStore(
+		generation: AdapterScopeGeneration,
+		protocol: adapterRegistryProtocol.AdapterRegistryProtocolSnapshot,
+		point: contribKitCore.AnyExtensionPoint,
+	): AdapterExternalStoreBinding {
+		const scope = this;
+		/** Najde bridge pouze v exact current generation bez cache mutace. */
+		function peekBridge(): adapterRegistryBridge.AdapterRegistryBridge | undefined {
+			const epoch = scope.#currentEpoch;
+			if (epoch === undefined
+				|| epoch.state === "retired"
+				|| !isSameAdapterScopeGeneration(epoch.generation, generation)) {
+				return undefined;
+			}
+			return epoch.bridges.get(protocol.rawRegistry);
+		}
+
+		return Object.freeze({
+			/** Commit-time scope a bridge acquire. */
+			subscribe(listener: adapterRegistryBridge.AdapterExternalStoreListener): contribKitCore.Unsubscribe {
+				if (typeof listener !== "function") {
+					throw new reactAdapterError.ReactAdapterError(
+						"REACT_INVALID_ARGUMENT",
+						"External-store listener must be callable.",
+						{ details: { field: "listener", phase: "lifecycle" } },
+					);
+				}
+				const epoch = scope.#acquireEpoch(generation);
+				const bridge = scope.#getOrCreateBridge(epoch, protocol);
+				return bridge.subscribe(point, listener);
+			},
+			/** Pure committed-cell lookup s global pre-subscribe fallbackem. */
+			getSnapshot(): adapterRegistryBridge.AdapterExternalStoreSnapshot {
+				const token = peekBridge()?.peekSnapshot(point);
+				return token ?? adapterRegistryProtocol.createAdapterRegistrySnapshotToken(protocol);
+			},
+			/** Constant SSR/hydration sentinel bez request-local dat. */
+			getServerSnapshot(): typeof adapterRegistryBridge.ADAPTER_SERVER_SNAPSHOT {
+				return adapterRegistryBridge.ADAPTER_SERVER_SNAPSHOT;
+			},
+			/** Pure fault lookup pro budoucí hook error mapping. */
+			readFault(): reactAdapterError.ReactAdapterError | undefined {
+				return peekBridge()?.readFault();
+			},
+			/** Pure committed bridge state nebo initial protocol stav. */
+			readRegistryState(): contribKitCore.ExtensionRegistryState {
+				return peekBridge()?.readRegistryState() ?? protocol.initialState;
+			},
+		});
+	}
+
+	/** Aktivuje novou epochu nebo zruší Strict grace té current. */
+	#acquireEpoch(generation: AdapterScopeGeneration): AdapterScopeEpoch {
+		const current = this.#currentEpoch;
+		if (current !== undefined
+			&& current.state !== "retired"
+			&& isSameAdapterScopeGeneration(current.generation, generation)) {
+			if (current.state === "grace") {
+				current.finalizeToken += 1;
+				current.state = "active";
+				for (const bridge of current.bridges.values()) {
+					bridge.reactivateEpoch();
+				}
+			}
+			return current;
+		}
+
+		if (current !== undefined && current.state !== "retired") {
+			this.#retireEpoch(current);
+		}
+
+		this.#nextEpoch += 1;
+		const created: AdapterScopeEpoch = {
+			epoch: this.#nextEpoch,
+			generation,
+			bridges: new Map(),
+			abortables: new Set(),
+			ownerCount: 0,
+			state: "active",
+			finalizeToken: 0,
+		};
+		this.#currentEpoch = created;
+		return created;
+	}
+
+	/** Vytvoří nejvýše jeden bridge pro exact epoch + raw registry dvojici. */
+	#getOrCreateBridge(
+		epoch: AdapterScopeEpoch,
+		protocol: adapterRegistryProtocol.AdapterRegistryProtocolSnapshot,
+	): adapterRegistryBridge.AdapterRegistryBridge {
+		const existing = epoch.bridges.get(protocol.rawRegistry);
+		if (existing !== undefined) {
+			return existing;
+		}
+
+		let created: adapterRegistryBridge.AdapterRegistryBridge;
+		created = new adapterRegistryBridge.AdapterRegistryBridge(protocol, {
+			checkpoint: (): void => {
+				if (this.#currentEpoch !== epoch || epoch.state !== "active") {
+					throw createStaleScopeError();
+				}
+			},
+			canFinalizeDetach: (): boolean => {
+				return this.#currentEpoch === epoch && epoch.state === "active";
+			},
+			scheduleMicrotask: this.#scheduleMicrotask,
+			reportLifecycleFailure: (error: reactAdapterError.ReactAdapterError): void => {
+				this.#reportFailure(error);
+			},
+			onDetached: (bridge: adapterRegistryBridge.AdapterRegistryBridge): void => {
+				if (epoch.bridges.get(protocol.rawRegistry) === bridge) {
+					epoch.bridges.delete(protocol.rawRegistry);
+				}
+			},
+		});
+		epoch.bridges.set(protocol.rawRegistry, created);
+		return created;
+	}
+
+	/** Synchronně invaliduje epochu a poté naplánuje Strict-grace finalitu. */
+	#beginEpochGrace(epoch: AdapterScopeEpoch): void {
+		if (epoch.state !== "active") {
+			return;
+		}
+		epoch.state = "grace";
+		epoch.finalizeToken += 1;
+		const token = epoch.finalizeToken;
+		this.#commitLeases.invalidateEpoch(epoch.epoch);
+		for (const bridge of epoch.bridges.values()) {
+			bridge.prepareEpochDeactivation();
+		}
+
+		this.#schedule((): void => {
+			if (this.#currentEpoch !== epoch
+				|| epoch.state !== "grace"
+				|| token !== epoch.finalizeToken) {
+				return;
+			}
+			this.#retireEpoch(epoch);
+		});
+	}
+
+	/** Terminálně označí epochu stale před prvním fyzickým unsubscribe. */
+	#retireEpoch(epoch: AdapterScopeEpoch): void {
+		if (epoch.state === "retired") {
+			return;
+		}
+		epoch.state = "retired";
+		epoch.finalizeToken += 1;
+		if (this.#currentEpoch === epoch) {
+			this.#currentEpoch = undefined;
+		}
+		this.#commitLeases.retireEpoch(epoch.epoch);
+		const abortDispatches: AdapterScopeAbortDispatch[] = [];
+		for (const record of [...epoch.abortables]) {
+			if (!record.active) {
+				continue;
+			}
+			record.active = false;
+			abortDispatches.push(this.#callAbortableInvalidation(record.invalidate));
+		}
+		epoch.abortables.clear();
+		for (const bridge of [...epoch.bridges.values()]) {
+			bridge.forceDetach();
+		}
+		epoch.bridges.clear();
+		for (const dispatchAbort of abortDispatches) {
+			this.#runAbortDispatch(dispatchAbort);
+		}
+	}
+
+	/** Izoluje vadný resource invalidator a zachová retirement ostatních resources. */
+	#callAbortableInvalidation(
+		invalidate: AdapterScopeAbortableInvalidation,
+	): AdapterScopeAbortDispatch {
+		try {
+			return invalidate();
+		} catch (cause: unknown) {
+			this.#reportFailure(new reactAdapterError.ReactAdapterError(
+				"REACT_CALLBACK_FAILED",
+				"A React adapter lifecycle invalidation callback failed.",
+				{
+					cause,
+					details: { field: "scope.abortable.invalidate", phase: "lifecycle" },
+				},
+			));
+			return (): void => {};
+		}
+	}
+
+	/** Spustí fyzický abort bez možnosti přepsat scope retirement. */
+	#runAbortDispatch(dispatchAbort: AdapterScopeAbortDispatch): void {
+		try {
+			dispatchAbort();
+		} catch (cause: unknown) {
+			this.#reportFailure(new reactAdapterError.ReactAdapterError(
+				"REACT_CALLBACK_FAILED",
+				"A React adapter lifecycle cleanup callback failed.",
+				{
+					cause,
+					details: { field: "scope.abortable.dispatch", phase: "lifecycle" },
+				},
+			));
+		}
+	}
+
+	/** Scheduler failure dokončí lifecycle synchronně a pouze diagnostikuje seam. */
+	#schedule(callback: () => void): void {
+		try {
+			this.#scheduleMicrotask(callback);
+		} catch (cause: unknown) {
+			this.#reportFailure(new reactAdapterError.ReactAdapterError(
+				"REACT_CALLBACK_FAILED",
+				"Adapter scope microtask scheduler failed.",
+				{
+					cause,
+					details: { field: "scope.scheduleMicrotask", phase: "lifecycle" },
+				},
+			));
+			callback();
+		}
+	}
+
+	/** Reporter failure nikdy neovlivní scope lifecycle. */
+	#reportFailure(error: reactAdapterError.ReactAdapterError): void {
+		try {
+			this.#reportLifecycleFailure?.(error);
+		} catch {
+			// Diagnostic seam nemá lifecycle autoritu.
+		}
+	}
+}

package/src/internal/implementation-classifier.ts

@@ -0,0 +1,59 @@
+/** Callable loader zachycený z platného structural managed-lazy descriptoru. */
+export type CapturedReactLazyLoader = (input: unknown) => unknown;
+
+/** Shallow klasifikace opaque React contribution implementation hodnoty. */
+export type ReactImplementationClassification =
+	| { readonly kind: "eager" }
+	| { readonly kind: "managedLazy"; readonly load: CapturedReactLazyLoader }
+	| { readonly kind: "invalid" };
+
+/** Lifecycle checkpoint mezi jednotlivými user-observable kroky klasifikace. */
+export type ReactImplementationClassificationCheckpoint = () => void;
+
+/** Sdílený immutable eager výsledek bez per-call mutable identity. */
+const eagerClassification: ReactImplementationClassification = Object.freeze({ kind: "eager" });
+
+/** Sdílený immutable invalid výsledek bez raw hodnoty. */
+const invalidClassification: ReactImplementationClassification = Object.freeze({ kind: "invalid" });
+
+/**
+ * Provede jedinou normativní shallow klasifikaci React implementation hodnoty.
+ *
+ * Funkce záměrně nezachytává accessor chyby. Volající hranice rozhoduje, zda je
+ * přeloží do Core validator failure nebo pozdější React render chyby.
+ */
+export function classifyReactContributionImplementation(
+	value: unknown,
+	checkpoint: ReactImplementationClassificationCheckpoint = skipReactImplementationClassificationCheckpoint,
+): ReactImplementationClassification {
+	checkpoint();
+	const eligible = typeof value === "function"
+		|| (typeof value === "object" && value !== null && !Array.isArray(value));
+	checkpoint();
+	if (!eligible) {
+		return invalidClassification;
+	}
+
+	const target = value as object;
+	const kind = Reflect.get(target, "kind", target);
+	checkpoint();
+	if (kind !== "contrib-kit-react-lazy") {
+		return eagerClassification;
+	}
+
+	const load = Reflect.get(target, "load", target);
+	checkpoint();
+	if (typeof load !== "function") {
+		return invalidClassification;
+	}
+
+	return Object.freeze({
+		kind: "managedLazy",
+		load: load as CapturedReactLazyLoader,
+	});
+}
+
+/** Výchozí checkpoint pro klasifikace bez consumer lifecycle autority. */
+function skipReactImplementationClassificationCheckpoint(): void {
+	// Core activation validator žádný adapter state nepublikuje.
+}