@peax/consent-core 0.6.0

package/dist/enforcement/integration.d.ts

@@ -0,0 +1,230 @@
+import * as z from 'zod/mini';
+
+/** Disjoint category/use decisions for one scope actually presented to the user. */
+declare type BatchCommand = z.infer<typeof consentDecisionsCommandSchema>;
+
+/** Records choices only for category members in userConsentedPolicy, not future members. */
+declare type CategoryConsentCommand = z.infer<typeof categoryConsentCommandSchema>;
+
+declare const categoryConsentCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    categoryId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+/** userConsentedPolicy is the scope shown for this decision, including a denial. */
+declare type ConsentDecisionCommand = z.infer<typeof consentDecisionCommandSchema>;
+
+declare const consentDecisionCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    useId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+declare type ConsentDecisionsCommand = Readonly<Omit<BatchCommand, 'decisions'> & {
+    decisions: readonly ExclusiveTarget<BatchCommand['decisions'][number]>[];
+}>;
+
+declare const consentDecisionsCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    decisions: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniUnion<readonly [z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>, z.ZodMiniReadonly<z.ZodMiniObject<{
+        categoryId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>]>>>;
+}, z.core.$strict>>;
+
+declare type ConsentDeniedReason = 'unknown-use' | 'undecided' | 'denied' | 'consent-version-mismatch';
+
+declare type ConsentEvaluation = Readonly<{
+    allowed: true;
+}> | Readonly<{
+    allowed: false;
+    reason: ConsentDeniedReason;
+}>;
+
+export declare type ConsentIntegrationActivation = Readonly<{
+    /** Called when consent stops allowing this use or the manager is disposed. */
+    deactivate: (reason: IntegrationDeactivationReason) => void | Promise<void>;
+    /** Executed code cannot be undone; a fresh page is required after deactivation. */
+    reloadOnDeactivate?: boolean;
+}>;
+
+export declare type ConsentIntegrationDefinition = Readonly<{
+    id: string;
+    useId: string;
+    activate: (signal: AbortSignal) => ConsentIntegrationActivation | Promise<ConsentIntegrationActivation>;
+    /** Optional bridge for an SDK the application initialized before this manager started. */
+    onBlocked?: () => void;
+    /** Conservatively require a reload if activation fails after partial SDK initialization. */
+    reloadOnError?: boolean;
+}>;
+
+export declare type ConsentIntegrationManager = Readonly<{
+    /** Listener failures are reported after the pass; successfully started work is not rolled back. */
+    start: () => void;
+    getStatus: (id: string) => ConsentIntegrationStatus;
+    /** After disposal begins, returns a no-op unsubscribe without retaining the listener. */
+    subscribe: (listener: () => void) => () => void;
+    /** Aborts/waits for all hooks and clears listeners before reporting notification failures. Never reloads. */
+    dispose: () => Promise<void>;
+}>;
+
+export declare type ConsentIntegrationManagerOptions = Readonly<{
+    consent: Pick<ConsentRuntime, 'evaluate' | 'subscribe'>;
+    integrations: readonly ConsentIntegrationDefinition[];
+}>;
+
+export declare type ConsentIntegrationStatus = Readonly<{
+    state: 'idle' | 'blocked' | 'activating' | 'active' | 'error' | 'reload-required' | 'disposed';
+    reloadRequired: boolean;
+    error?: unknown;
+}>;
+
+declare type ConsentPolicy = z.infer<typeof consentPolicySchema>;
+
+declare const consentPolicySchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        title: z.ZodMiniString<string>;
+        description: z.ZodMiniString<string>;
+    }, z.core.$strict>>>>;
+    uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        serviceId: z.ZodMiniString<string>;
+        categoryId: z.ZodMiniString<string>;
+        purposeId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** A current use with no decision or a grant for a different consent version. */
+declare type ConsentRequirement = Readonly<{
+    useId: string;
+    categoryId: string;
+    /** The version required by the current policy for this use. */
+    consentVersion: number;
+    reason: 'undecided' | 'consent-version-mismatch';
+}>;
+
+/** In-memory runtime; methods can be passed as callbacks without binding. */
+declare type ConsentRuntime = Readonly<{
+    getSnapshot: () => ConsentSnapshot;
+    evaluate: (useId: string) => ConsentEvaluation;
+    /** Includes undecided uses and version-mismatched grants, not explicit denials. */
+    getMismatchedConsent: () => readonly ConsentRequirement[];
+    /**
+     * Replace all choices from trusted persistence, preserving unknown uses and recorded versions.
+     * Validation checks structure, not evidence of user consent; use decision methods for new choices.
+     * Does not replace policy, renew versions or perform I/O. Effective changes notify existing guards.
+     */
+    restoreState: (state: unknown) => ValidationResult<ConsentSnapshot>;
+    setConsentDecision: (command: ConsentDecisionCommand) => ValidationResult<ConsentSnapshot>;
+    setCategoryConsent: (command: CategoryConsentCommand) => ValidationResult<ConsentSnapshot>;
+    /** Validates all targets before one commit; observer errors can throw after that commit. */
+    setConsentDecisions: (command: ConsentDecisionsCommand) => ValidationResult<ConsentSnapshot>;
+    updatePolicy: (currentAppPolicy: unknown) => ValidationResult<ConsentSnapshot>;
+    subscribe: (listener: () => void) => () => void;
+}>;
+
+/** One active app policy and recorded choices; not a history of policies shown to users. */
+declare type ConsentSnapshot = Readonly<{
+    currentAppPolicy: ConsentPolicy;
+    state: ConsentState;
+}>;
+
+declare type ConsentState = z.infer<typeof consentStateSchema>;
+
+declare const consentStateSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    choices: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** Starts only declared integrations whose exact use is currently allowed. */
+export declare function createConsentIntegrationManager({ consent, integrations, }: ConsentIntegrationManagerOptions): ConsentIntegrationManager;
+
+declare type ExclusiveTarget<T> = T extends {
+    useId: string;
+} ? T & {
+    readonly categoryId?: never;
+} : T & {
+    readonly useId?: never;
+};
+
+export declare type IntegrationDeactivationReason = 'blocked' | 'disposed';
+
+/** A validation issue without a copy of the rejected input. */
+declare type ValidationIssue = Readonly<{
+    code: string;
+    path: readonly (string | number)[];
+    message: string;
+}>;
+
+declare type ValidationResult<T> = Readonly<{
+    success: true;
+    data: T;
+}> | Readonly<{
+    success: false;
+    issues: readonly ValidationIssue[];
+}>;
+
+export { }

