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.
registry.ts: Add optional styles and fragments table types to the
solver's GeometryWorld. Previously these were attached via
(world as any).styles / .fragments, bypassing the type system.
extraction.ts:
- remapTopologyIds: accept topologySubjectIds as explicit parameter
instead of reading (world as any)._topologySubjectIds and deleting
it post-remap. Eliminates 3 smuggling accesses (read, set, delete)
- All worldAny.styles / worldAny.fragments / worldAny.strings /
worldAny.transforms / worldAny.matrices assignments now use
typed world.xxx access. worldAny variable removed entirely.
- attachMeasuredChWidths: use world.styles directly.
- (result.world as any).env mutation replaced with typed
result.world.env assignment.
- (sizeWorld as any).styles replaced with typed access.
predicates.ts: Replace all 3 (world as any).styles inline type-assert
reads (getSubjectFontSizePx, getRootFontSizePx, getSubjectChWidthPx)
with direct world.styles?.xxx access. No runtime behavior change.
Zero (world as any) casts remain in extraction.ts or predicates.ts.
658 tests pass.
predicates.ts (missing-fact discipline):
- getTopologyValueBySubject: return -1 sentinel instead of ?? 0
when topology data is missing/unset. NaN and negative values
also treated as missing. Previously returned 0 which was
indistinguishable from root subject ID.
- clippedByPredicate: return 'indeterminate' when clippingRoot < 0
- inStackingContextPredicate: return 'indeterminate' when sc < 0
or refSC < 0 (both subject and reference). Previously treated
missing data as false — a silent wrong answer.
- attachedToScrollContainerPredicate: return 'indeterminate' when
scrollContainer < 0
- escapeClippingChainOfPredicate: return 'indeterminate' when
clippingRoot < 0
extraction.ts (cleanup visibility):
- Promote fast-geometry and CDP cleanup failures from console.debug
(invisible during test execution) to console.warn. Contaminated
pages are now diagnosable without debug-log inspection.
658 tests pass.
predicates.ts: Replace defaultPredicatesRegistered boolean guard with
sentinel predicate check inside the registry. registerDefaultPredicates()
is now always safe to call — no module-scope flag that can drift out
of sync with the actual registry state. clearPredicateRegistry() no
longer needs to manually reset a flag.
extraction.ts:
- Replace compatibilityWarningEmitted process-singleton boolean with
WeakSet<ImhotepUi> (warnedUis). Each ImhotepUi instance now gets its
own compatibility warning, fixing the bug where two pages would share
a single warning gate.
- Export resetExtractionPathStats() for test isolation of fast-path
and CDP fallback counters.
598 SDK + 3 conformance + 57 E2E = 658 tests pass.
Imhotep-core: add predicate-specs.ts with 34 PredicateSpec entries as
the single source of truth for predicate metadata (name, arity,
aliases, requiredFacts, validOptions, diagnosticCode, relationCode,
decompose rules, category flags). Lookup helpers derive all
per-predicate information from the static table.
Extraction.ts (3 consumers converted):
- computeRequiredFacts: replace getRequiredFactsForPredicate (global
registry) with getPredicateRequiredFacts (static spec table).
Removes registerDefaultPredicates() dependency from fact planning.
- compileCanonicalClauseToFormula: replace 4 string-branch patterns
('between'/'separatedFrom'/'atLeast'/'aspectRatio'/'inStackingContext')
with spec-driven getPredicateDecomposition() and isUnaryPredicate().
Same behavior, zero string dispatch in predicate selection.
- mapFolDiagnostic: replace PREDICATE_TO_DIAGNOSTIC_CODE (13-entry
Record) with getPredicateDiagnosticCode() from spec table.
595 SDK + 57 hard E2E tests pass.
lower-to-canonical.ts: clauseEquivalent now compares compoundOperator
and compoundGroupId. Previously, compound assertions with different
operators (.and vs .or) were considered equivalent.
fol-compiler.ts: adaptGrammarFormulaToLogicAst validates node.kind
against known formula kinds (forall/exists/and/or/not/implies/predicate)
before passing through as FormulaNode. Previously any object with a
'kind' property was blindly cast.
predicates.ts / registry.ts: @deprecated tags on globalPredicateRegistry
and globalClauseRegistry. Both are still functional but consumers should
transition to explicit injection via LogicEngineOptions / EvaluationOptions.
454 solver+DSL tests pass, zero regressions.
geometry-cache.ts: replace 5 empty catch blocks with console.warn
- statSync failure, rmSync failure (x2), readCachedWorld failure,
readCachedExtractionResult failure were all silently swallowed.
Now emit context-bearing warnings so stale/corrupt caches are visible.
predicates.ts: replace __boxIndex as any mutation with WeakMap
- getBorderRect used (world as any).__boxIndex to cache a subject-to-
box-index map on the world object. Replaced with module-level WeakMap
that auto-collects when the world is GC'd. Eliminates 2 as any casts.
extraction.ts: serialize materializeSemanticSelector + debug cleanup
- 3 Promise.all sites over page.evaluate changed to sequential for..of
to eliminate DOM modification race conditions.
- 2 .catch(()=>{}) cleanup blocks now use console.debug so failed
cleanup is traceable when debugging.
- resolveViewport catch now emits console.warn on zero-viewport fallback.
648 SDK + 57 E2E tests pass.
pipeline.ts: || undefined → ?? undefined (9 occurrences)
- || converts valid subject ID 0 to undefined because 0 is falsy in JS.
This broke clause witnesses and topology references for the first subject.
domain-index.ts: remove .toLowerCase() on CSS selectors
- CSS selectors are case-sensitive (IDs, class names, attribute values).
Lowercasing on lookup but not on storage (selectorIndex) meant case-
sensitive selectors never matched — returning empty arrays silently.
canonical.ts: add warning when visualBoxes falls back to layout boxes
- visualBoxes ?? boxes silently substituted layout coordinates for visual
space, producing incorrect results for transform-dependent assertions.
Now emits console.warn so silent data corruption is visible.
extraction.ts: serialize materializeSemanticSelector calls (3 sites)
- Changed Promise.all over page.evaluate() to sequential for..of. While
Playwright serializes CDP calls internally, concurrent DOM-modifying
evaluate() calls create undefined execution order. Sequential resolution
eliminates theoretical race conditions for semantic selector injection.
engine.ts: include stack trace in evaluator exception diagnostics
- Catch-all converted ALL exceptions (including TypeError from programming
bugs) to IMH_EVALUATOR_EXCEPTION with just err.message. Now includes
stack trace and logs to console.warn for visibility. Distinguishes
TypeError (programming bug) from other evaluation errors.
648 SDK tests + 57 E2E hard tests pass, zero regressions.
Topology array order mismatch (critical bug):
- CDP browser script iterates elements in document order (querySelectorAll),
but solver accesses topology arrays by selector-resolution order.
- Fix: add subjectIds array to TopologyRecord tracking the backendNodeId
at each document-order position; remapTopologyIds now reorders all 6
topology arrays before remapping backendNodeIds to solver IDs.
- Fallback: when subjectIds is missing (cached pre-fix data), falls back
to simple remap without reordering.
Unary inStackingContext compilation:
- compileCanonicalClauseToFormula treated inStackingContext as always binary,
creating referenceBinding with undefined selector for unary assertions.
- Fix: add (inStackingContext && !clause.reference) to unaryPredicate/isUnary.
Hard test fixture (fixtures package):
- 29-element geometric fixture with 10 scenarios
- 57 assertions (54 spatial + 3 topology) all pass end-to-end
- Add children branch in convertDomain() alongside descendants —
children() now correctly maps to parentVar: '$parent'
instead of falling through to the default branch which reversed
the parentVar/selector mapping.
- SelectorDomainResolver now handles parentVar domains with no
CSS selector filter (children domain collects all registered
subject IDs, then filters by parent via ancestor index).
- All 1072 tests pass across 14 packages.
- computeRequiredFacts now returns domAncestry flag by scanning formula
bindings for parentVar references (descendants/children domains)
- extractWorld fast-path gate now requires domAncestry === false — formulas
with parentVar domains will always use CDP extraction, which provides
the DOM parentNodeId data needed for ancestor index construction
- Prevents silent indeterminate results when descendants(, sel) is
used on the fast path (which lacks DOM ancestry data)
- Cache key updated to include domAncestry flag ('a') so cached fast vs
CDP results for the same selectors don't collide
- mapFolDiagnostic now accepts optional metrics parameter
- adaptFOLResultToImhotepResult matches solver diagnostics to
formula results by clauseId/formulaId and passes formula-level
metrics (gap, dimensions, stacking context, overflow, etc.)
into the diagnostics output
- Previously mapFolDiagnostic always returned metrics: {} and
sourceRef: {}, making compound/quantified failures undiagnosable
for users investigating contracts
- Extend DomainResolver.resolve() signature to accept optional BindingEnv
so that parentVar domains can be resolved with runtime variable bindings
- Pass BindingEnv through evaluateForAll/evaluateExists to resolver calls
- Add buildAncestorIndex() to precompute DOM ancestor sets from CDP data
- SelectorDomainResolver now filters descendant domains by the bound parent
when domain.parentVar is present and ancestor index is available
- Return undefined for parentVar domains when no ancestor index or env
(prevents silent fallback to global domain resolution)
- Update all test DomainResolver mocks for new resolve interface
- Add 10 unit tests covering ancestor index construction, backward compat,
descendant filtering, exclusion of non-descendants, empty descendants,
missing parentVar/env, and no-ancestor-index safety
- renderer.kind is typed on RendererDescriptor, no cast needed
- buildGeometryWorld returns proper GeometryWorld type (solver variant
differs from core variant, as any required for that cross-package cast)
The proxy in buildExpectation() returned FluentRelation raw (not
proxied), so .and/.or chaining happened outside the assertion store.
The second relation was never stored — checkAll() only evaluated
the first relation (false positive).
Add ensureAndOrProxied() to override .and/.or on FluentRelation
instances so compound builders flow through the assertion store
proxy. Preserves instanceof FluentRelation checks (no JS Proxy on
the instance, just property overrides).
3 regression tests cover .and, .or, and triple-chaining.
Extracted the 629-line checkAll closure from imhotep() into a standalone
makeCheckAll() factory in check-all.ts. Handles temporal dead zone by
passing getUi() getter instead of ui value.
public.ts reduced from 3568 lines to 916 lines (-74.3%). Now contains
only: imports/re-exports, normalizeRuntime, the imhotep() factory
function, property-run internals, and entry points.
Moved the extraction pipeline, formula analysis, selector resolution glue,
CDP extraction, canonical compilation, contract building, cardinality
evaluation, FOL diagnostic mapping, compatibility reporting, and all
module-level extraction state into a dedicated extraction.ts module.
public.ts reduced from 3568 to 1533 lines (-57%). The remaining file
contains only the imhotep() entry point, property-run internals, and
component/story/fixture entry points, plus re-exports for backward
compatibility.
John Dvorak