@qilin-agent/util-values 0.0.0-stage → 3.1.4

package/lib/index.js

@@ -0,0 +1,923 @@
+//#region lib/types/partial-json.js
+/**
+* Lazily scanned view of one JSON object's top-level fields, built from text
+* that may still be streaming or from an already parsed object. Nothing is
+* scanned until a reader asks; the view remembers every question it answered
+* and reports changed answers when the owner refreshes for publication.
+* Used for model tool-call arguments: a row reads the fields it
+* cares about at whatever granularity it displays, at every stage of the call.
+* @module @qilin-agent/util-values/src/partial-json
+*/
+const SIMPLE_ESCAPES = {
+	"\"": "\"",
+	"\\": "\\",
+	"/": "/",
+	b: "\b",
+	f: "\f",
+	n: "\n",
+	r: "\r",
+	t: "	"
+};
+const CONTENT_ESCAPE = /[\\\u0000-\u001f]/u;
+function isWhitespace(c) {
+	return c === " " || c === "\n" || c === "\r" || c === "	";
+}
+function isHex(c) {
+	return c >= "0" && c <= "9" || c >= "a" && c <= "f" || c >= "A" && c <= "F";
+}
+/**
+* The view. A streaming instance grows through {@link PartialArguments.append};
+* {@link PartialArguments.fromText} and {@link PartialArguments.fromObject} build
+* sealed instances over a finished call. Every reader is total: an absent or
+* differently typed field answers `undefined` (or `false`), never throws.
+*/
+var PartialArguments = class PartialArguments {
+	/** The view of a call with no arguments available. */
+	static EMPTY = PartialArguments.fromObject({});
+	/**
+	* View finished argument text without scanning it until a reader asks.
+	* @param text - the complete argument JSON text.
+	* @returns a sealed view.
+	*/
+	static fromText(text) {
+		const view = new PartialArguments();
+		view.append(text);
+		view.sealed = true;
+		return view;
+	}
+	/**
+	* View an already parsed argument payload, such as a PTC dispatch object.
+	* @param value - the parsed argument value.
+	* @returns a sealed view; a non-object payload has no fields.
+	*/
+	static fromObject(value) {
+		const view = new PartialArguments();
+		view.object = typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+		view.sealed = true;
+		return view;
+	}
+	/**
+	* The source: text so far or a parsed object, plus whether it can still grow.
+	* These are the only enumerable fields, so two views over the same source
+	* compare equal structurally however far each has been read.
+	*/
+	chunks = [];
+	object;
+	sealed = false;
+	#ends = [];
+	#size = 0;
+	#consumed = 0;
+	#mode = "root";
+	#escape = false;
+	#keyStart = 0;
+	#keyEscaped = false;
+	#key = "";
+	#current = null;
+	#nestedEnds = [];
+	#nestedInString = false;
+	#invalidAt;
+	#invalidValue = false;
+	#entries = /* @__PURE__ */ new Map();
+	#order = [];
+	#reads = /* @__PURE__ */ new Map();
+	/** Whether this view rejects further appends; does not scan text or register reads. */
+	get isSealed() {
+		return this.sealed;
+	}
+	/** Whether indexing or a content read found invalid JSON; unread value contents are not validated. */
+	get invalid() {
+		this.scan();
+		return this.#mode === "invalid" || this.#invalidValue;
+	}
+	/**
+	* Retain streamed argument text without scanning or comparing observed answers.
+	* @param fragment - the text following every fragment appended before.
+	*/
+	append(fragment) {
+		if (this.sealed) throw new Error("PartialArguments: cannot append to a sealed view");
+		if (fragment.length === 0) return;
+		this.chunks.push(fragment);
+		this.#size += fragment.length;
+		this.#ends.push(this.#size);
+	}
+	/**
+	* Reconcile a streamed prefix with authoritative complete text without joining the fragments.
+	* @param text - the final argument text, which replaces missing or conflicting deltas.
+	* @returns this view sealed with its caches retained when every character matches; otherwise a new sealed view.
+	*/
+	settle(text) {
+		if (this.object !== void 0 || text.length !== this.#size) return PartialArguments.fromText(text);
+		let offset = 0;
+		for (const chunk of this.chunks) {
+			if (!text.startsWith(chunk, offset)) return PartialArguments.fromText(text);
+			offset += chunk.length;
+		}
+		this.chunks = text.length === 0 ? [] : [text];
+		this.#ends = text.length === 0 ? [] : [text.length];
+		this.sealed = true;
+		return this;
+	}
+	/**
+	* Compare observed answers and advance their publication baseline. Unread views remain unscanned.
+	* @returns whether any observed answer changed since its first read or the preceding refresh.
+	*/
+	refresh() {
+		if (this.#reads.size === 0) return false;
+		this.scan();
+		let changed = false;
+		let completions = false;
+		for (const read of this.#reads.values()) {
+			if (read.completion) {
+				completions = true;
+				continue;
+			}
+			changed = this.refreshRead(read) || changed;
+		}
+		if (completions) {
+			for (const read of this.#reads.values()) if (read.completion) changed = this.refreshRead(read) || changed;
+		}
+		if (this.sealed) this.#reads.clear();
+		return changed;
+	}
+	refreshRead(read) {
+		const now = read.answer();
+		if (Object.is(now, read.last)) return false;
+		read.last = now;
+		return true;
+	}
+	/**
+	* Check whether no further fields can arrive.
+	* @returns whether the outer object closed, indexing failed, or the view is sealed; unread values are not validated.
+	*/
+	closed() {
+		return this.remember("closed", "", () => this.closedNow());
+	}
+	/**
+	* List discovered fields in first-appearance order.
+	* @returns top-level keys seen so far, in first-appearance order.
+	*/
+	keys() {
+		return this.remember("keys", "", () => this.keysNow(), (keys) => keys.length);
+	}
+	/**
+	* Check whether a top-level field has appeared.
+	* @param key - argument name.
+	* @returns whether the field has appeared (a string opened or another value began).
+	*/
+	has(key) {
+		return this.remember("has", key, () => this.hasNow(key));
+	}
+	/**
+	* Check whether a field's closing delimiter has arrived, without validating its contents.
+	* @param key - argument name.
+	* @returns whether its delimiter arrived and no content reader has reported an error for this value.
+	*/
+	complete(key) {
+		return this.remember("complete", key, () => this.completeNow(key));
+	}
+	/**
+	* Read string length without materializing its text.
+	* @param key - argument name.
+	* @param options - change granularity for a streaming string.
+	* @returns decoded UTF-16 length of the string field so far; undefined when absent or not a string.
+	*/
+	stringLength(key, options) {
+		const step = Math.max(1, Math.floor(options?.step ?? 1));
+		const offset = options?.offset ?? 0;
+		return this.remember(`length:${step}:${offset}`, key, () => this.lengthNow(key), (length) => length === void 0 ? void 0 : Math.ceil((length + offset) / step));
+	}
+	/**
+	* Check a string against a decoded UTF-16 length limit without materializing it.
+	* @param key - argument name.
+	* @param maxLength - decoded UTF-16 limit, floored to at least zero.
+	* @returns whether the string is longer than the limit; false when absent or not a string.
+	*/
+	stringExceeds(key, maxLength) {
+		const limit = Math.max(0, Math.floor(maxLength));
+		return this.remember(`exceeds:${limit}`, key, () => (this.lengthNow(key, limit + 1) ?? 0) > limit);
+	}
+	/**
+	* Read a decoded string, including a streaming prefix.
+	* @param key - argument name.
+	* @returns the string field's decoded text so far; undefined when absent or not a string.
+	*/
+	text(key) {
+		return this.remember("text", key, () => this.textNow(key));
+	}
+	/**
+	* Read at most the first decoded UTF-16 units of a string.
+	* @param key - argument name.
+	* @param maxLength - maximum decoded UTF-16 length, floored to at least one.
+	* @returns the bounded string prefix; undefined when absent or not a string.
+	*/
+	textPrefix(key, maxLength) {
+		const limit = Math.max(1, Math.floor(maxLength));
+		return this.remember(`prefix:${limit}`, key, () => this.textPrefixNow(key, limit));
+	}
+	/**
+	* Read a completed non-string argument.
+	* @param key - argument name.
+	* @returns the parsed non-string value once it closed; undefined while open, absent, or a string.
+	*/
+	value(key) {
+		return this.remember("value", key, () => this.valueNow(key));
+	}
+	/** Answer a question and, on a streaming view, remember it for change detection. */
+	remember(kind, key, read, comparison) {
+		this.scan();
+		const result = read();
+		if (!this.sealed) {
+			const id = `${kind}/${key}`;
+			if (!this.#reads.has(id)) this.#reads.set(id, {
+				completion: kind === "complete",
+				answer: comparison === void 0 ? read : () => comparison(read()),
+				last: comparison === void 0 ? result : comparison(result)
+			});
+		}
+		return result;
+	}
+	closedNow() {
+		return this.sealed || this.#mode === "closed" || this.#mode === "invalid";
+	}
+	keysNow() {
+		return this.object === void 0 ? this.#order : Object.keys(this.object);
+	}
+	hasNow(key) {
+		return this.object === void 0 ? this.#entries.has(key) : Object.hasOwn(this.object, key);
+	}
+	completeNow(key) {
+		if (this.object !== void 0) return Object.hasOwn(this.object, key);
+		const entry = this.#entries.get(key);
+		return entry !== void 0 && entry.end >= 0 && (entry.kind === "string" ? entry.invalidAt === void 0 : !entry.invalid);
+	}
+	lengthNow(key, limit = Number.POSITIVE_INFINITY) {
+		if (this.object !== void 0) {
+			const field = Object.hasOwn(this.object, key) ? this.object[key] : void 0;
+			return typeof field === "string" ? field.length : void 0;
+		}
+		const entry = this.#entries.get(key);
+		if (entry?.kind !== "string") return void 0;
+		if (entry.text !== void 0 && entry.text.at === entry.end) return entry.text.length;
+		const read = entry.length ??= {
+			at: entry.start,
+			length: 0,
+			text: ""
+		};
+		this.readString(entry, read, limit, false);
+		return read.length;
+	}
+	textNow(key) {
+		if (this.object !== void 0) {
+			const field = Object.hasOwn(this.object, key) ? this.object[key] : void 0;
+			return typeof field === "string" ? field : void 0;
+		}
+		const entry = this.#entries.get(key);
+		if (entry?.kind !== "string") return void 0;
+		if (entry.text === void 0 && entry.end >= 0 && entry.needsDecoding && entry.invalidAt === void 0) {
+			let text;
+			try {
+				text = JSON.parse(`"${this.slice(entry.start, entry.end)}"`);
+			} catch (_error) {}
+			if (text !== void 0) entry.text = {
+				at: entry.end,
+				length: text.length,
+				text
+			};
+		}
+		const read = entry.text ??= {
+			at: entry.start,
+			length: 0,
+			text: ""
+		};
+		this.readString(entry, read, Number.POSITIVE_INFINITY, true);
+		return read.text;
+	}
+	textPrefixNow(key, maxLength) {
+		if (this.object !== void 0) {
+			const field = Object.hasOwn(this.object, key) ? this.object[key] : void 0;
+			return typeof field === "string" ? field.slice(0, maxLength) : void 0;
+		}
+		const entry = this.#entries.get(key);
+		if (entry?.kind !== "string") return void 0;
+		const prefixes = entry.prefixes ??= /* @__PURE__ */ new Map();
+		let read = prefixes.get(maxLength);
+		if (read === void 0) {
+			read = {
+				at: entry.start,
+				length: 0,
+				text: ""
+			};
+			prefixes.set(maxLength, read);
+		}
+		this.readString(entry, read, maxLength, true);
+		return read.text;
+	}
+	valueNow(key) {
+		if (this.object !== void 0) {
+			if (!Object.hasOwn(this.object, key)) return void 0;
+			const field = this.object[key];
+			return typeof field === "string" ? void 0 : field;
+		}
+		const entry = this.#entries.get(key);
+		if (entry?.kind !== "value" || entry.end < 0 || entry.invalid) return void 0;
+		if (entry.parsed === void 0) try {
+			entry.parsed = JSON.parse(this.slice(entry.start, entry.end));
+		} catch (_error) {
+			entry.invalid = true;
+			this.#invalidValue = true;
+		}
+		return entry.parsed;
+	}
+	chunkAt(at) {
+		let low = 0;
+		let high = this.#ends.length;
+		while (low < high) {
+			const mid = low + high >>> 1;
+			if (this.#ends[mid] <= at) low = mid + 1;
+			else high = mid;
+		}
+		return low;
+	}
+	/** Materialize only a requested range, never the cumulative source. */
+	slice(start, end) {
+		if (start >= end) return "";
+		const first = this.chunkAt(start);
+		const last = this.chunkAt(end - 1);
+		const base = first === 0 ? 0 : this.#ends[first - 1];
+		if (first === last) return this.chunks[first].slice(start - base, end - base);
+		const parts = [this.chunks[first].slice(start - base)];
+		for (let i = first + 1; i < last; i++) parts.push(this.chunks[i]);
+		parts.push(this.chunks[last].slice(0, end - this.#ends[last - 1]));
+		return parts.join("");
+	}
+	readString(entry, read, limit, materialize) {
+		const end = Math.min(entry.end < 0 ? this.#consumed : entry.end, entry.invalidAt ?? Number.POSITIVE_INFINITY, this.#invalidAt ?? Number.POSITIVE_INFINITY);
+		if (!entry.needsDecoding) {
+			const length = Math.min(end - read.at, limit - read.length);
+			if (length <= 0) return;
+			if (materialize) read.text += this.slice(read.at, read.at + length);
+			read.at += length;
+			read.length += length;
+			return;
+		}
+		let chunkIndex = this.chunkAt(read.at);
+		while (read.at < end && read.length < limit) {
+			const base = chunkIndex === 0 ? 0 : this.#ends[chunkIndex - 1];
+			const chunk = this.chunks[chunkIndex];
+			const remaining = chunk.slice(read.at - base, Math.min(chunk.length, end - base));
+			const boundary = remaining.search(CONTENT_ESCAPE);
+			const length = Math.min(boundary < 0 ? remaining.length : boundary, limit - read.length);
+			if (length > 0) {
+				if (materialize) read.text += remaining.slice(0, length);
+				read.at += length;
+				read.length += length;
+				if (read.at === base + chunk.length) chunkIndex++;
+				continue;
+			}
+			const type = remaining.length > 1 ? remaining[1] : read.at + 1 < end ? this.chunks[chunkIndex + 1][0] : void 0;
+			let decoded;
+			let width = 2;
+			if (remaining[0] === "\\" && type === void 0 && entry.end < 0) return;
+			if (remaining[0] === "\\" && type === "u") {
+				const hex = this.slice(read.at + 2, Math.min(end, read.at + 6));
+				let valid = true;
+				for (let i = 0; i < hex.length; i++) if (!isHex(hex[i])) valid = false;
+				if (valid) {
+					if (hex.length < 4 && entry.end < 0) return;
+					if (hex.length === 4) decoded = String.fromCharCode(Number.parseInt(hex, 16));
+				}
+				width = 6;
+			} else if (remaining[0] === "\\" && type !== void 0) decoded = SIMPLE_ESCAPES[type];
+			if (decoded === void 0) {
+				entry.invalidAt = read.at;
+				this.#invalidValue = true;
+				return;
+			}
+			if (materialize) read.text += decoded;
+			read.length++;
+			read.at += width;
+			while (chunkIndex < this.chunks.length && read.at >= this.#ends[chunkIndex]) chunkIndex++;
+		}
+	}
+	/** Locate new field ranges without decoding or parsing their contents. */
+	scan() {
+		if (this.object !== void 0 || this.#consumed === this.#size) return;
+		for (let i = this.chunkAt(this.#consumed); i < this.chunks.length && this.#invalidAt === void 0; i++) {
+			const pending = this.chunks[i];
+			const base = i === 0 ? 0 : this.#ends[i - 1];
+			for (let index = this.#consumed - base; index < pending.length && this.#mode !== "invalid"; index++) {
+				if (this.#mode === "string" || this.#mode === "nested" && this.#nestedInString) {
+					const end = this.stringBoundary(pending, index);
+					this.#consumed += end - index;
+					index = end;
+					if (index === pending.length) break;
+				}
+				this.step(pending[index], this.#consumed);
+				this.#consumed++;
+			}
+		}
+	}
+	/** Only raw quotes and their preceding backslash runs can terminate a string. */
+	stringBoundary(fragment, start) {
+		let at = start;
+		while (true) {
+			const quote = fragment.indexOf("\"", at);
+			const end = quote < 0 ? fragment.length : quote;
+			if (this.#mode === "string") {
+				const entry = this.#current;
+				if (!entry.needsDecoding && CONTENT_ESCAPE.test(fragment.slice(at, end))) entry.needsDecoding = true;
+			}
+			let slashStart = end;
+			while (slashStart > at && fragment[slashStart - 1] === "\\") slashStart--;
+			const escaped = (end - slashStart) % 2 === 1 !== (slashStart === at && this.#escape);
+			this.#escape = quote < 0 && escaped;
+			if (quote < 0 || !escaped) return end;
+			at = quote + 1;
+		}
+	}
+	step(c, at) {
+		switch (this.#mode) {
+			case "root":
+				if (isWhitespace(c)) return;
+				if (c === "{") {
+					this.#mode = "key-or-end";
+					return;
+				}
+				this.fail();
+				return;
+			case "key-or-end":
+				if (isWhitespace(c)) return;
+				if (c === "}") {
+					this.#mode = "closed";
+					return;
+				}
+				if (c === "\"") {
+					this.beginKey(at);
+					return;
+				}
+				this.fail();
+				return;
+			case "key-only":
+				if (isWhitespace(c)) return;
+				if (c === "\"") {
+					this.beginKey(at);
+					return;
+				}
+				this.fail();
+				return;
+			case "key":
+				this.stepKey(c, at);
+				return;
+			case "colon":
+				if (isWhitespace(c)) return;
+				if (c === ":") {
+					this.#mode = "value";
+					return;
+				}
+				this.fail();
+				return;
+			case "value":
+				this.beginValue(c, at);
+				return;
+			case "string": {
+				const entry = this.#current;
+				entry.end = at;
+				this.#current = null;
+				this.#mode = "comma-or-end";
+				return;
+			}
+			case "scalar":
+				this.stepScalar(c, at);
+				return;
+			case "nested":
+				this.stepNested(c, at);
+				return;
+			case "comma-or-end":
+				if (isWhitespace(c)) return;
+				if (c === ",") {
+					this.#mode = "key-only";
+					return;
+				}
+				if (c === "}") {
+					this.#mode = "closed";
+					return;
+				}
+				this.fail();
+				return;
+			case "closed":
+				if (isWhitespace(c)) return;
+				this.fail();
+				return;
+			/* v8 ignore next 2 -- scan() stops stepping once the view is invalid. */
+			case "invalid": return;
+			/* v8 ignore next 2 -- Every scanner mode has a handler above. */
+			default: assertNever(this.#mode);
+		}
+	}
+	fail() {
+		this.#invalidAt = this.#consumed;
+		this.#mode = "invalid";
+		this.#current = null;
+	}
+	beginKey(at) {
+		this.#mode = "key";
+		this.#keyStart = at + 1;
+		this.#keyEscaped = false;
+		this.#escape = false;
+	}
+	stepKey(c, at) {
+		if (c < " ") {
+			this.fail();
+			return;
+		}
+		if (this.#escape) {
+			this.#escape = false;
+			return;
+		}
+		if (c === "\\") {
+			this.#escape = true;
+			this.#keyEscaped = true;
+			return;
+		}
+		if (c !== "\"") return;
+		const raw = this.slice(this.#keyStart, at);
+		if (this.#keyEscaped) try {
+			this.#key = JSON.parse(`"${raw}"`);
+		} catch (_error) {
+			this.fail();
+			return;
+		}
+		else this.#key = raw;
+		this.#mode = "colon";
+	}
+	open(entry) {
+		if (!this.#entries.has(this.#key)) this.#order.push(this.#key);
+		this.#entries.set(this.#key, entry);
+		this.#current = entry;
+	}
+	beginValue(c, at) {
+		if (isWhitespace(c)) return;
+		if (c === "\"") {
+			this.open({
+				kind: "string",
+				start: at + 1,
+				end: -1,
+				needsDecoding: false,
+				invalidAt: void 0,
+				length: void 0,
+				text: void 0,
+				prefixes: void 0
+			});
+			this.#escape = false;
+			this.#mode = "string";
+			return;
+		}
+		if (c === "}" || c === "," || c === ":" || c === "]") {
+			this.fail();
+			return;
+		}
+		this.open({
+			kind: "value",
+			start: at,
+			end: -1,
+			parsed: void 0,
+			invalid: false
+		});
+		if (c === "{" || c === "[") {
+			this.#mode = "nested";
+			this.#nestedEnds = [c === "{" ? "}" : "]"];
+			this.#nestedInString = false;
+			this.#escape = false;
+			return;
+		}
+		this.#mode = "scalar";
+	}
+	stepScalar(c, at) {
+		if (c !== "," && c !== "}" && !isWhitespace(c)) return;
+		this.closeValue(at);
+		this.#mode = c === "," ? "key-only" : c === "}" ? "closed" : "comma-or-end";
+	}
+	stepNested(c, at) {
+		if (this.#nestedInString) {
+			this.#nestedInString = false;
+			return;
+		}
+		if (c === "\"") {
+			this.#nestedInString = true;
+			return;
+		}
+		if (c === "{" || c === "[") {
+			this.#nestedEnds.push(c === "{" ? "}" : "]");
+			return;
+		}
+		if (c === "}" || c === "]") {
+			if (this.#nestedEnds.pop() !== c) {
+				this.fail();
+				return;
+			}
+			if (this.#nestedEnds.length === 0) {
+				this.closeValue(at + 1);
+				this.#mode = "comma-or-end";
+			}
+		}
+	}
+	closeValue(end) {
+		const entry = this.#current;
+		entry.end = end;
+		this.#current = null;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/** Duplicate-install-safe JSON and immutable-value helpers. @module @qilin-agent/util-values */
+/**
+* Mark an unreachable closed-union branch.
+* @param value - impossible value; an unhandled typed variant fails at the call site.
+* @param context - optional switch-site label included in the failure message.
+* @returns never; a runtime value that escaped its type always throws.
+*/
+function assertNever(value, context) {
+	const rendered = JSON.stringify(value) ?? String(value);
+	throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
+}
+/** Whether a realm-owned intrinsic prototype has a native constructor matching this engine's representation. */
+function hasIntrinsicConstructor(prototype, name) {
+	const constructor = Object.getOwnPropertyDescriptor(prototype, "constructor")?.value;
+	if (typeof constructor !== "function") return false;
+	try {
+		return constructor.name === name && constructor.prototype === prototype && Function.prototype.toString.call(constructor) === Function.prototype.toString.call(name === "Array" ? Array : Object);
+	} catch {
+		return false;
+	}
+}
+/** Whether a candidate is one realm's intrinsic `Object.prototype`. */
+function isIntrinsicObjectPrototype(value) {
+	return Object.getPrototypeOf(value) === null && hasIntrinsicConstructor(value, "Object");
+}
+/** Whether an array uses one realm's intrinsic `Array.prototype`, not a subclass or forged prototype. */
+function hasPlainArrayPrototype(value) {
+	const prototype = Object.getPrototypeOf(value);
+	if (!Array.isArray(prototype) || !hasIntrinsicConstructor(prototype, "Array")) return false;
+	const objectPrototype = Object.getPrototypeOf(prototype);
+	return typeof objectPrototype === "object" && objectPrototype !== null && isIntrinsicObjectPrototype(objectPrototype);
+}
+/** Whether an object is a plain or null-prototype record from any JavaScript realm. */
+function hasPlainObjectPrototype(value) {
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || typeof prototype === "object" && isIntrinsicObjectPrototype(prototype);
+}
+/** Return every JSON-visible object key, or reject own data JSON would discard. */
+function enumerableStringKeys(value) {
+	const keys = Reflect.ownKeys(value);
+	if (keys.some((key) => typeof key !== "string" || !Object.prototype.propertyIsEnumerable.call(value, key))) return void 0;
+	return keys;
+}
+/** Validate lossless JSON iteratively, optionally materializing a detached snapshot. */
+function walkJsonValue(value, detach) {
+	const ancestors = /* @__PURE__ */ new Set();
+	let root;
+	const assign = (destination, item) => {
+		if (destination === void 0) return;
+		if (destination.kind === "root") root = item;
+		else if (destination.kind === "array") destination.target[destination.index] = item;
+		else Object.defineProperty(destination.target, destination.key, {
+			value: item,
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+	};
+	const tasks = [{
+		kind: "visit",
+		value,
+		...detach ? { destination: { kind: "root" } } : {}
+	}];
+	for (let task = tasks.pop(); task !== void 0; task = tasks.pop()) {
+		if (task.kind === "leave") {
+			ancestors.delete(task.source);
+			continue;
+		}
+		if (task.kind === "array-item") {
+			if (!Object.prototype.hasOwnProperty.call(task.source, task.index)) return void 0;
+			tasks.push({
+				kind: "visit",
+				value: task.source[task.index],
+				...task.target === void 0 ? {} : { destination: {
+					kind: "array",
+					target: task.target,
+					index: task.index
+				} }
+			});
+			continue;
+		}
+		if (task.kind === "object-property") {
+			tasks.push({
+				kind: "visit",
+				value: task.source[task.key],
+				...task.target === void 0 ? {} : { destination: {
+					kind: "object",
+					target: task.target,
+					key: task.key
+				} }
+			});
+			continue;
+		}
+		const current = task.value;
+		if (current === null) {
+			assign(task.destination, null);
+			continue;
+		}
+		if (typeof current === "boolean" || typeof current === "string") {
+			assign(task.destination, current);
+			continue;
+		}
+		if (typeof current === "number") {
+			if (!Number.isFinite(current) || Object.is(current, -0)) return void 0;
+			assign(task.destination, current);
+			continue;
+		}
+		if (typeof current !== "object") return void 0;
+		if (ancestors.has(current)) return void 0;
+		if (Array.isArray(current)) {
+			if (!hasPlainArrayPrototype(current)) return void 0;
+			const length = current.length;
+			if (Reflect.ownKeys(current).length !== length + 1) return void 0;
+			const target = detach ? [] : void 0;
+			if (target !== void 0) assign(task.destination, target);
+			ancestors.add(current);
+			tasks.push({
+				kind: "leave",
+				source: current
+			});
+			for (let index = length - 1; index >= 0; index--) tasks.push({
+				kind: "array-item",
+				source: current,
+				index,
+				...target === void 0 ? {} : { target }
+			});
+			continue;
+		}
+		if (!hasPlainObjectPrototype(current)) return void 0;
+		const keys = enumerableStringKeys(current);
+		if (keys === void 0) return void 0;
+		const target = detach ? {} : void 0;
+		if (target !== void 0) assign(task.destination, target);
+		ancestors.add(current);
+		tasks.push({
+			kind: "leave",
+			source: current
+		});
+		for (let index = keys.length - 1; index >= 0; index--) {
+			const key = keys[index];
+			/* v8 ignore next -- the loop is bounded by the captured key count. */
+			if (key === void 0) return void 0;
+			tasks.push({
+				kind: "object-property",
+				source: current,
+				key,
+				...target === void 0 ? {} : { target }
+			});
+		}
+	}
+	return detach ? root : true;
+}
+/**
+* Validate and detach lossless JSON in one read per property.
+* @param value - candidate value to validate and detach.
+* @returns the detached snapshot, or `undefined` when the value is not losslessly JSON-serializable.
+*/
+function snapshotJsonValue(value) {
+	return walkJsonValue(value, true);
+}
+/**
+* Test the same lossless JSON rules as {@link snapshotJsonValue} without detaching the value.
+* @param value - candidate value to test.
+* @returns whether the value survives a JSON round trip without loss.
+*/
+function isJsonValue(value) {
+	return walkJsonValue(value, false) === true;
+}
+/**
+* Compare JSON-compatible values structurally.
+* @param a - one JSON-compatible value.
+* @param b - the other JSON-compatible value.
+* @returns whether both values contain the same JSON data.
+*/
+function deepEqualJson(a, b) {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((entry, index) => deepEqualJson(entry, b[index]));
+	}
+	const left = a;
+	const right = b;
+	const keys = Object.keys(left);
+	if (keys.length !== Object.keys(right).length) return false;
+	return keys.every((key) => key in right && deepEqualJson(left[key], right[key]));
+}
+/**
+* Deep-freeze an object graph in place while leaving live AbortSignal objects mutable.
+* @param value - value to freeze.
+* @returns the same value after every reachable enumerable child is frozen.
+*/
+function deepFreeze(value) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const pending = [{
+		kind: "visit",
+		node: value
+	}];
+	while (pending.length > 0) {
+		const task = pending.pop();
+		/* v8 ignore next -- the loop condition guarantees one pending task. */
+		if (task === void 0) continue;
+		if (task.kind === "property") {
+			pending.push({
+				kind: "visit",
+				node: task.source[task.key]
+			});
+			continue;
+		}
+		const node = task.node;
+		if (node === null || typeof node !== "object") continue;
+		if (node instanceof AbortSignal) continue;
+		if (seen.has(node)) continue;
+		seen.add(node);
+		Object.freeze(node);
+		const keys = Object.keys(node);
+		for (let index = keys.length - 1; index >= 0; index--) {
+			const key = keys[index];
+			/* v8 ignore next -- the loop is bounded by the captured key count. */
+			if (key === void 0) continue;
+			pending.push({
+				kind: "property",
+				source: node,
+				key
+			});
+		}
+	}
+	return value;
+}
+/**
+* Weak-key lookup with a strongly retained iterable set of associated values.
+*
+* Each value must belong to only one key. The container performs no automatic
+* cleanup; owners delete associations or clear the container at lifecycle end.
+*/
+var WeakMapWithValues = class {
+	keys = /* @__PURE__ */ new WeakMap();
+	valueSet = /* @__PURE__ */ new Set();
+	/** Live strongly retained values in insertion order. */
+	values = this.valueSet;
+	/**
+	* Read the value associated with a key.
+	* @param key - weakly held lookup key.
+	* @returns the associated value, or absence.
+	*/
+	get(key) {
+		return this.keys.get(key);
+	}
+	/**
+	* Test whether a key has an association.
+	* @param key - weakly held lookup key.
+	* @returns whether the key is present.
+	*/
+	has(key) {
+		return this.keys.has(key);
+	}
+	/**
+	* Associate one key with one caller-unique value.
+	* @param key - weakly held lookup key.
+	* @param value - strongly retained value that belongs to no other key.
+	* @returns this container.
+	*/
+	set(key, value) {
+		if (this.keys.has(key)) {
+			const previous = this.keys.get(key);
+			if (previous === value) return this;
+			this.valueSet.delete(previous);
+		}
+		this.keys.set(key, value);
+		this.valueSet.add(value);
+		return this;
+	}
+	/**
+	* Remove one association and its strongly retained value.
+	* @param key - weakly held lookup key.
+	* @returns whether an association was removed.
+	*/
+	delete(key) {
+		if (!this.keys.has(key)) return false;
+		const value = this.keys.get(key);
+		const deleted = this.keys.delete(key);
+		this.valueSet.delete(value);
+		return deleted;
+	}
+	/** Remove every association and strongly retained value. */
+	clear() {
+		this.keys = /* @__PURE__ */ new WeakMap();
+		this.valueSet.clear();
+	}
+};
+//#endregion
+export { PartialArguments, WeakMapWithValues, assertNever, deepEqualJson, deepFreeze, isJsonValue, snapshotJsonValue };