package/dist/enforcement/integration.js

@@ -0,0 +1,181 @@
+import { t as requireConsent } from "../validate-D16G7mdG.js";
+//#region src/enforcement/integration/createConsentIntegrationManager.ts
+var status = (state, reloadRequired = false, error) => Object.freeze({
+	state,
+	reloadRequired,
+	...error === void 0 ? {} : { error }
+});
+/** Starts only declared integrations whose exact use is currently allowed. */
+function createConsentIntegrationManager({ consent, integrations }) {
+	requireConsent(consent);
+	const entries = /* @__PURE__ */ new Map();
+	for (const definition of integrations) {
+		if (!definition || typeof definition.id !== "string" || !definition.id.trim()) throw new TypeError("Expected a non blank integration ID.");
+		if (typeof definition.useId !== "string" || !definition.useId.trim() || typeof definition.activate !== "function") throw new TypeError("Expected an integration use ID and activate function.");
+		if (entries.has(definition.id)) throw new TypeError(`Duplicate integration ID: ${definition.id}`);
+		entries.set(definition.id, {
+			definition,
+			status: status("idle"),
+			generation: 0,
+			blocked: false,
+			controller: void 0,
+			activation: void 0,
+			pending: void 0,
+			cleanup: void 0
+		});
+	}
+	let started = false;
+	let disposed = false;
+	const listeners = /* @__PURE__ */ new Set();
+	let unsubscribe;
+	function publish(entry, next, failures) {
+		if (entry.status.state === next.state && entry.status.reloadRequired === next.reloadRequired && entry.status.error === next.error) return;
+		entry.status = next;
+		const errors = [];
+		for (const listener of [...listeners]) {
+			if (!listeners.has(listener)) continue;
+			try {
+				listener();
+			} catch (error) {
+				errors.push(error);
+			}
+		}
+		if (!errors.length) return;
+		if (failures) failures.push(...errors);
+		else {
+			const current = entry.status;
+			entry.status = status(current.state, current.reloadRequired, new AggregateError([...current.error === void 0 ? [] : [current.error], ...errors], "Integration notification failed."));
+		}
+	}
+	function reportTaskError(entry, error, failures) {
+		publish(entry, status(disposed ? "disposed" : "error", true, error), failures);
+	}
+	function completeTask(entry, key, task) {
+		return task.then(() => {
+			entry[key] = void 0;
+			if (!disposed) reconcile(entry);
+		}).catch((error) => {
+			entry[key] = void 0;
+			reportTaskError(entry, error);
+		});
+	}
+	function deactivate(entry, reason, failures) {
+		entry.generation += 1;
+		entry.controller?.abort();
+		entry.controller = void 0;
+		const activation = entry.activation;
+		entry.activation = void 0;
+		const reloadRequired = entry.status.reloadRequired || Boolean(activation?.reloadOnDeactivate);
+		publish(entry, status(reason === "disposed" ? "disposed" : reloadRequired ? "reload-required" : "blocked", reloadRequired), failures);
+		if (!activation) return;
+		try {
+			entry.cleanup = completeTask(entry, "cleanup", Promise.resolve(activation.deactivate(reason)));
+		} catch (error) {
+			reportTaskError(entry, error, failures);
+		}
+	}
+	function activate(entry, failures) {
+		const controller = new AbortController();
+		entry.controller = controller;
+		const generation = ++entry.generation;
+		publish(entry, status("activating"), failures);
+		entry.pending = completeTask(entry, "pending", (async () => {
+			try {
+				const activation = await Promise.resolve().then(() => {
+					if (controller.signal.aborted || !consent.evaluate(entry.definition.useId).allowed) return { deactivate: () => {} };
+					return entry.definition.activate(controller.signal);
+				});
+				if (!activation || typeof activation.deactivate !== "function") throw new TypeError("Integration activation must return a deactivation hook.");
+				if (disposed || generation !== entry.generation || controller.signal.aborted || !consent.evaluate(entry.definition.useId).allowed) {
+					if (activation.reloadOnDeactivate) publish(entry, status(disposed ? "disposed" : "reload-required", true));
+					try {
+						await activation.deactivate(disposed ? "disposed" : "blocked");
+					} catch (error) {
+						reportTaskError(entry, error);
+					}
+					return;
+				}
+				entry.activation = activation;
+				publish(entry, status("active"));
+			} catch (error) {
+				if (disposed || generation !== entry.generation || controller.signal.aborted) return;
+				publish(entry, status("error", entry.status.reloadRequired || Boolean(entry.definition.reloadOnError), error));
+			}
+		})());
+	}
+	function reconcile(entry, failures) {
+		if (!started || disposed) return;
+		if (!consent.evaluate(entry.definition.useId).allowed) {
+			let blockedError;
+			if (!entry.blocked) {
+				entry.blocked = true;
+				try {
+					entry.definition.onBlocked?.();
+				} catch (error) {
+					blockedError = error;
+				}
+			}
+			if (entry.activation || entry.controller) deactivate(entry, "blocked", failures);
+			else if (entry.status.state !== "error") publish(entry, status(entry.status.reloadRequired ? "reload-required" : "blocked", entry.status.reloadRequired), failures);
+			if (blockedError !== void 0) publish(entry, status("error", true, blockedError), failures);
+			return;
+		}
+		entry.blocked = false;
+		if (entry.status.reloadRequired || entry.status.state === "error" || entry.activation || entry.controller || entry.pending || entry.cleanup) return;
+		activate(entry, failures);
+	}
+	function reconcileAll() {
+		const failures = [];
+		for (const entry of entries.values()) try {
+			reconcile(entry, failures);
+		} catch (error) {
+			failures.push(error);
+		}
+		if (failures.length) throw new AggregateError(failures, "Integration lifecycle failed after reconciliation.");
+	}
+	return Object.freeze({
+		start() {
+			if (disposed) throw new Error("Integration manager is disposed.");
+			if (started) return;
+			started = true;
+			unsubscribe = consent.subscribe(reconcileAll);
+			reconcileAll();
+		},
+		getStatus(id) {
+			const entry = entries.get(id);
+			if (!entry) throw new TypeError(`Unknown integration ID: ${id}`);
+			return entry.status;
+		},
+		subscribe(listener) {
+			if (typeof listener !== "function") throw new TypeError("Expected a status listener.");
+			if (disposed) return () => {};
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			const failures = [];
+			try {
+				unsubscribe?.();
+			} catch (error) {
+				failures.push(error);
+			}
+			for (const entry of entries.values()) try {
+				deactivate(entry, "disposed", failures);
+			} catch (error) {
+				failures.push(error);
+			}
+			try {
+				await Promise.all([...entries.values()].flatMap((entry) => [entry.pending, entry.cleanup]));
+			} finally {
+				listeners.clear();
+			}
+			if (failures.length) throw new AggregateError(failures, "Integration lifecycle failed after disposal.");
+		}
+	});
+}
+//#endregion
+export { createConsentIntegrationManager };

