@fedify/vocab-runtime 2.4.0-pr.936.41 → 2.4.1

package/dist/internal/signed-representation.cjs

@@ -0,0 +1,378 @@
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_contexts = require("../contexts-B09jb9Pi.cjs");
+//#region src/internal/signed-representation.ts
+const RETAINED_SIGNED_REPRESENTATION = Symbol.for("@fedify/vocab-runtime.signedRepresentation.v1");
+const SIGNED_VALUE_SCOPE = Symbol.for("@fedify/vocab-runtime.signedValueScope.v1");
+/**
+* The IRI namespace of the placeholder node references that stand in for a
+* retained signed representation until the owning `toJsonLd()` frame puts the
+* representation back.
+*/
+const MARKER_NAMESPACE = "urn:x-fedify-signed-value:";
+/** Bounds applied when validating a retained signed representation. */
+const MAX_VALIDATION_DEPTH = 64;
+const MAX_VALIDATION_NODES = 1e5;
+/**
+* The depth to which placeholders are put back.  It has to exceed
+* {@link MAX_VALIDATION_DEPTH}, because a restored document is itself nested
+* inside the document that embeds it.  Running out of depth is an error
+* rather than a stopping point: a placeholder left in an unvisited subtree
+* would reach the wire in place of the secured child.
+*/
+const MAX_RESTORATION_DEPTH = 256;
+/**
+* JSON-LD keywords that may appear at the top level of a context definition
+* without endangering placeholder recovery.  `@vocab` and `@base` are checked
+* separately because they can rewrite the placeholder IRI.
+*/
+const HARMLESS_CONTEXT_KEYWORDS = /* @__PURE__ */ new Set([
+	"@protected",
+	"@version",
+	"@propagate"
+]);
+/**
+* Keyword aliases that are safe to leave in place because the placeholder
+* recovery walker understands them.
+*/
+const ALLOWED_KEYWORD_ALIASES = /* @__PURE__ */ new Map([["id", "@id"], ["type", "@type"]]);
+function isJsonMap(value) {
+	if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+/**
+* Checks that a value is a plain JSON tree that is safe to embed verbatim in
+* a serialized document: plain object and array prototypes only, string keys
+* only, own enumerable data properties only, finite numbers, and no
+* `undefined`.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isPlainJsonTree(value) {
+	let nodes = 0;
+	return check(value, 0);
+	function check(current, depth) {
+		if (depth > MAX_VALIDATION_DEPTH) return false;
+		if (++nodes > MAX_VALIDATION_NODES) return false;
+		if (current === null) return true;
+		switch (typeof current) {
+			case "string":
+			case "boolean": return true;
+			case "number": return Number.isFinite(current);
+			case "object": break;
+			default: return false;
+		}
+		if (Array.isArray(current)) {
+			if (Object.getPrototypeOf(current) !== Array.prototype) return false;
+			if (Object.getOwnPropertySymbols(current).length > 0) return false;
+			for (let i = 0; i < current.length; i++) {
+				const descriptor = Object.getOwnPropertyDescriptor(current, i);
+				if (descriptor == null || !("value" in descriptor)) return false;
+				if (!check(descriptor.value, depth + 1)) return false;
+			}
+			return true;
+		}
+		if (!isJsonMap(current)) return false;
+		if (Object.getOwnPropertySymbols(current).length > 0) return false;
+		for (const key of Object.getOwnPropertyNames(current)) {
+			const descriptor = Object.getOwnPropertyDescriptor(current, key);
+			if (descriptor == null || !("value" in descriptor)) return false;
+			if (!descriptor.enumerable) return false;
+			if (!check(descriptor.value, depth + 1)) return false;
+		}
+		return true;
+	}
+}
+function deepFreeze(value) {
+	if (value == null || typeof value !== "object") return value;
+	if (Object.isFrozen(value)) return value;
+	Object.freeze(value);
+	for (const child of Object.values(value)) deepFreeze(child);
+	return value;
+}
+/**
+* Attaches the secured JSON document that a signer captured for `target`.
+*
+* The document is the exact JSON value that the object's own Object Integrity
+* Proof covers.  Nested serialization embeds it verbatim instead of
+* reconstructing the object under the parent's JSON-LD context.  The value is
+* deep-frozen, so it is independent of anything done to `target` afterwards.
+*
+* `clone()` never carries the attachment, because a clone is a fresh instance.
+*
+* @internal Technically exported for `@fedify/fedify` and generated
+* vocabulary classes, but not part of the public API contract.  This is not
+* considered public API for Semantic Versioning decisions.
+*/
+function retainSignedRepresentation(target, securedDocument) {
+	if (!isJsonMap(securedDocument) || !isPlainJsonTree(securedDocument)) throw new TypeError(`The secured document must be a plain JSON map within the validation bounds (at most ${MAX_VALIDATION_DEPTH} levels deep and ${MAX_VALIDATION_NODES} nodes).`);
+	Object.defineProperty(target, RETAINED_SIGNED_REPRESENTATION, {
+		value: deepFreeze(securedDocument),
+		enumerable: false,
+		writable: false,
+		configurable: true
+	});
+}
+/**
+* Returns the secured JSON document retained for `target`, if any.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function getRetainedSignedRepresentation(target) {
+	if (target == null || typeof target !== "object") return void 0;
+	const retained = target[RETAINED_SIGNED_REPRESENTATION];
+	return isJsonMap(retained) ? retained : void 0;
+}
+function resolveContextEntry(entry) {
+	if (typeof entry !== "string") return entry;
+	if (!Object.hasOwn(require_contexts.preloadedContexts, entry)) return void 0;
+	const document = require_contexts.preloadedContexts[entry];
+	if (!isJsonMap(document)) return void 0;
+	return document["@context"];
+}
+/**
+* Checks whether a JSON-LD context leaves placeholder node references
+* recoverable after compaction.
+*
+* Placeholder recovery replaces a bare IRI string, `{"@id": …}`, or
+* `{"id": …}`.  A context that aliases `@id` under a different term, declares
+* `@nest`, uses an `@id` or `@type` container, rebases or re-vocabularies the
+* placeholder namespace, or defines a prefix that shortens the placeholder
+* IRI could hide the placeholder from that walker or make the walker rewrite
+* the wrong node.  A context that cannot be resolved offline cannot be vetted
+* at all.  Any of those makes the context unsafe, and retention is then not
+* used.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function isMarkerSafeContext(context) {
+	return check(context, 0);
+	function check(current, depth) {
+		if (depth > 8) return false;
+		if (Array.isArray(current)) return current.every((entry) => check(entry, depth + 1));
+		if (typeof current === "string") {
+			const resolved = resolveContextEntry(current);
+			if (resolved === void 0) return false;
+			return check(resolved, depth + 1);
+		}
+		if (current == null) return true;
+		if (!isJsonMap(current)) return false;
+		for (const [term, definition] of Object.entries(current)) {
+			if (term === "@vocab" || term === "@base") {
+				if (typeof definition !== "string") return false;
+				if (sharesMarkerNamespace(definition)) return false;
+				continue;
+			}
+			if (term.startsWith("@")) {
+				if (!HARMLESS_CONTEXT_KEYWORDS.has(term)) return false;
+				continue;
+			}
+			if (MARKER_NAMESPACE.startsWith(`${term}:`)) return false;
+			if (!checkTerm(term, definition, depth)) return false;
+		}
+		return true;
+	}
+	function checkTerm(term, definition, depth) {
+		if (definition == null) return true;
+		if (typeof definition === "string") return checkTermTarget(term, definition);
+		if (!isJsonMap(definition)) return false;
+		const target = definition["@id"];
+		if (target != null) {
+			if (typeof target !== "string") return false;
+			if (!checkTermTarget(term, target)) return false;
+		}
+		if ("@nest" in definition) return false;
+		if ("@reverse" in definition) return false;
+		const container = definition["@container"];
+		const containers = Array.isArray(container) ? container : container == null ? [] : [container];
+		for (const entry of containers) if (entry === "@id" || entry === "@type") return false;
+		if ("@context" in definition) {
+			if (!check(definition["@context"], depth + 1)) return false;
+		}
+		return true;
+	}
+	function checkTermTarget(term, target) {
+		if (target.startsWith("@")) return ALLOWED_KEYWORD_ALIASES.get(term) === target;
+		if (!target.includes(":")) return false;
+		return !sharesMarkerNamespace(target);
+	}
+}
+/**
+* Reports whether an IRI prefix could shorten, relativize or otherwise hide a
+* placeholder IRI.  Both directions matter: a prefix shorter than the
+* namespace covers every marker, and a longer one covers the markers whose
+* random suffix happens to start with it.
+*/
+function sharesMarkerNamespace(prefix) {
+	return MARKER_NAMESPACE.startsWith(prefix) || prefix.startsWith(MARKER_NAMESPACE);
+}
+/**
+* Joins the signed-value scope of the enclosing `toJsonLd()` frame, or starts
+* one when this frame is the outermost.
+*
+* `options` must already be the internal copy that the generated encoder
+* makes, never the object a caller passed in: the scope is attached to it as
+* an enumerable symbol-keyed property so that every `{...options}` spread in
+* the generated code propagates it to nested and inherited frames.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function enterSignedValueScope(options) {
+	const existing = options[SIGNED_VALUE_SCOPE];
+	if (existing != null) return {
+		scope: existing,
+		owner: false
+	};
+	const scope = {
+		enabled: options.format !== "expand" && (options.context == null || isMarkerSafeContext(options.context)),
+		markers: /* @__PURE__ */ new Map(),
+		documents: /* @__PURE__ */ new Map()
+	};
+	Object.defineProperty(options, SIGNED_VALUE_SCOPE, {
+		value: scope,
+		enumerable: true,
+		writable: false,
+		configurable: true
+	});
+	return {
+		scope,
+		owner: true
+	};
+}
+/**
+* Emits a placeholder node reference for a value that carries a retained
+* signed representation, or `undefined` when it does not carry one.
+*
+* Both encoder paths use placeholders, never the retained document itself:
+* an ancestor frame may still expand or compact the value, which would
+* destroy an embedded document but leaves a node reference recoverable.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function retainedSignedValueRef(value, scope) {
+	if (!scope.enabled) return void 0;
+	if (value == null || typeof value !== "object") return void 0;
+	const retained = getRetainedSignedRepresentation(value);
+	if (retained == null) return void 0;
+	let marker = scope.markers.get(value);
+	if (marker == null) {
+		if (!isPlainJsonTree(retained)) return void 0;
+		marker = `${MARKER_NAMESPACE}${crypto.randomUUID()}`;
+		scope.markers.set(value, marker);
+		scope.documents.set(marker, retained);
+	}
+	return { "@id": marker };
+}
+function markerOf(value, scope) {
+	return typeof value === "string" && scope.documents.has(value) ? value : void 0;
+}
+/**
+* Puts every retained signed representation back in place of its placeholder
+* node reference.
+*
+* Only the frame that owns the scope calls this, and only after compaction
+* and context embedding are complete.
+*
+* @throws {TypeError} If a retained document was not put back anywhere, or if
+*         any trace of a placeholder survives.  Both mean the serialized
+*         document does not contain the secured child it was told to embed,
+*         and emitting it would produce a signed child that silently fails
+*         verification.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+function resolveSignedValues(document, scope) {
+	if (scope.documents.size < 1) return document;
+	const restored = /* @__PURE__ */ new Set();
+	const resolved = restore(document, 0);
+	for (const marker of scope.documents.keys()) {
+		if (restored.has(marker)) continue;
+		throw new TypeError(`Failed to preserve a signed child representation: the placeholder ${marker} is not in the serialized document.`);
+	}
+	const trace = findMarkerTrace(resolved, scope);
+	if (trace != null) throw new TypeError(`Failed to preserve a signed child representation: a trace of the placeholder ${trace} survived serialization.`);
+	return resolved;
+	function restore(value, depth) {
+		if (depth > MAX_RESTORATION_DEPTH) throw new TypeError(`Failed to preserve a signed child representation: the serialized document is nested deeper than ${MAX_RESTORATION_DEPTH} levels, so a placeholder could be left unresolved.`);
+		const direct = markerOf(value, scope);
+		if (direct != null) return take(direct);
+		if (Array.isArray(value)) {
+			let changed = false;
+			const mapped = value.map((item) => {
+				const next = restore(item, depth + 1);
+				if (next !== item) changed = true;
+				return next;
+			});
+			return changed ? mapped : value;
+		}
+		if (!isJsonMap(value)) return value;
+		const keys = Object.keys(value);
+		if (keys.length === 1 && (keys[0] === "@id" || keys[0] === "id")) {
+			const marker = markerOf(value[keys[0]], scope);
+			if (marker != null) return take(marker);
+		}
+		let changed = false;
+		const mapped = Object.create(null);
+		for (const key of keys) {
+			const next = key === "@context" ? value[key] : restore(value[key], depth + 1);
+			if (next !== value[key]) changed = true;
+			mapped[key] = next;
+		}
+		if (!changed) return value;
+		return Object.setPrototypeOf(mapped, Object.prototype);
+	}
+	function take(marker) {
+		restored.add(marker);
+		return structuredClone(scope.documents.get(marker));
+	}
+}
+/**
+* Finds any surviving trace of a placeholder IRI in a resolved document,
+* matching the random suffix rather than the whole IRI so that a shortened,
+* relativized or otherwise rewritten marker is caught too.
+*/
+function findMarkerTrace(document, scope) {
+	const suffixes = /* @__PURE__ */ new Map();
+	for (const marker of scope.documents.keys()) suffixes.set(marker.slice(26), marker);
+	return search(document, 0);
+	function matched(value) {
+		for (const [suffix, marker] of suffixes) if (value.includes(suffix)) return marker;
+	}
+	function search(value, depth) {
+		if (depth > MAX_RESTORATION_DEPTH) throw new TypeError(`Failed to preserve a signed child representation: the serialized document is nested deeper than ${MAX_RESTORATION_DEPTH} levels, so a surviving placeholder could go unnoticed.`);
+		if (typeof value === "string") return matched(value);
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				const found = search(item, depth + 1);
+				if (found != null) return found;
+			}
+			return;
+		}
+		if (value == null || typeof value !== "object") return void 0;
+		for (const [key, child] of Object.entries(value)) {
+			const found = matched(key) ?? search(child, depth + 1);
+			if (found != null) return found;
+		}
+	}
+}
+//#endregion
+exports.enterSignedValueScope = enterSignedValueScope;
+exports.getRetainedSignedRepresentation = getRetainedSignedRepresentation;
+exports.isMarkerSafeContext = isMarkerSafeContext;
+exports.isPlainJsonTree = isPlainJsonTree;
+exports.resolveSignedValues = resolveSignedValues;
+exports.retainSignedRepresentation = retainSignedRepresentation;
+exports.retainedSignedValueRef = retainedSignedValueRef;

