- Add scripts/check-structural.js: counts production as any, empty catch,
and ?? 0 patterns; fails CI if counts exceed committed baseline
- Add scripts/.structural-baseline.json: committed baseline (101 as any,
17 empty catch, 62 ?? 0); use --fix-baseline to ratchet down
- Add scripts/ci-verify.sh: ordered pipeline (build → typecheck → lint →
structural → unit tests → E2E) with pass/fail summary
- Add npm scripts: test:structural, test:structural:fix, ci:verify
- Add cache-staleness conformance test: verifies WORLD_CACHE_SCHEMA_VERSION
is prefixed to all cache keys for auto-invalidation on schema changes
- Cache test suite grows from 141 → 142 passes
- Remove defensive ?? 0 fallbacks in buildFailedPredicate that could
silently report false geometry in proof witnesses
- Require all 4 rect fields present before building subjectRect/referenceRect
(was only checking subjectLeft)
- Add explicit undefined guards for observed gap, measured values,
delta, and aspect ratio — return undefined (no failedPredicate)
when critical metrics are missing instead of fabricating 0 defaults
- Generic synthesizeGenericFailedPredicate checks value presence
instead of defaulting metrics[keys] to 0
- Option defaults (minGap, maxGap, tolerance, min, max bounds)
retain ?? 0/?? Infinity as correct neutral values for user parameters
- Add IMH_EXTRACTION_CLEANUP_FAILED and IMH_EXTRACTION_RESIDUAL_ATTRIBUTES
diagnostic codes with severity warning and extraction-error category
- Check for residual data-imhotep-runtime-id attributes before extraction
(both fast-geometry and CDP paths), emit diagnostic if prior run leaked them
- Surface cleanup failures (attribute removal, CDP session detach) as
returned diagnostics instead of silent console.warn
- Wrap CDP sessionManager.detach() in try/catch to prevent finally-block
unhandled throws on closed/navigated pages
- Count injected vs cleaned runtime-id attributes; report mismatch as
IMH_EXTRACTION_CLEANUP_FAILED with metrics
- Move errors array declaration before try block in fast-geometry path
so finally can append cleanup diagnostics
predicates.ts: Add populateDefaultPredicates(registry) accepting any
PredicateRegistry. Add createDefaultPredicateRegistry() factory.
registerDefaultPredicates() now delegates to populateDefaultPredicates
on the global (backward compatible).
logic-engine.ts: Replace globalPredicateRegistry fallback with
createDefaultPredicateRegistry() factory. Each evaluateLogic() call
creates a fresh self-populated registry unless one is explicitly
injected. No shared mutable state between evaluations.
engine.ts: Same pattern for clauses — add populateDefaultClauses(registry),
createDefaultClauseRegistry() factory. registerDefaultClauses() now
delegates to populateDefaultClauses on the global. evaluate() replaces
globalClauseRegistry fallback with createDefaultClauseRegistry().
registry.ts: @deprecated tag on registerClause with migration note.
Both global registries remain for backward compatibility via the
deprecated registerDefault*() functions, but the evaluation engines
no longer depend on them. Every evaluation gets its own registry by
default, so custom predicates registered by one test cannot leak
into another. Tests using explicit registry injection are unaffected.
662 tests pass (315 DSL + 141 core + 149 solver + 57 E2E).
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.
ast.ts: Add optional compoundOperator and compoundParts fields to
RelationAssertion, allowing compound fluent assertions to carry
their .and / .or structure through the AST layer.
fluent.ts: toAst() now emits compoundOperator/compoundParts when
isCompound, closing the gap where compound state was silently
dropped in canonical extraction, preset building, and validation.
lower-to-canonical.ts: Handle RelationAssertion with compound metadata
by lowering each part as a separate grouped clause (same groupId,
same compoundOperator), matching DSL parser compound behavior.
validator.ts: Validate options on each compound part, closing the
false-positive validation gap where only the final relation was checked.
3 lossy code paths (extractCanonicalFromAssertion, presets.toPresetResult,
validateRelation) now preserve compound structure. Primary FOL evaluation
path was already correct (fol-compiler reads compoundParts directly).
658 tests pass.
Cache keys now include a schema version prefix so that world-schema
changes automatically invalidate stale cached extraction results.
Previously two incompatible schema versions would share the same
cache key if URL/selectors/env matched, silently returning stale data.
WORLD_CACHE_SCHEMA_VERSION exported publicly so consumers can
increment it when making schema-incompatible changes to extraction.
658 tests pass.
Replace 21-item hardcoded isKeywordThatCanBePredicate array with
isPredicateName() from PredicateSpec (+ 'size' special case for
fluent API FOL bodies).
Replace 24-item parseRelation relationKinds array with
collectSpatialPredicateNames() from spec. Error message now also
auto-derives from the spec.
595 SDK + 57 E2E tests pass.
Replace 19-entry relationCodes string-to-integer map with
getPredicateRelationCode() from PredicateSpec. Keep only
aspectRatioBetween (15) as local DSL-keyword override.
Replace string-based unary detection ('atLeast'||'atMost') in
compileSimpleAssertionToFormula with isUnaryPredicate() from spec.
595 SDK + 57 E2E tests pass.
Replace 5 static Sets/maps (SPATIAL_RELATIONS, SIZE_RELATIONS,
VALID_OPTIONS, QUANTIFIER_COMPATIBLE, UNARY_RELATIONS) with
derivation from the unified PredicateSpec table:
- collectSpatialPredicateNames / collectSizePredicateNames
for category sets
- getPredicateValidOptions for option validation
- collectQuantifierCompatiblePredicateNames for quantifier checks
- isUnaryPredicate for unary detection
Local override map retained for fluent API dotted size variants
('size.atLeast' etc.) and 'aspectRatioBetween' DSL keyword, which
are input conventions, not distinct predicates.
595 SDK + 57 E2E 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.
compiler.ts: normalizeOptionValue now rejects NaN numbers and empty
strings. Previously typeof NaN === 'number' passed through and
propagated into option values, causing predicate comparisons like
value >= NaN to produce silent wrong results.
grammar.ts: parseAssertion now emits console.warn when silently
skipping unexpected tokens or failed clauses. Previously these
returns-null were invisible to developers.
454 solver+DSL + 57 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
- grammar.ts: add 'between' to isKeywordThatCanBePredicate() so the parser
recognizes it as a valid predicate keyword in forall/exists formula bodies
- compiler.ts: add special case in compileDenseFOLToFormula for
between(, min, max, dimension?) that extracts numeric args into
options ({min, max, dimension}) instead of dropping them in the generic
arg loop. The existing betweenPredicate evaluator already handles these.
- fol-dense-combinations.test.ts: replace GAP test with two verified-working
tests for between and between with dimension
All 27 BUILTIN_PREDICATES now have real evaluators. The
makeNotImplementedPredicate factory and its IMH_FEATURE_NOT_YET_IMPLEMENTED
path were the last remaining NYI scaffolding — no caller existed for it.
IMH_FEATURE_NOT_YET_IMPLEMENTED diagnostic code kept in the taxonomy
as a future fallback, but no evaluator produces it.
- 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.
- CRITICAL: escapeClippingChainOf now has an evaluator (returns indeterminate
with clear diagnostic — full implementation requires fragment-level bounds
analysis). Previously parsed but silently produced IMH_EVALUATOR_MISSING.
- attachedToScrollContainer added to BUILTIN_PREDICATES with evaluator
(checks world.topology.scrollContainerOf). Was only in legacy engine.
- aspectRatio added to BUILTIN_PREDICATES with evaluator (compares
width/height ratio against min/max bounds). Was only in legacy engine.
- Fix all BUILTIN_PREDICATES index references shifted by new entries
(beside 17→20, nextTo 18→21, adjacent 19→22, touching 20→23,
near 21→24, under 22→25, within 23→26, separatedFrom 16→18,
inStackingContext 15→17).
- Register attachedToScrollContainer, escapeClippingChainOf, aspectRatio
in registerDefaultPredicates.
- Zero NYI/not-implemented predicates remain in the registry.
- 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
- evaluateAnd: carry left metrics on left-fail short-circuit,
carry right metrics on right fail/indeterminate
- evaluateOr: carry left metrics on left-pass short-circuit,
carry right metrics on right pass, merge both on double-fail
- evaluateNot: carry operand metrics when operand passes
(so not fails with diagnostic context), carry on indeterminate
- evaluateImplies: carry consequent metrics on fail/indeterminate
This ensures compound formula failures preserve measured geometry
context (gap, dimensions, direction) rather than presenting empty
diagnostics to users investigating layout contract violations.
- Change BUILTIN_PREDICATES[15] arity from 1 to 2 to match binary usage
in the FOL compiler and topology engine
- Update evaluator to handle both unary (does element have stacking context)
and binary (do both elements share the same stacking context) cases
- Binary comparison: both elements must have a valid stacking context
AND their stackingContextOf values must match
- Aligns predicate semantics with the legacy engine in solver/topology.ts
and the topology query layer's inStackingContext(graph, subj, ref?) API
- 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)
- Add 4 unit tests in predicates.test.ts for new contain metrics:
inside hasClippedOverflow (with/without clipping)
clippedBy clipKind (contain:paint=1, overflow=2)
- Unskip and implement clippedBy e2e test with overflow:hidden container
in e2e-edge.test.ts (was stale skipped with 'not yet implemented')
- Add leftAlignedWith/rightAlignedWith/topAlignedWith/bottomAlignedWith
to lexer TokenKind union and keyword map
- Add to grammar.ts consumeRelation() recognized relation kinds
- Dense DSL users can now write: '.a' leftAlignedWith '.b', etc.
(previously returned parser error 'Expected relation')
- Replace makeNotImplementedPredicate stubs for leftAlignedWith,
rightAlignedWith, topAlignedWith, bottomAlignedWith with real
evaluators delegating to alignedWithPredicate with axis option
- Update logic-engine.test.ts to expect real evaluation results
instead of IMH_FEATURE_NOT_YET_IMPLEMENTED
- insidePredicate: add hasClippedOverflow=1 when reference element
clips its content (contain:paint or overflow:hidden) and the
subject overflows beyond the reference bounds
- containsPredicate: same, checking the subject (container) clips
- Reads world.clipping table to determine if the container clips
- Safe when clipping data is absent (unit test fixtures)
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