/**
 * Symbol-keyed lazy memoization stamped directly onto the host object.
 *
 * Faster than a module-level `WeakMap` in V8/JSC because the symbol slot is
 * resolved through the object's hidden class instead of a side-table hash
 * lookup. The slot is defined as a non-enumerable property so the stamp
 * does not leak through `{...spread}`, `Object.keys`, `JSON.stringify`, or
 * `toEqual`-style deep equality.
 *
 * Caveats: the stamp lives as long as the host object, even after callers
 * release their references to the cached value — only use this for caches
 * whose lifetime should match the host. Frozen hosts cannot be stamped;
 * `define` silently skips them, so memoization/visit-tracking degrades to
 * best-effort (recompute on every call, no cycle protection) instead of
 * throwing.
 */
function define<T extends object>(target: T, key: symbol, value: unknown): void {
	if (Object.isFrozen(target)) return;
	Object.defineProperty(target, key, { value, writable: true, configurable: true });
}

export function stamp<T extends object, V>(target: T, key: symbol, compute: (target: T) => V): V {
	const slot = target as Record<symbol, V | undefined>;
	const existing = slot[key];
	if (existing !== undefined) return existing;
	const value = compute(target);
	define(target, key, value);
	return value;
}

/**
 * Epoch-keyed cycle guard. Cheaper than `WeakSet` for recursive traversal
 * because the marker is a single property slot on the host object, written
 * once and overwritten in place on every subsequent traversal — the hidden
 * class transitions once per object lifetime, not per traversal.
 *
 * Usage:
 *   function walk(node, epoch = epochNext()) {
 *     if (!once(node, epoch)) return; // cycle
 *     for (const child of node.children) walk(child, epoch);
 *   }
 */
const kEpoch = Symbol("pi.schema.epoch");
let __epoch = 0;

export function epochNext(): number {
	return ++__epoch;
}

/**
 * Marks `target` as visited for this `epoch`. Returns `true` the first time
 * it is called for a given (target, epoch) pair and `false` on every
 * subsequent call within the same epoch.
 */
export function once<T extends object>(target: T, epoch: number): boolean {
	const slot = target as Record<symbol, number | undefined>;
	const cur = slot[kEpoch];
	if (cur !== undefined && cur >= epoch) return false;
	if (cur === undefined) define(target, kEpoch, epoch);
	else slot[kEpoch] = epoch;
	return true;
}

/**
 * Counter-based path tracker. Use when a traversal needs to distinguish
 * "currently on the recursion path" from "previously visited" — i.e. cycle
 * detection that throws while still allowing DAG sharing. Increment on
 * entry, decrement on exit; the slot returns to 0 after a balanced walk so
 * subsequent top-level calls see a fresh state without any reset.
 *
 * Unlike a `WeakSet` with `seen.delete(...)`, the property is never deleted
 * — only incremented and decremented — so the host object's hidden class
 * is never invalidated.
 *
 * Usage:
 *   function walk(node) {
 *     if (!enter(node)) throw new Error("cycle");
 *     try { for (const c of node.children) walk(c); }
 *     finally { exit(node); }
 *   }
 */
const kDepth = Symbol("pi.schema.depth");

/**
 * Returns `true` on first entry, `false` if `target` is already on the
 * current path. A `false` return does NOT deepen the counter — callers pair
 * `exit` only with successful enters (`if (!enter(n)) bail; try {…} finally
 * { exit(n); }`), so incrementing on the cycle branch would leak depth and
 * make every later top-level walk of the same object misreport a cycle.
 */
export function enter<T extends object>(target: T): boolean {
	const slot = target as Record<symbol, number | undefined>;
	const cur = slot[kDepth];
	if (cur === undefined) {
		define(target, kDepth, 1);
		return true;
	}
	if (cur !== 0) return false;
	slot[kDepth] = 1;
	return true;
}

export function exit<T extends object>(target: T): void {
	const slot = target as Record<symbol, number | undefined>;
	const cur = slot[kDepth];
	// Frozen targets never received the kDepth stamp in `enter` — nothing to unwind.
	if (cur === undefined) return;
	slot[kDepth] = cur - 1;
}