@oh-my-pi/pi-ai 18.2.0 → 18.2.1

package/src/registry/oauth/perplexity.ts

@@ -1,15 +1,6 @@
 /**
- * Perplexity login and token refresh.
- *
- * Login paths (in priority order):
- * 1. macOS native app: reads JWT from NSUserDefaults (`defaults read ai.perplexity.mac authToken`)
- * 2. HTTP email OTP: `GET /api/auth/csrf` → `POST /api/auth/signin-email` → `POST /api/auth/signin-otp`
- *
- * No browser or manual cookie paste required.
- * Refresh: Socket.IO `refreshJWT` RPC over authenticated WebSocket connection.
- *
- * Protocol: Engine.IO v4 + Socket.IO v4 over WebSocket (bypasses Cloudflare managed challenge).
- * Architecture reverse-engineered from Perplexity macOS app (ai.perplexity.mac).
+ * Perplexity login via legacy macOS session borrowing, host-managed browser SSO,
+ * or HTTP email OTP (including authenticator challenges).
  */
 import * as os from "node:os";
 import { $env } from "@oh-my-pi/pi-utils";
@@ -80,10 +71,7 @@ function jwtToCredentials(jwt: string, email?: string): OAuthCredentials {
 // Desktop app extraction
 // ---------------------------------------------------------------------------
 
-/**
- * Read the Perplexity JWT from the native macOS Catalyst app's UserDefaults.
- * Tokens are stored in NSUserDefaults (not Keychain), readable by any same-UID process.
- */
+/** Read the legacy ai.perplexity.mac app's session; newer Mac apps use a restricted Keychain. */
 async function extractFromNativeApp(): Promise<string | null> {
 	if (os.platform() !== "darwin") return null;
 
@@ -99,7 +87,7 @@ async function extractFromNativeApp(): Promise<string | null> {
 }
 
 // ---------------------------------------------------------------------------
-// Socket.IO email OTP login
+// HTTP email OTP login
 // ---------------------------------------------------------------------------
 
 /**
@@ -274,32 +262,110 @@ async function httpEmailLogin(ctrl: OAuthController): Promise<OAuthCredentials>
 	return jwtToCredentials(token, trimmedEmail);
 }
 
+// ---------------------------------------------------------------------------
+// Browser SSO login
+// ---------------------------------------------------------------------------
+
+const SESSION_COOKIE_NAME = "__Secure-next-auth.session-token";
+const PERPLEXITY_BASE_URL = "https://www.perplexity.ai";
+
+async function browserSsoLogin(ctrl: OAuthController): Promise<OAuthCredentials> {
+	if (!ctrl.onBrowserSession) {
+		throw new AIError.OAuthError("Browser SSO is unavailable in this client", {
+			kind: "validation",
+			provider: "perplexity",
+		});
+	}
+	ctrl.onProgress?.("Complete Perplexity sign-in in the browser window. Choose SSO for your organization.");
+	const token = (
+		await ctrl.onBrowserSession(
+			{
+				url: `${PERPLEXITY_BASE_URL}/auth/signin`,
+				cookieNames: [SESSION_COOKIE_NAME, "next-auth.session-token"],
+			},
+			ctrl.signal,
+		)
+	).trim();
+	if (ctrl.signal?.aborted) throw new AIError.LoginCancelledError();
+	if (!token || /[\s;]/.test(token)) {
+		throw new AIError.OAuthError("Perplexity SSO captured an invalid session cookie", {
+			kind: "validation",
+			provider: "perplexity",
+		});
+	}
+
+	ctrl.onProgress?.("Validating Perplexity session...");
+	const response = await (ctrl.fetch ?? fetch)(`${PERPLEXITY_BASE_URL}/api/auth/session`, {
+		headers: {
+			Cookie: `${SESSION_COOKIE_NAME}=${token}`,
+			"User-Agent": APP_USER_AGENT,
+			"X-App-ApiVersion": API_VERSION,
+		},
+		redirect: "error",
+		signal: ctrl.signal,
+	});
+	if (!response.ok) {
+		throw new AIError.ProviderHttpError(`Perplexity session validation failed (${response.status})`, response.status);
+	}
+	let email: unknown;
+	try {
+		const session = (await response.json()) as { user?: { email?: unknown } } | null;
+		email = session?.user?.email;
+	} catch (error) {
+		if (ctrl.signal?.aborted) throw new AIError.LoginCancelledError();
+		if (!(error instanceof SyntaxError)) throw error;
+		throw new AIError.OAuthError("Perplexity returned an invalid session response", {
+			kind: "validation",
+			provider: "perplexity",
+		});
+	}
+	if (ctrl.signal?.aborted) throw new AIError.LoginCancelledError();
+	if (typeof email !== "string" || !email.trim()) {
+		throw new AIError.OAuthError("Perplexity session is invalid or expired. Sign in again.", {
+			kind: "validation",
+			provider: "perplexity",
+		});
+	}
+	return jwtToCredentials(token, email.trim());
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
-/**
- * Login to Perplexity.
- *
- * Tries auto-extraction from the desktop app, then runs HTTP email OTP login.
- *
- * No browser/manual token paste fallback is used.
- */
+/** Prefer legacy app borrowing, then offer browser SSO when the host supports it. */
 export async function loginPerplexity(ctrl: OAuthController): Promise<OAuthCredentials> {
-	if (!ctrl.onPrompt) {
-		throw new AIError.OnPromptRequiredError("Perplexity");
-	}
+	if (!ctrl.onPrompt) throw new AIError.OnPromptRequiredError("Perplexity");
+	if (ctrl.signal?.aborted) throw new AIError.LoginCancelledError();
 
-	// Path 1: Native macOS app JWT (skip if PI_AUTH_NO_BORROW=1)
 	if (!$env.PI_AUTH_NO_BORROW) {
 		ctrl.onProgress?.("Checking for Perplexity desktop app...");
 		const nativeJwt = await extractFromNativeApp();
+		if (ctrl.signal?.aborted) throw new AIError.LoginCancelledError();
 		if (nativeJwt) {
 			ctrl.onProgress?.("Found Perplexity JWT from native app");
 			return jwtToCredentials(nativeJwt);
 		}
 	}
 
-	// Path 2: HTTP email OTP
+	if (ctrl.onBrowserSession) {
+		const method = (
+			await ctrl.onPrompt({
+				message: "Login method: sso (browser) or email; blank for sso",
+				placeholder: "sso / email",
+				allowEmpty: true,
+			})
+		)
+			.trim()
+			.toLowerCase();
+		if (ctrl.signal?.aborted) throw new AIError.LoginCancelledError();
+		if (!method || method === "sso") return browserSsoLogin(ctrl);
+		if (method !== "email") {
+			throw new AIError.OAuthError("Choose sso or email for Perplexity login", {
+				kind: "validation",
+				provider: "perplexity",
+			});
+		}
+	}
 	return httpEmailLogin(ctrl);
 }

package/src/registry/oauth/types.ts

@@ -70,12 +70,21 @@ export interface OAuthProviderInfo {
 	storeCredentialsAs?: string;
 }
 
+/** Sign-in URL and accepted cookies for an isolated, host-owned browser. */
+export type OAuthBrowserSessionRequest = {
+	url: string;
+	/** Cookie names in preference order; return the first non-empty matching value. */
+	cookieNames: readonly string[];
+};
+
 export interface OAuthController {
 	onAuth?(info: OAuthAuthInfo): void;
 	onProgress?(message: string): void;
 	/** Request pasted callback input; stop any visible prompt when `signal` aborts. */
 	onManualCodeInput?(signal?: AbortSignal): Promise<string>;
 	onPrompt?(prompt: OAuthPrompt): Promise<string>;
+	/** Complete browser login and return one matching cookie value privately. Reject on cancellation or failure. */
+	onBrowserSession?(request: OAuthBrowserSessionRequest, signal?: AbortSignal): Promise<string>;
 	signal?: AbortSignal;
 	fetch?: FetchImpl;
 }

package/src/stream.ts

@@ -193,6 +193,8 @@ let providerInFlightHeartbeatWriterOverride:
 	| undefined;
 let providerInFlightLeaseRemoverOverride: ((leasePath: string) => Promise<void>) | undefined;
 let providerInFlightWaitObserverOverride: ((provider: string) => void) | undefined;
+let providerInFlightLockCreatedObserverOverride: ((lockDir: string) => Promise<void>) | undefined;
+let providerInFlightLockIdentifiedObserverOverride: ((lockDir: string) => Promise<void>) | undefined;
 
 export function configureProviderMaxInFlightRequests(limits: Record<string, number> | undefined): void {
 	configuredProviderMaxInFlightRequests = limits ?? {};
@@ -365,12 +367,21 @@ async function acquireProviderInFlightLock(provider: string, signal?: AbortSigna
 		if (signal?.aborted) throw signal.reason ?? new AIError.AbortError("Provider request aborted before dispatch");
 		try {
 			await fs.mkdir(lockDir);
-			const lockIdentity = await readProviderInFlightLockIdentity(lockDir);
+			await providerInFlightLockCreatedObserverOverride?.(lockDir);
+			let lockIdentity: ProviderInFlightLockIdentity;
+			try {
+				lockIdentity = await readProviderInFlightLockIdentity(lockDir);
+			} catch (error) {
+				if (isEnoent(error)) continue;
+				throw error;
+			}
 			const token = crypto.randomUUID();
 			try {
+				await providerInFlightLockIdentifiedObserverOverride?.(lockDir);
 				await writeProviderInFlightInfo(lockDir, token);
 			} catch (error) {
 				await releaseProviderInFlightLockDirIfSame(lockDir, lockIdentity);
+				if (isEnoent(error)) continue;
 				throw error;
 			}
 			return async () => {
@@ -623,6 +634,12 @@ export const __providerInFlightForTesting = {
 	setWaitObserver(observer: ((provider: string) => void) | undefined): void {
 		providerInFlightWaitObserverOverride = observer;
 	},
+	setLockCreatedObserver(observer: ((lockDir: string) => Promise<void>) | undefined): void {
+		providerInFlightLockCreatedObserverOverride = observer;
+	},
+	setLockIdentifiedObserver(observer: ((lockDir: string) => Promise<void>) | undefined): void {
+		providerInFlightLockIdentifiedObserverOverride = observer;
+	},
 	providerDir(provider: string): string {
 		return providerInFlightDir(provider);
 	},
@@ -1061,7 +1078,11 @@ async function resolveWithThinkingLoopRetries(
 	onAttempt?: (message: AssistantMessage) => void,
 ): Promise<AssistantMessage> {
 	const dispatchAttempt = async (): Promise<AssistantMessage> => {
-		const message = await dispatch().result();
+		const response = dispatch();
+		for await (const _event of response) {
+			// Completion callers do not consume deltas; drain them as they arrive to avoid retaining the response history.
+		}
+		const message = await response.result();
 		onAttempt?.(message);
 		return message;
 	};

package/src/types.ts

@@ -1055,6 +1055,8 @@ export interface AssistantMessage {
 	errorMessage?: string;
 	/** Stable recovery-classification text when errorMessage includes display-only diagnostics. */
 	errorClassificationMessage?: string;
+	/** True only when an exact request-body-read timeout failed on a full Responses replay, not a previous-response delta. */
+	requestBodyReadTimeoutFullReplay?: boolean;
 	/** Per-tool abort messages used when an aborted assistant turn needs different placeholder results per tool call. */
 	toolCallAbortMessages?: Record<string, string>;
 	/** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
@@ -1187,6 +1189,7 @@ export type CursorTodoSyncHandler = (
 	snapshot: CursorTodoSnapshot | null,
 	toolCallId: string,
 	error: string | null,
+	origin?: "read" | "update",
 ) => ToolResultMessage;
 
 export interface CursorShellStreamCallbacks {

package/src/usage/claude.ts

@@ -22,6 +22,8 @@ import { HOUR_MS, parseIsoTimestamp, WEEK_MS } from "./shared";
 const DEFAULT_ENDPOINT = "https://api.anthropic.com/api/oauth";
 const MAX_ATTEMPTS = 3;
 const BASE_RETRY_DELAY_MS = 500;
+/** Shared windows that gate every Claude request, whatever the model. */
+const CLAUDE_SHARED_GATE_WINDOW_IDS = ["5h", "7d"] as const;
 
 const CLAUDE_HEADERS = {
 	accept: "application/json, text/plain, */*",
@@ -921,5 +923,36 @@ export const claudeRankingStrategy: CredentialRankingStrategy = {
 		const kind = getClaudeModelKind(context);
 		return kind === "fable" || kind === "mythos" ? `tier:${kind}` : undefined;
 	},
+	/**
+	 * A reactive Fable/Mythos block carries the reset the 429 reported, but
+	 * Anthropic can restore the tier earlier (plan change, corrected counter),
+	 * and the block then idles a usable account for days. Judge each tier scope
+	 * against the limits that actually gate a request of that kind — its own
+	 * weekly row plus the shared umbrella windows — so a healthy report lifts
+	 * the block while a spent shared 5-hour wall keeps it.
+	 *
+	 * Only Fable/Mythos appear: {@link blockScope} scopes reactive blocks for
+	 * those tiers alone, so no other scope can exist to heal.
+	 */
+	healableBlockScopes(report) {
+		const sharedLimits = report.limits.filter(limit => limit.scope.shared === true);
+		// The endpoint returns a report as soon as one window parses, and a tier
+		// 429 can be caused by a shared wall. A payload missing a shared gate
+		// leaves the block's cause unknown, so vouch for nothing rather than
+		// clear a block that still holds.
+		const everySharedGateReported = CLAUDE_SHARED_GATE_WINDOW_IDS.every(windowId =>
+			sharedLimits.some(limit => limit.scope.windowId === windowId || limit.window?.id === windowId),
+		);
+		if (!everySharedGateReported) return [];
+		const tiers = new Set<string>();
+		for (const limit of report.limits) {
+			const tier = limit.scope.tier;
+			if (tier === "fable" || tier === "mythos") tiers.add(tier);
+		}
+		return [...tiers].map(tier => ({
+			blockScope: `tier:${tier}`,
+			limits: [...sharedLimits, ...report.limits.filter(limit => limit.scope.tier === tier)],
+		}));
+	},
 	windowDefaults: { primaryMs: 5 * 60 * 60 * 1000, secondaryMs: 7 * 24 * 60 * 60 * 1000 },
 };

package/src/usage/google-antigravity.ts

@@ -355,18 +355,24 @@ function buildQuotaSummaryReport(
 		);
 		const amount = buildQuotaSummaryAmount(bucket);
 		const counterKeys = getQuotaSummaryCounterKeys(group, bucket);
+		const sharedGroup =
+			counterKeys.length > 1
+				? `${bucket.bucketId ?? group?.displayName ?? "third-party"}:${window?.id ?? bucket.window ?? "default"}`
+				: undefined;
 		for (const counterKey of counterKeys) {
 			const counterName = getQuotaSummaryCounterName(counterKey);
 			const windowId = window?.id ?? bucket.window ?? bucket.bucketId ?? "default";
+			const label =
+				sharedGroup !== undefined ? "Claude & GPT (shared)" : counterKey === "google" ? "Gemini" : counterName;
 			limits.push({
 				id: `${params.provider}:${counterKey}:default:${bucket.bucketId ?? windowId}`,
-				label: counterName ? `Usage (${counterName})` : (group?.displayName ?? bucket.displayName ?? "Usage"),
+				label: label ?? group?.displayName ?? bucket.displayName ?? "Usage",
 				scope: {
 					provider: params.provider,
 					accountId: params.credential.accountId,
 					projectId: params.credential.projectId,
 					windowId,
-					...(counterKeys.length > 1 ? { shared: true } : {}),
+					...(sharedGroup !== undefined ? { shared: true, sharedGroup } : {}),
 				},
 				window,
 				amount,

package/src/usage.ts

@@ -54,6 +54,8 @@ export interface UsageScope {
 	tier?: string;
 	windowId?: string;
 	shared?: boolean;
+	/** Stable identity shared by routing-specific copies of one upstream quota. */
+	sharedGroup?: string;
 }
 
 /** Normalized limit entry for a single window or quota bucket. */
@@ -271,6 +273,7 @@ export const usageScopeSchema = type({
 	"tier?": "string",
 	"windowId?": "string",
 	"shared?": "boolean",
+	"sharedGroup?": "string",
 });
 
 export const usageLimitSchema = type({

package/src/utils/block-symbols.ts

@@ -141,3 +141,60 @@ export type SyntheticUserCarrier = object & { [kSyntheticUser]?: boolean };
 export function isSyntheticUser(message: SyntheticUserCarrier | null | undefined): boolean {
 	return message?.[kSyntheticUser] === true;
 }
+
+/**
+ * Marks a message synthesized by a per-call context transform rather than
+ * loaded from persisted conversation history.
+ *
+ * Prompt-cache boundaries must skip these messages: their content is rebuilt
+ * for each request and cannot anchor a prefix reused by the next turn.
+ * Symbol-keyed so the marker never persists or reaches the provider wire.
+ */
+export const kPerCallContextMessage = Symbol("agent.message.perCallContext");
+
+/** Carries per-call context provenance without exposing a string-keyed property. */
+export type PerCallContextMessageCarrier = object & { [kPerCallContextMessage]?: true };
+
+/** Marks a message as synthesized for the current provider call. */
+export function markPerCallContextMessage(message: PerCallContextMessageCarrier): void {
+	message[kPerCallContextMessage] = true;
+}
+
+/** Copies per-call context provenance to a converted or projected message. */
+export function copyPerCallContextMessage(
+	target: PerCallContextMessageCarrier,
+	source: PerCallContextMessageCarrier,
+): void {
+	if (source[kPerCallContextMessage] === true) target[kPerCallContextMessage] = true;
+}
+
+/** True when a message was synthesized for the current provider call. */
+export function isPerCallContextMessage(message: PerCallContextMessageCarrier | null | undefined): boolean {
+	return message?.[kPerCallContextMessage] === true;
+}
+
+/**
+ * Original history position carried by a context message clone.
+ *
+ * Object-spread transforms retain this symbol, allowing the extension runner
+ * to distinguish byte-identical historical copies from inserted messages.
+ */
+export const kContextHistoryIndex = Symbol("agent.message.contextHistoryIndex");
+
+/** Carries a context message's original history position. */
+export type ContextHistoryIndexCarrier = object & { [kContextHistoryIndex]?: number };
+
+/** Reads a context message's original history position. */
+export function getContextHistoryIndex(message: ContextHistoryIndexCarrier | null | undefined): number | undefined {
+	return message?.[kContextHistoryIndex];
+}
+
+/** Records a context message's original history position. */
+export function setContextHistoryIndex(message: ContextHistoryIndexCarrier, index: number): void {
+	message[kContextHistoryIndex] = index;
+}
+
+/** Removes context-history tracking before provider conversion. */
+export function clearContextHistoryIndex(message: ContextHistoryIndexCarrier): void {
+	delete message[kContextHistoryIndex];
+}

package/src/utils/openai-http.ts

@@ -14,7 +14,7 @@
  *   captured response body for the strict-tools fallback and the responses
  *   chain-state detectors, which regex over `error.message`.
  */
-import { fetchWithRetry, readSseJson, type SseEventObserver } from "@oh-my-pi/pi-utils";
+import { fetchWithRetry, readSseJsonOrText, type SseEventObserver } from "@oh-my-pi/pi-utils";
 import * as AIError from "../error";
 import { OpenAIHttpError } from "../error";
 
@@ -68,6 +68,8 @@ export interface OpenAIStreamRequestInit {
 	body: unknown;
 	signal: AbortSignal;
 	fetch?: FetchImpl;
+	/** Optional caller-specific gate composed with shared transport retry exclusions. */
+	shouldRetryResponse?: (response: Response, bodyText: string) => boolean | Promise<boolean>;
 	/** Raw wire-frame observer (`onSseEvent` debug pipeline). */
 	onSseEvent?: SseEventObserver;
 }
@@ -98,7 +100,9 @@ export async function postOpenAIStream<TEvent>(init: OpenAIStreamRequestInit): P
 		// A proxy concurrency-admission 429 (`rate_limit_type: max_parallel_requests`)
 		// surfaces immediately instead of being slept-and-retried here; session
 		// recovery owns its backoff/fallback (issue #8854).
-		shouldRetryResponse: (response, bodyText) => !isConcurrencyAdmissionRejection(response, bodyText),
+		shouldRetryResponse: async (response, bodyText) =>
+			!isConcurrencyAdmissionRejection(response, bodyText) &&
+			(init.shouldRetryResponse === undefined || (await init.shouldRetryResponse(response, bodyText))),
 		// Bun's native fetch enforces a hard ~300s pre-response timeout (issue #2422).
 		// Cold large-context streams legitimately exceed it; the caller's
 		// `firstEventTimeoutMs`/`AbortSignal` already govern stuck requests.
@@ -113,12 +117,44 @@ export async function postOpenAIStream<TEvent>(init: OpenAIStreamRequestInit): P
 		});
 	}
 	return {
-		events: readSseJson<TEvent>(response.body, init.signal, init.onSseEvent),
+		events: decodeStream<TEvent>(response.body, init.signal, init.onSseEvent),
 		response,
 		requestId: response.headers.get("x-request-id"),
 	};
 }
 
+/**
+ * Consume `readSseJsonOrText` and turn a non-JSON `data:` frame into a
+ * classified in-band error. A reverse proxy that already committed to an HTTP
+ * 200 stream (so the status line can no longer carry the failure) answers with
+ * plain text — `data: 429 Too Many Requests`, an nginx throttle page — and
+ * that has to advance the fallback chain like a real 429 (body-error.ts).
+ * Frames that are not recognisable throttles rethrow the original parse error,
+ * preserving the pre-existing loud failure for genuinely malformed payloads.
+ * `readSseJsonOrText` also yields a frame that was a JSON-encoded *string* on the
+ * wire (a double-encoded proxy error page); it is not a usable event either, so
+ * it is classified the same way and then dropped — every consumer here already
+ * ignored a string chunk, the completions loop by its `typeof !== "object"` test.
+ */
+async function* decodeStream<TEvent>(
+	body: ReadableStream<Uint8Array>,
+	signal: AbortSignal | undefined,
+	onSseEvent: SseEventObserver | undefined,
+): AsyncGenerator<TEvent> {
+	for await (const frame of readSseJsonOrText<TEvent>(body, signal, onSseEvent)) {
+		if (typeof frame === "string") {
+			const inBand = AIError.createInBandProviderErrorFromText(frame);
+			if (inBand) throw inBand;
+			// Not a recognisable throttle: reproduce the exact strict-parse failure the
+			// previous reader raised, so genuinely malformed payloads stay equally
+			// loud. A frame that parses again was a JSON string, not a malformed one.
+			JSON.parse(frame);
+			continue;
+		}
+		yield frame;
+	}
+}
+
 /** Decode a non-2xx response into an {@link OpenAIHttpError} without consuming it twice. */
 export async function captureOpenAIHttpError(response: Response): Promise<AIError.OpenAIHttpError> {
 	let bodyText: string | undefined;

package/src/utils/retry-after.ts

@@ -1,5 +1,17 @@
+import { retryResetTimezoneOffsetFor } from "@oh-my-pi/pi-catalog/compat/behavior";
+import { extractRetryHint } from "@oh-my-pi/pi-utils";
+
 export type HeadersLike = Headers | Record<string, string | undefined> | undefined | null;
 
+/** Extracts retry timing using the provider's catalog-declared timestamp timezone. */
+export function extractProviderRetryHint(
+	provider: string | undefined,
+	message: string | undefined,
+): number | undefined {
+	const naiveResetTimezoneOffset = provider === undefined ? undefined : retryResetTimezoneOffsetFor(provider);
+	return extractRetryHint(undefined, message, { naiveResetTimezoneOffset });
+}
+
 const RETRY_AFTER_HINT = "retry-after-ms=";
 
 export function formatErrorMessageWithRetryAfter(error: unknown, headers?: HeadersLike): string {

package/src/utils/schema/normalize.ts

@@ -1877,9 +1877,9 @@ function inferStrictPrimitiveTypeFromEnumOrConst(node: Record<string, unknown>):
 }
 
 /**
- * Per-schema-object memoization slot. The result of `tryEnforceStrictSchema`
- * is stamped directly onto the input via `stamp(target, kStrictSchema, …)`
- * so repeated calls (different providers, retries, batching) reuse the same
+ * Per-schema-object memoization key. The result of `tryEnforceStrictSchema`
+ * is memoized against the input via `stamp(target, kStrictSchema, …)` so
+ * repeated calls (different providers, retries, batching) reuse the same
  * computed pair without re-walking the tree.
  */
 const kStrictSchema = Symbol("pi.schema.strict");

package/src/utils/schema/stamps.ts

@@ -1,38 +1,39 @@
 /**
- * Symbol-keyed lazy memoization stamped directly onto the host object.
+ * Lazy memoization keyed by host object identity, held in a module-level
+ * weak side table.
  *
- * 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.
+ * The bookkeeping deliberately lives outside the host rather than in a
+ * non-enumerable symbol property: schema objects are caller-owned and may be
+ * sealed, frozen, or deep-frozen after their first traversal. A recursive
+ * freeze that enumerates with `Reflect.ownKeys` reaches symbol slots, so an
+ * on-host slot would be frozen along with the schema and every later write
+ * would throw. A side table is also invisible to `{...spread}`,
+ * `Object.keys`, `JSON.stringify`, and `toEqual`-style deep equality.
  *
- * Caveats: the stamp lives as long as the host object, even after callers
+ * Caveats: an entry 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.
+ * whose lifetime should match the host.
  */
-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 });
-}
+const memos = new WeakMap<object, Map<symbol, unknown>>();
 
 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];
+	let slots = memos.get(target);
+	if (!slots) {
+		slots = new Map();
+		memos.set(target, slots);
+	}
+	const existing = slots.get(key) as V | undefined;
 	if (existing !== undefined) return existing;
 	const value = compute(target);
-	define(target, key, value);
+	slots.set(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.
+ * Epoch-keyed cycle guard. Cheaper than a per-call `WeakSet` for recursive
+ * traversal because the marker is a single side-table entry per host object,
+ * written once and overwritten in place on every subsequent traversal — no
+ * per-walk allocation.
  *
  * Usage:
  *   function walk(node, epoch = epochNext()) {
@@ -40,7 +41,7 @@ export function stamp<T extends object, V>(target: T, key: symbol, compute: (tar
  *     for (const child of node.children) walk(child, epoch);
  *   }
  */
-const kEpoch = Symbol("pi.schema.epoch");
+const epochs = new WeakMap<object, number>();
 let __epoch = 0;
 
 export function epochNext(): number {
@@ -53,11 +54,9 @@ export function epochNext(): number {
  * 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];
+	const cur = epochs.get(target);
 	if (cur !== undefined && cur >= epoch) return false;
-	if (cur === undefined) define(target, kEpoch, epoch);
-	else slot[kEpoch] = epoch;
+	epochs.set(target, epoch);
 	return true;
 }
 
@@ -65,13 +64,9 @@ export function once<T extends object>(target: T, epoch: number): boolean {
  * 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
+ * entry, decrement on exit; the counter 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");
@@ -79,7 +74,7 @@ export function once<T extends object>(target: T, epoch: number): boolean {
  *     finally { exit(node); }
  *   }
  */
-const kDepth = Symbol("pi.schema.depth");
+const depths = new WeakMap<object, number>();
 
 /**
  * Returns `true` on first entry, `false` if `target` is already on the
@@ -89,21 +84,14 @@ const kDepth = Symbol("pi.schema.depth");
  * 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;
+	const cur = depths.get(target);
+	if (cur !== undefined && cur !== 0) return false;
+	depths.set(target, 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.
+	const cur = depths.get(target);
 	if (cur === undefined) return;
-	slot[kDepth] = cur - 1;
+	depths.set(target, cur - 1);
 }