package/dist/enforcement/markup.d.ts

@@ -0,0 +1,214 @@
+import * as z from 'zod/mini';
+
+/** Disjoint category/use decisions for one scope actually presented to the user. */
+declare type BatchCommand = z.infer<typeof consentDecisionsCommandSchema>;
+
+/** Records choices only for category members in userConsentedPolicy, not future members. */
+declare type CategoryConsentCommand = z.infer<typeof categoryConsentCommandSchema>;
+
+declare const categoryConsentCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    categoryId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+/** userConsentedPolicy is the scope shown for this decision, including a denial. */
+declare type ConsentDecisionCommand = z.infer<typeof consentDecisionCommandSchema>;
+
+declare const consentDecisionCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    useId: z.ZodMiniString<string>;
+    decision: z.ZodMiniEnum<{
+        granted: "granted";
+        denied: "denied";
+    }>;
+}, z.core.$strict>>;
+
+declare type ConsentDecisionsCommand = Readonly<Omit<BatchCommand, 'decisions'> & {
+    decisions: readonly ExclusiveTarget<BatchCommand['decisions'][number]>[];
+}>;
+
+declare const consentDecisionsCommandSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    userConsentedPolicy: z.ZodMiniReadonly<z.ZodMiniObject<{
+        purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            title: z.ZodMiniString<string>;
+            description: z.ZodMiniString<string>;
+        }, z.core.$strict>>>>;
+        uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+            id: z.ZodMiniString<string>;
+            serviceId: z.ZodMiniString<string>;
+            categoryId: z.ZodMiniString<string>;
+            purposeId: z.ZodMiniString<string>;
+            consentVersion: z.ZodMiniInt;
+        }, z.core.$strict>>>>;
+    }, z.core.$strict>>;
+    decisions: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniUnion<readonly [z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>, z.ZodMiniReadonly<z.ZodMiniObject<{
+        categoryId: z.ZodMiniString<string>;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>]>>>;
+}, z.core.$strict>>;
+
+declare type ConsentDeniedReason = 'unknown-use' | 'undecided' | 'denied' | 'consent-version-mismatch';
+
+declare type ConsentEvaluation = Readonly<{
+    allowed: true;
+}> | Readonly<{
+    allowed: false;
+    reason: ConsentDeniedReason;
+}>;
+
+export declare type ConsentMarkupGuard = Readonly<{
+    /** Failed initial scans roll back resources and preserve the original error; retry never replays scripts. */
+    start: () => void;
+    /** Sticky until page reload; removing an executed script cannot undo it. */
+    getReloadRequiredUseIds: () => readonly string[];
+    /** After disposal, returns a no-op unsubscribe without retaining the listener. */
+    subscribe: (listener: () => void) => () => void;
+    /** Cleans up every managed resource before throwing collected listener/cleanup errors. */
+    dispose: () => void;
+}>;
+
+export declare type ConsentMarkupIssue = Readonly<{
+    element: HTMLScriptElement | HTMLIFrameElement;
+    reason: 'invalid-marker' | 'load-error';
+    error: unknown;
+}>;
+
+export declare type ConsentMarkupOptions = Readonly<{
+    consent: Pick<ConsentRuntime, 'evaluate' | 'subscribe'>;
+    /** Only descendants of this document or connected element are managed. */
+    root: Document | HTMLElement;
+    onIssue?: (issue: ConsentMarkupIssue) => void;
+}>;
+
+declare type ConsentPolicy = z.infer<typeof consentPolicySchema>;
+
+declare const consentPolicySchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    purposes: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        title: z.ZodMiniString<string>;
+        description: z.ZodMiniString<string>;
+    }, z.core.$strict>>>>;
+    uses: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        serviceId: z.ZodMiniString<string>;
+        categoryId: z.ZodMiniString<string>;
+        purposeId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** A current use with no decision or a grant for a different consent version. */
+declare type ConsentRequirement = Readonly<{
+    useId: string;
+    categoryId: string;
+    /** The version required by the current policy for this use. */
+    consentVersion: number;
+    reason: 'undecided' | 'consent-version-mismatch';
+}>;
+
+/** In-memory runtime; methods can be passed as callbacks without binding. */
+declare type ConsentRuntime = Readonly<{
+    getSnapshot: () => ConsentSnapshot;
+    evaluate: (useId: string) => ConsentEvaluation;
+    /** Includes undecided uses and version-mismatched grants, not explicit denials. */
+    getMismatchedConsent: () => readonly ConsentRequirement[];
+    /**
+     * Replace all choices from trusted persistence, preserving unknown uses and recorded versions.
+     * Validation checks structure, not evidence of user consent; use decision methods for new choices.
+     * Does not replace policy, renew versions or perform I/O. Effective changes notify existing guards.
+     */
+    restoreState: (state: unknown) => ValidationResult<ConsentSnapshot>;
+    setConsentDecision: (command: ConsentDecisionCommand) => ValidationResult<ConsentSnapshot>;
+    setCategoryConsent: (command: CategoryConsentCommand) => ValidationResult<ConsentSnapshot>;
+    /** Validates all targets before one commit; observer errors can throw after that commit. */
+    setConsentDecisions: (command: ConsentDecisionsCommand) => ValidationResult<ConsentSnapshot>;
+    updatePolicy: (currentAppPolicy: unknown) => ValidationResult<ConsentSnapshot>;
+    subscribe: (listener: () => void) => () => void;
+}>;
+
+/** One active app policy and recorded choices; not a history of policies shown to users. */
+declare type ConsentSnapshot = Readonly<{
+    currentAppPolicy: ConsentPolicy;
+    state: ConsentState;
+}>;
+
+declare type ConsentState = z.infer<typeof consentStateSchema>;
+
+declare const consentStateSchema: z.ZodMiniReadonly<z.ZodMiniObject<{
+    choices: z.ZodMiniReadonly<z.ZodMiniArray<z.ZodMiniReadonly<z.ZodMiniObject<{
+        useId: z.ZodMiniString<string>;
+        consentVersion: z.ZodMiniInt;
+        decision: z.ZodMiniEnum<{
+            granted: "granted";
+            denied: "denied";
+        }>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+
+/** Framework-neutral, opt-in management of inert marked nodes only. */
+export declare function createConsentMarkupGuard({ consent, root, onIssue }: ConsentMarkupOptions): ConsentMarkupGuard;
+
+declare type ExclusiveTarget<T> = T extends {
+    useId: string;
+} ? T & {
+    readonly categoryId?: never;
+} : T & {
+    readonly useId?: never;
+};
+
+/** A validation issue without a copy of the rejected input. */
+declare type ValidationIssue = Readonly<{
+    code: string;
+    path: readonly (string | number)[];
+    message: string;
+}>;
+
+declare type ValidationResult<T> = Readonly<{
+    success: true;
+    data: T;
+}> | Readonly<{
+    success: false;
+    issues: readonly ValidationIssue[];
+}>;
+
+export { }