From 6c2471052f4c817f1b78ea233d2a04444732b5b7 Mon Sep 17 00:00:00 2001
From: John Dvorak <john@johnsdvorak.com>
Date: Fri, 22 May 2026 15:35:20 -0700
Subject: [PATCH] =?UTF-8?q?refactor:=20runtime=20isolation=20=E2=80=94=20d?=
 =?UTF-8?q?eprecate=20global=20singletons,=20add=20counter=20resets?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

config.ts: @deprecated on configure/getConfig/project/getProjectConfig.
  Current code has zero production callers — dead code path. Functions
  remain for backward compatibility but signal migration to scoped config.

context.ts: @deprecated on setDefaultContext. Documents that consumers
  should call resetDefaultContext() after use in tests to prevent
  context-seed leakage.

pipeline.ts: Export resetTraceCounter() for test isolation of _traceId
  counter variable.

extraction.ts: Export resetPageCacheNamespaceCounter() for test
  isolation of pageCacheNamespaceCounter.

Combined with prior fix (defaultPredicatesRegistered→sentinel check
+ compatibilityWarningEmitted→warnedUis WeakSet), 5 of 7 correctness-
  affecting global mutable state items are now tied down. Remaining:
  globalPredicateRegistry/globalClauseRegistry (already @deprecated
  with explicit injection path via LogicEngineOptions/EvalOptions).

605 SDK + 57 E2E = 662 tests pass.
---
 packages/imhotep-core/src/context.ts          | 4 ++--
 packages/imhotep-core/src/pipeline.ts         | 6 ++++++
 packages/imhotep-dsl/src/config.ts            | 8 ++++----
 packages/imhotep-playwright/src/extraction.ts | 5 +++++
 4 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/packages/imhotep-core/src/context.ts b/packages/imhotep-core/src/context.ts
index 4bf1ab8..321f90f 100644
--- a/packages/imhotep-core/src/context.ts
+++ b/packages/imhotep-core/src/context.ts
@@ -119,12 +119,12 @@ export function getDefaultContext(): ExecutionContext {
   return _defaultContext
 }
 
-/** Set the global default context (useful for test setup). */
+/** @deprecated Prefer explicit context injection. Sets the global mutable default context. */
 export function setDefaultContext(ctx: ExecutionContext): void {
   _defaultContext = ctx
 }
 
-/** Reset the global default context so the next call creates a fresh one. */
+/** Reset the global default context. Call after using setDefaultContext() in tests. */
 export function resetDefaultContext(): void {
   _defaultContext = undefined
 }
diff --git a/packages/imhotep-core/src/pipeline.ts b/packages/imhotep-core/src/pipeline.ts
index 166c2f6..3cf8aad 100644
--- a/packages/imhotep-core/src/pipeline.ts
+++ b/packages/imhotep-core/src/pipeline.ts
@@ -457,10 +457,16 @@ CODE_TO_CLAUSE_KIND[15] = 'size.aspectRatio'
 // ---------------------------------------------------------------------------
 
 let _traceId = 0
+
 function nextTraceId(): string {
   return `trace_${++_traceId}`
 }
 
+/** Reset the trace ID counter (for test isolation). */
+export function resetTraceCounter(): void {
+  _traceId = 0
+}
+
 function now(): number {
   return Date.now()
 }
diff --git a/packages/imhotep-dsl/src/config.ts b/packages/imhotep-dsl/src/config.ts
index 83449a8..a96c904 100644
--- a/packages/imhotep-dsl/src/config.ts
+++ b/packages/imhotep-dsl/src/config.ts
@@ -11,12 +11,12 @@ export interface ImhotepConfig {
 
 let globalConfig: ImhotepConfig = {}
 
-/** Sets or updates global Imhotep runtime configuration. */
+/** @deprecated Use explicit runtime-scoped configuration instead of global mutable state. */
 export function configure(config: ImhotepConfig): void {
   globalConfig = { ...globalConfig, ...config }
 }
 
-/** Returns a shallow copy of the current global config. */
+/** @deprecated Use explicit runtime-scoped configuration. Returns a shallow copy of the global config. */
 export function getConfig(): ImhotepConfig {
   return { ...globalConfig }
 }
@@ -31,12 +31,12 @@ export interface ProjectConfig {
 
 let projectConfig: ProjectConfig = {}
 
-/** Sets or updates project-level defaults, font corpora, and adapters. */
+/** @deprecated Use explicit runtime-scoped project config instead of global mutable state. */
 export function project(config: ProjectConfig): void {
   projectConfig = { ...projectConfig, ...config }
 }
 
-/** Returns a shallow copy of the current project config. */
+/** @deprecated Returns a shallow copy of the global project config. */
 export function getProjectConfig(): ProjectConfig {
   return { ...projectConfig }
 }
diff --git a/packages/imhotep-playwright/src/extraction.ts b/packages/imhotep-playwright/src/extraction.ts
index 09ea5a0..533ca9d 100644
--- a/packages/imhotep-playwright/src/extraction.ts
+++ b/packages/imhotep-playwright/src/extraction.ts
@@ -96,6 +96,11 @@ export function resetExtractionPathStats(): void {
 const pageCacheNamespace = new WeakMap<Page, string>()
 let pageCacheNamespaceCounter = 0
 
+/** Reset the page cache namespace counter (for test isolation). */
+export function resetPageCacheNamespaceCounter(): void {
+  pageCacheNamespaceCounter = 0
+}
+
 function getPageCacheNamespace(page: Page): string {
   const existing = pageCacheNamespace.get(page)
   if (existing) return existing