package/dist/internal/signed-representation.d.cts

@@ -0,0 +1,144 @@
+/// <reference lib="esnext.temporal" />
+//#region src/internal/signed-representation.d.ts
+/**
+* A JSON map.  Retained signed representations are always plain JSON maps.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+type SignedRepresentationJsonMap = Record<string, unknown>;
+/**
+* Checks that a value is a plain JSON tree that is safe to embed verbatim in
+* a serialized document: plain object and array prototypes only, string keys
+* only, own enumerable data properties only, finite numbers, and no
+* `undefined`.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isPlainJsonTree(value: unknown): boolean;
+/**
+* Attaches the secured JSON document that a signer captured for `target`.
+*
+* The document is the exact JSON value that the object's own Object Integrity
+* Proof covers.  Nested serialization embeds it verbatim instead of
+* reconstructing the object under the parent's JSON-LD context.  The value is
+* deep-frozen, so it is independent of anything done to `target` afterwards.
+*
+* `clone()` never carries the attachment, because a clone is a fresh instance.
+*
+* @internal Technically exported for `@fedify/fedify` and generated
+* vocabulary classes, but not part of the public API contract.  This is not
+* considered public API for Semantic Versioning decisions.
+*/
+declare function retainSignedRepresentation(target: object, securedDocument: SignedRepresentationJsonMap): void;
+/**
+* Returns the secured JSON document retained for `target`, if any.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function getRetainedSignedRepresentation(target: unknown): SignedRepresentationJsonMap | undefined;
+/**
+* Checks whether a JSON-LD context leaves placeholder node references
+* recoverable after compaction.
+*
+* Placeholder recovery replaces a bare IRI string, `{"@id": …}`, or
+* `{"id": …}`.  A context that aliases `@id` under a different term, declares
+* `@nest`, uses an `@id` or `@type` container, rebases or re-vocabularies the
+* placeholder namespace, or defines a prefix that shortens the placeholder
+* IRI could hide the placeholder from that walker or make the walker rewrite
+* the wrong node.  A context that cannot be resolved offline cannot be vetted
+* at all.  Any of those makes the context unsafe, and retention is then not
+* used.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isMarkerSafeContext(context: unknown): boolean;
+/**
+* The per-`toJsonLd()`-call state that tracks retained children.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+interface SignedValueScope {
+  /** Whether retained representations may be embedded at all. */
+  readonly enabled: boolean;
+  /** Marker IRI for each retained instance seen in this call. */
+  readonly markers: Map<object, string>;
+  /** Retained document for each marker IRI. */
+  readonly documents: Map<string, SignedRepresentationJsonMap>;
+}
+/**
+* The result of entering a signed-value scope.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+interface SignedValueScopeEntry {
+  readonly scope: SignedValueScope;
+  /**
+  * Whether this frame created the scope, and therefore has to put the
+  * retained documents back before returning.
+  */
+  readonly owner: boolean;
+}
+/**
+* Joins the signed-value scope of the enclosing `toJsonLd()` frame, or starts
+* one when this frame is the outermost.
+*
+* `options` must already be the internal copy that the generated encoder
+* makes, never the object a caller passed in: the scope is attached to it as
+* an enumerable symbol-keyed property so that every `{...options}` spread in
+* the generated code propagates it to nested and inherited frames.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function enterSignedValueScope(options: {
+  format?: "compact" | "expand";
+  context?: string | Record<string, string> | (string | Record<string, string>)[];
+}): SignedValueScopeEntry;
+/**
+* Emits a placeholder node reference for a value that carries a retained
+* signed representation, or `undefined` when it does not carry one.
+*
+* Both encoder paths use placeholders, never the retained document itself:
+* an ancestor frame may still expand or compact the value, which would
+* destroy an embedded document but leaves a node reference recoverable.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function retainedSignedValueRef(value: unknown, scope: SignedValueScope): {
+  "@id": string;
+} | undefined;
+/**
+* Puts every retained signed representation back in place of its placeholder
+* node reference.
+*
+* Only the frame that owns the scope calls this, and only after compaction
+* and context embedding are complete.
+*
+* @throws {TypeError} If a retained document was not put back anywhere, or if
+*         any trace of a placeholder survives.  Both mean the serialized
+*         document does not contain the secured child it was told to embed,
+*         and emitting it would produce a signed child that silently fails
+*         verification.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function resolveSignedValues(document: unknown, scope: SignedValueScope): unknown;
+//#endregion
+export { SignedRepresentationJsonMap, SignedValueScope, SignedValueScopeEntry, enterSignedValueScope, getRetainedSignedRepresentation, isMarkerSafeContext, isPlainJsonTree, resolveSignedValues, retainSignedRepresentation, retainedSignedValueRef };

package/dist/internal/signed-representation.d.ts

@@ -0,0 +1,144 @@
+/// <reference lib="esnext.temporal" />
+//#region src/internal/signed-representation.d.ts
+/**
+* A JSON map.  Retained signed representations are always plain JSON maps.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+type SignedRepresentationJsonMap = Record<string, unknown>;
+/**
+* Checks that a value is a plain JSON tree that is safe to embed verbatim in
+* a serialized document: plain object and array prototypes only, string keys
+* only, own enumerable data properties only, finite numbers, and no
+* `undefined`.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isPlainJsonTree(value: unknown): boolean;
+/**
+* Attaches the secured JSON document that a signer captured for `target`.
+*
+* The document is the exact JSON value that the object's own Object Integrity
+* Proof covers.  Nested serialization embeds it verbatim instead of
+* reconstructing the object under the parent's JSON-LD context.  The value is
+* deep-frozen, so it is independent of anything done to `target` afterwards.
+*
+* `clone()` never carries the attachment, because a clone is a fresh instance.
+*
+* @internal Technically exported for `@fedify/fedify` and generated
+* vocabulary classes, but not part of the public API contract.  This is not
+* considered public API for Semantic Versioning decisions.
+*/
+declare function retainSignedRepresentation(target: object, securedDocument: SignedRepresentationJsonMap): void;
+/**
+* Returns the secured JSON document retained for `target`, if any.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function getRetainedSignedRepresentation(target: unknown): SignedRepresentationJsonMap | undefined;
+/**
+* Checks whether a JSON-LD context leaves placeholder node references
+* recoverable after compaction.
+*
+* Placeholder recovery replaces a bare IRI string, `{"@id": …}`, or
+* `{"id": …}`.  A context that aliases `@id` under a different term, declares
+* `@nest`, uses an `@id` or `@type` container, rebases or re-vocabularies the
+* placeholder namespace, or defines a prefix that shortens the placeholder
+* IRI could hide the placeholder from that walker or make the walker rewrite
+* the wrong node.  A context that cannot be resolved offline cannot be vetted
+* at all.  Any of those makes the context unsafe, and retention is then not
+* used.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function isMarkerSafeContext(context: unknown): boolean;
+/**
+* The per-`toJsonLd()`-call state that tracks retained children.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+interface SignedValueScope {
+  /** Whether retained representations may be embedded at all. */
+  readonly enabled: boolean;
+  /** Marker IRI for each retained instance seen in this call. */
+  readonly markers: Map<object, string>;
+  /** Retained document for each marker IRI. */
+  readonly documents: Map<string, SignedRepresentationJsonMap>;
+}
+/**
+* The result of entering a signed-value scope.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+interface SignedValueScopeEntry {
+  readonly scope: SignedValueScope;
+  /**
+  * Whether this frame created the scope, and therefore has to put the
+  * retained documents back before returning.
+  */
+  readonly owner: boolean;
+}
+/**
+* Joins the signed-value scope of the enclosing `toJsonLd()` frame, or starts
+* one when this frame is the outermost.
+*
+* `options` must already be the internal copy that the generated encoder
+* makes, never the object a caller passed in: the scope is attached to it as
+* an enumerable symbol-keyed property so that every `{...options}` spread in
+* the generated code propagates it to nested and inherited frames.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function enterSignedValueScope(options: {
+  format?: "compact" | "expand";
+  context?: string | Record<string, string> | (string | Record<string, string>)[];
+}): SignedValueScopeEntry;
+/**
+* Emits a placeholder node reference for a value that carries a retained
+* signed representation, or `undefined` when it does not carry one.
+*
+* Both encoder paths use placeholders, never the retained document itself:
+* an ancestor frame may still expand or compact the value, which would
+* destroy an embedded document but leaves a node reference recoverable.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function retainedSignedValueRef(value: unknown, scope: SignedValueScope): {
+  "@id": string;
+} | undefined;
+/**
+* Puts every retained signed representation back in place of its placeholder
+* node reference.
+*
+* Only the frame that owns the scope calls this, and only after compaction
+* and context embedding are complete.
+*
+* @throws {TypeError} If a retained document was not put back anywhere, or if
+*         any trace of a placeholder survives.  Both mean the serialized
+*         document does not contain the secured child it was told to embed,
+*         and emitting it would produce a signed child that silently fails
+*         verification.
+*
+* @internal Technically exported for generated vocabulary classes, but not
+* part of the public API contract.  This is not considered public API for
+* Semantic Versioning decisions.
+*/
+declare function resolveSignedValues(document: unknown, scope: SignedValueScope): unknown;
+//#endregion
+export { SignedRepresentationJsonMap, SignedValueScope, SignedValueScopeEntry, enterSignedValueScope, getRetainedSignedRepresentation, isMarkerSafeContext, isPlainJsonTree, resolveSignedValues, retainSignedRepresentation, retainedSignedValueRef };