ordel-engine 0.1.0__tar.gz

ordel_engine-0.1.0/.gitignore

@@ -0,0 +1,175 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+
+# Runtime
+.ordel/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+!.env.example
+!.env.prod.example
+
+# Terraform
+**/.terraform/*
+*.tfstate
+*.tfstate.*
+*.tfvars
+!*.tfvars.example
+tfplan
+*.tfplan
+crash.log
+crash.*.log
+
+# Stray root-level node_modules (e.g. an npm install run from the repo root,
+# or the rrweb-dom-stream poc pulling deps up) — never committed.
+/node_modules/
+# Local trace-capture scratch (Langfuse/OTel dumps) — throwaway.
+/scratchpad_traces/
+
+# Node (web/)
+web/node_modules/
+web/.next/
+# Stale build caches moved aside during repairs (e.g. the Kestrel→Ordel
+# rename Turbopack fix). Local-only, safe to delete.
+web/.next.*/
+web/out/
+web/.pnp
+web/.pnp.*
+# TypeScript incremental build cache — local-only, regenerates on each build.
+web/tsconfig.tsbuildinfo
+
+# Node runner (node-runner/) — local Playwright run output
+node-runner/runs/
+node-runner/node_modules/
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+test-results/
+web/test-results/
+web/playwright-report/
+backend/test-results/
+
+# Playwright
+.playwright-cli/
+.playwright-mcp/
+.playwright/
+
+# storageState files — contain live auth tokens; regenerated each run
+web/tests/.auth/
+web/**/.auth/
+
+# Worktrees
+.worktrees/
+
+# Brainstorm sessions
+.superpowers/
+
+# Claude Code config
+.claude.json
+.claude/worktrees/
+*.debug
+
+# Backups (local only)
+backups/
+
+# Local dev notes (credentials, scratch)
+draft-keep.txt
+
+# Binary artifacts
+*.docx
+
+# Test artifacts (manual playtest screenshots + recorder session captures)
+# Live snapshots end up next to whatever directory the tester ran from;
+# pin specific names rather than a blanket *.png so legit UI assets in
+# web/public/ + docs/ don't get caught.
+/*.png
+/web/*.png
+/backend/*.png
+/qa-suite/modules/_session-*.spec.ts
+/backend/bugs.md
+
+# Backend runtime artifact storage (POM persist / local-FS dev mirror)
+/backend/storage/
+
+# Archived docs (historical plans, sessions, completed milestones — not for review)
+docs/archive/
+
+# =============================================================
+# Reference / experimental code (kept locally, not in repo)
+# =============================================================
+
+# Performance testing reference implementation (Phase 2)
+Perf_Flow/
+Perf_Flow.zip
+
+# Archived v1 components (replaced by v2)
+web/components/scripts/archived/
+
+# Unused shared components (experimental)
+web/components/shared/approval-batch.tsx
+web/components/shared/coverage-ring.tsx
+web/components/shared/inline-approval.tsx
+web/components/shared/onboarding-tour.tsx
+
+# Unused studio components (experimental)
+web/components/studio/ArtifactCard.tsx
+web/components/studio/BrowserPreview.tsx
+web/components/studio/NewSessionModal.tsx
+
+# Unused layout components (replaced)
+web/components/layout/app-sidebar.tsx
+web/components/layout/header.tsx
+.claude/scheduled_tasks.lock
+
+# =============================================================
+# Per-developer tool output (regenerable, don't commit)
+# =============================================================
+
+# Antigravity CLI: home-dir symlinks to ~/.gemini/config/projects/*
+.antigravitycli/
+
+# Understand-Anything: knowledge graph cache (regenerate with /understand)
+# Keep the .understandignore input config so all devs share the same graph scope.
+.understand-anything/*
+!.understand-anything/.understandignore
+
+# Local install / runtime logs (uvicorn, npm, pip, alembic, bootstrap, etc.)
+*.log
+*.err
+backend/.secrets/
+*.pem
+.secrets/
+
+# Workflow/agent scratch scripts (throwaway)
+.wf-*
+backend/.wf-*
+
+# Stale: web/e2e was renamed to web/tests long ago — keep the leftover out
+web/e2e/
+docs/conference/demo-video/
+scratchpad-video/
+.overmind.env

ordel_engine-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

ordel_engine-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: ordel-engine
+Version: 0.1.0
+Summary: Ordel's deterministic QA engine — the pure functional core (fingerprint matching + self-heal) that runs locally in the free CLI with no DB, no backend, no LLM.
+Project-URL: Homepage, https://ordel.io
+Author: Ordel
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: fingerprint,qa,selectors,self-healing,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ordel-engine
+
+The deterministic core of the [Ordel free CLI](https://pypi.org/project/ordel-cli/): pure,
+stdlib-only functions for **element fingerprinting** and **self-healing selectors** — no DB,
+no backend, no LLM.
+
+You usually don't install this directly; it's a dependency of `ordel-cli`. It's published
+separately because it's the shared, deterministic substrate the CLI runs locally.
+
+## What's in it
+- **element fingerprint** — a stable, structural fingerprint of a DOM element.
+- **similarity** — deterministic scoring between a recorded element and live candidates.
+- **heal** — recover a broken selector by best-match, or signal `needs_agent` when ambiguous
+  (the boundary a coding agent resolves with its own LLM — the engine never calls one).
+- **capture** — normalize a raw browser capture into fingerprintable signals.
+
+Pure Python, zero third-party dependencies. Apache-2.0.

ordel_engine-0.1.0/README.pypi.md

@@ -0,0 +1,17 @@
+# ordel-engine
+
+The deterministic core of the [Ordel free CLI](https://pypi.org/project/ordel-cli/): pure,
+stdlib-only functions for **element fingerprinting** and **self-healing selectors** — no DB,
+no backend, no LLM.
+
+You usually don't install this directly; it's a dependency of `ordel-cli`. It's published
+separately because it's the shared, deterministic substrate the CLI runs locally.
+
+## What's in it
+- **element fingerprint** — a stable, structural fingerprint of a DOM element.
+- **similarity** — deterministic scoring between a recorded element and live candidates.
+- **heal** — recover a broken selector by best-match, or signal `needs_agent` when ambiguous
+  (the boundary a coding agent resolves with its own LLM — the engine never calls one).
+- **capture** — normalize a raw browser capture into fingerprintable signals.
+
+Pure Python, zero third-party dependencies. Apache-2.0.

ordel_engine-0.1.0/ordel_engine/__init__.py

@@ -0,0 +1,44 @@
+"""Ordel engine — the pure, deterministic QA core for the free CLI.
+
+No DB, no auth, no network, no LLM. Stdlib-only. This is the functional core:
+element fingerprinting + self-healing selectors, called by the CLI's shell
+(which owns all I/O to the local ``.ordel/`` store).
+"""
+
+from __future__ import annotations
+
+from ordel_engine.capture import (
+    fingerprint_from_dict,
+    fingerprint_from_signals,
+    id_is_dynamic,
+)
+from ordel_engine.element_fingerprint import (
+    ElementFingerprint,
+    MatchResult,
+    Verdict,
+    match,
+    score,
+)
+from ordel_engine.heal import (
+    AmbiguityError,
+    HealError,
+    HealFailedError,
+    HealOutcome,
+    heal_by_fingerprint,
+)
+
+__all__ = [
+    "ElementFingerprint",
+    "MatchResult",
+    "Verdict",
+    "match",
+    "score",
+    "fingerprint_from_signals",
+    "fingerprint_from_dict",
+    "id_is_dynamic",
+    "heal_by_fingerprint",
+    "HealOutcome",
+    "HealError",
+    "AmbiguityError",
+    "HealFailedError",
+]

ordel_engine-0.1.0/ordel_engine/capture.py

@@ -0,0 +1,110 @@
+"""DOM signals → :class:`ElementFingerprint`.
+
+The bridge between a browser-captured element and the deterministic matcher. Input is
+the JSON an ``ElementSignals`` capture emits (node-runner
+``recorder-service/locator-inference.ts`` — Node is the SOLE canonicalization
+authority, so the ``*_canon`` fields are consumed VERBATIM here, never recomputed).
+
+Mirrors the backend's canonical constructor
+(``ordel.core.services.observed_graph_service._element_fp``) — in particular its
+``id_is_dynamic`` heuristic: an id containing a digit is treated as dynamic (so it is
+excluded from the identity hash). If either source-of-truth changes, update this too;
+``tests/test_capture.py`` pins the mapping.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ordel_engine.element_fingerprint import ElementFingerprint
+
+
+def _s(v: Any) -> str:
+    return "" if v is None else str(v)
+
+
+def _safe_bbox(v: Any) -> tuple[float, float, float, float] | None:
+    """A bbox is trusted only as a 4-tuple of numbers; anything else (wrong length,
+    non-list, non-numeric) is dropped rather than crashing the geometry scorer (which
+    reads bbox[3]) or the float coercion."""
+    if isinstance(v, (list, tuple)) and len(v) == 4:
+        try:
+            return (float(v[0]), float(v[1]), float(v[2]), float(v[3]))
+        except (TypeError, ValueError):
+            return None
+    return None
+
+
+def _class_tokens(v: Any) -> frozenset[str]:
+    """Coerce class tokens to a frozenset of lowercased strings. Tolerates non-string
+    elements (a stray number in the list would otherwise crash on ``.lower()``)."""
+    return frozenset(str(c).lower() for c in (v or []))
+
+
+def fingerprint_from_dict(d: dict[str, Any]) -> ElementFingerprint:
+    """Build an :class:`ElementFingerprint` from an ElementFingerprint-FIELD dict — the
+    shape persisted in ``.ordel/`` and the shape an agent passes to ``heal_selector``.
+
+    Tolerant by construction: unknown keys are ignored, ``class_tokens`` is coerced to a
+    frozenset, and ``bbox`` is kept only when it is a valid 4-tuple (else dropped). This
+    is the ONE safe field-dict → fingerprint path; ``fingerprint_from_signals`` is the
+    separate node-*signals* path.
+    """
+    known = ElementFingerprint.__dataclass_fields__.keys()
+    data = {k: v for k, v in d.items() if k in known}
+    if "class_tokens" in data:
+        data["class_tokens"] = _class_tokens(data["class_tokens"])
+    data["bbox"] = _safe_bbox(data.get("bbox"))
+    return ElementFingerprint(**data)
+
+
+def id_is_dynamic(raw_id: str | None) -> bool:
+    """A raw ``id`` containing any digit is treated as dynamic (framework-generated
+    like ``mui-4417`` / ``ember123``), so it is not trusted as identity.
+
+    Mirrors ``observed_graph_service._element_fp``:
+    ``bool(el.el_id and any(d in el.el_id for d in _DIGIT))``. Tolerates a non-string id
+    (a numeric ``id`` would otherwise crash iterating it) by coercing to str first.
+    """
+    if raw_id is None:
+        return False
+    return any(ch.isdigit() for ch in str(raw_id))
+
+
+def fingerprint_from_signals(signals: dict[str, Any]) -> ElementFingerprint:
+    """Build an :class:`ElementFingerprint` from a node ``ElementSignals`` dict.
+
+    Canonical identity fields (``*_canon``) are taken verbatim from Node. Raw
+    supporting fields feed Layer-2 fuzzy scoring. State signals are intentionally
+    NOT read — state is never identity.
+    """
+    bbox = _safe_bbox(signals.get("boundingBox"))
+    ordinal = signals.get("ordinal")
+    return ElementFingerprint(
+        # ── canonical identity (Node-emitted, verbatim) ──
+        tag_canon=_s(signals.get("tag_canon")),
+        role_canon=_s(signals.get("role_canon")),
+        accessible_name_canon=_s(signals.get("accessibleName_canon")),
+        testid_canon=_s(signals.get("testid_canon")),
+        name_attr_canon=_s(signals.get("nameAttr_canon")),
+        id_canon=_s(signals.get("id_canon")),
+        # ── raw supporting (Layer-2) ──
+        visible_text=_s(signals.get("text")),
+        neighbor_text=_s(signals.get("neighborText")),
+        class_tokens=_class_tokens(signals.get("classTokens")),
+        href=_s(signals.get("href")),
+        alt=_s(signals.get("alt")),
+        title=_s(signals.get("title")),
+        type_attr=_s(signals.get("type")).lower(),
+        placeholder=_s(signals.get("placeholder")),
+        aria_description=_s(signals.get("ariaDescription")),
+        id_xpath=_s(signals.get("idXpath")),
+        # ── geometry (validated 4-tuple or None) ──
+        bbox=bbox,
+        # ── dynamic-id trust (mirrors backend heuristic on the RAW id) ──
+        id_is_dynamic=id_is_dynamic(signals.get("id")),
+        # ── repeated-element container scoping ──
+        container_key=_s(signals.get("containerKey")),
+        ordinal=ordinal if isinstance(ordinal, int) else None,
+        distinguishing_text=_s(signals.get("distinguishingText")),
+    )

ordel_engine-0.1.0/ordel_engine/element_fingerprint.py

@@ -0,0 +1,387 @@
+"""Element fingerprint + deterministic matcher (Phase 1, foundation).
+
+The recognition layer's per-element identity. Two layers:
+
+- **Layer 1 — exact composite hash** (``fingerprint_hash``): sha256 over the
+  Node-emitted ``*_canon`` identity fields. O(1) relocation when nothing
+  churned. Hash is an OPTIMISATION, not the matcher — on real apps testid is
+  often absent and accessibleName churns with i18n, so the fast path misses
+  and Layer 2 carries the load.
+- **Layer 2 — weighted-overlap fuzzy score** (on hash miss): Similo two-tier
+  weights over the raw signals, consuming the shared comparators in
+  :mod:`ordel.core.similarity`. Survives dynamic ids / xpath churn.
+
+Canonicalization is NODE's job: Python NEVER recomputes the accessible name.
+It hashes the Node-emitted ``*_canon`` fields verbatim (kills Node↔Python
+drift). See ``locator-inference.ts readSignals``.
+
+State signals (expanded/checked/selected/disabled/required) are captured but
+NOT part of identity — a toggled checkbox still matches.
+
+``match(candidate, existing)`` → :class:`MatchResult` with a verdict of
+SAME / AMBIGUOUS / NEW. AMBIGUOUS is the band Phase-4 routes to the thin
+deferred LLM tiebreaker (reusing the heal propose→approve path); Phase 1 only
+produces the deterministic verdict + the narrowed top candidates.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import unicodedata
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from ordel_engine.similarity import (
+    SignalScore,
+    normalized_euclidean,
+    normalized_levenshtein,
+    token_jaccard,
+    weighted_overlap,
+)
+
+# ── Thresholds (shared config; Phase-5 tunes these together with page bands) ──
+# Kept here as module constants; a later phase moves them into the
+# per-app-overridable shared threshold config alongside the page
+# AUTO_MERGE/CANDIDATE bands. Do NOT hardcode at call sites.
+# Phase-5 TUNED via scripts/recognition_bench.py against the VON-Similo Google
+# corpus (84 real DOM-evolution pairs): the 0.70/0.55/0.05 operating point gives
+# 97.5% accuracy / 100% precision / 90.5% recall with ZERO false merges (vs
+# 95.0% / 81% recall at the original 0.85/0.65/0.10) — recovers missed
+# relocations with no added false merges. Re-run the bench if the signal set
+# changes. accept > fuzzy is required by the match() banding logic.
+ACCEPT_THRESHOLD = 0.70
+FUZZY_THRESHOLD = 0.55
+MARGIN = 0.05
+
+# Similo tier weights (plan §TIER WEIGHTS).
+_W_TIER1 = 1.5
+_W_TIER2 = 0.5
+
+# Geometry tolerance scales (px) for the normalized-Euclidean comparators.
+# Generous by design — geometry is a weak supporting signal, not identity.
+_LOCATION_SCALE = 600.0
+_AREA_SCALE = 200.0
+_SHAPE_SCALE = 4.0
+
+
+class Verdict(StrEnum):
+    """The deterministic matcher's decision."""
+
+    SAME = "same"
+    AMBIGUOUS = "ambiguous"  # → Phase-4 LLM tiebreaker / human gate
+    NEW = "new"
+
+
+def canon_text(value: str | None) -> str:
+    """Canonicalise a raw text field the SAME way Node does for *_canon.
+
+    Lowercase + Unicode-NFC + whitespace-collapsed. Used ONLY for Layer-2
+    fuzzy comparison of RAW fields Python receives without a canonical
+    twin — NEVER to recompute an identity field Node already canonicalised.
+    The identity hash hashes the Node ``*_canon`` fields verbatim via
+    :func:`compute_fingerprint_hash`.
+    """
+    if not value:
+        return ""
+    out = unicodedata.normalize("NFC", value)
+    out = " ".join(out.split())
+    return out.lower()
+
+
+@dataclass(frozen=True)
+class ElementFingerprint:
+    """One element's full captured signal record.
+
+    Identity fields are the Node-emitted ``*_canon`` values (already
+    lowercased + NFC + whitespace-collapsed). Raw fields support Layer-2
+    fuzzy comparison. State + geometry are captured but state is never
+    identity.
+    """
+
+    # Canonical identity fields (Node-emitted; hashed VERBATIM).
+    tag_canon: str = ""
+    role_canon: str = ""
+    accessible_name_canon: str = ""
+    testid_canon: str = ""
+    name_attr_canon: str = ""
+    id_canon: str = ""
+
+    # Raw supporting signals (Layer-2 fuzzy).
+    visible_text: str = ""
+    neighbor_text: str = ""
+    class_tokens: frozenset[str] = field(default_factory=frozenset)
+    href: str = ""
+    alt: str = ""
+    title: str = ""
+    type_attr: str = ""
+    placeholder: str = ""
+    aria_description: str = ""
+    xpath: str = ""
+    id_xpath: str = ""
+
+    # Geometry (location/area/shape) from the bounding box.
+    bbox: tuple[float, float, float, float] | None = None  # x, y, w, h
+
+    # ``id`` is trusted in the identity hash only when NOT dynamic.
+    id_is_dynamic: bool = False
+
+    # Container scoping for repeated-element disambiguation (table rows etc.).
+    container_key: str = ""
+    ordinal: int | None = None
+    distinguishing_text: str = ""
+
+    def location(self) -> tuple[float, float]:
+        if self.bbox is None:
+            return (0.0, 0.0)
+        return (self.bbox[0], self.bbox[1])
+
+    def area(self) -> tuple[float]:
+        if self.bbox is None:
+            return (0.0,)
+        return (self.bbox[2] * self.bbox[3],)
+
+    def shape(self) -> tuple[float]:
+        """Aspect ratio (w/h) — invariant to scaling, captures shape."""
+        if self.bbox is None or self.bbox[3] == 0:
+            return (0.0,)
+        return (self.bbox[2] / self.bbox[3],)
+
+
+def compute_fingerprint_hash(fp: ElementFingerprint) -> str:
+    """Layer-1 composite exact hash over the Node-emitted ``*_canon`` fields.
+
+    sha256 over (tag, id*, name_attr, testid, role, accessible_name). ``id``
+    is included ONLY when it passes the dynamic filter. EXCLUDES
+    bbox/xpath/class/href/state — those are Layer-2 / never-identity.
+
+    Container-scoped repeated elements (table rows / grid cells) fold their
+    ordinal + distinguishing leaf text into the hash so row-2's button !=
+    row-5's button deterministically (must_fix #7).
+    """
+    id_part = "" if fp.id_is_dynamic else fp.id_canon
+    parts = [
+        fp.tag_canon,
+        id_part,
+        fp.name_attr_canon,
+        fp.testid_canon,
+        fp.role_canon,
+        fp.accessible_name_canon,
+    ]
+    # Container disambiguation: only folds in when the element is part of a
+    # detected repeated-sibling group (ordinal set). A standalone element
+    # gets ordinal=None and hashes identically to its old pre-container form.
+    if fp.ordinal is not None:
+        parts.append(f"@{fp.container_key}#{fp.ordinal}")
+        parts.append(canon_text(fp.distinguishing_text))
+    joined = "\x1f".join(parts)
+    return hashlib.sha256(joined.encode("utf-8")).hexdigest()
+
+
+def _id_signal(fp: ElementFingerprint) -> tuple[str, bool]:
+    """``id`` is a Tier-1 identity signal only when NOT dynamic."""
+    if fp.id_is_dynamic or not fp.id_canon:
+        return ("", False)
+    return (fp.id_canon, True)
+
+
+def _testid_fast_path(
+    candidate: ElementFingerprint, existing: list[tuple[str, ElementFingerprint]]
+) -> str | None:
+    """Layer 1.5 — exact ``testid`` match, tag + ordinal guarded.
+
+    ``testid`` (a ``data-testid``/QA hook) is author-supplied specifically to
+    give tooling a text-independent identity anchor — it is meant to be the
+    single strongest signal the matcher can receive. But the Layer-1 exact
+    hash (:func:`compute_fingerprint_hash`) ALSO requires
+    ``accessible_name_canon`` equality, which never holds across a translated
+    re-capture (locale/i18n validation, GAP-2109). That forces every
+    translated element through Layer-2 fuzzy scoring, where testid is
+    diluted to one of ~11 equally-weighted Tier-1 signals — several of which
+    (accessible_name, visible_text, neighbor_text, and often geometry from
+    text-driven layout reflow) degrade simultaneously under translation. A
+    testid-identical element can then score below ``FUZZY_THRESHOLD`` and
+    resolve NEW: a silent duplicate of an element the app unambiguously
+    already has.
+
+    This fast path restores testid's intended role as a near-decisive
+    identity anchor when present (non-empty) and equal on both sides.
+    Tag-guarded to catch accidental testid collisions across unrelated
+    element types; ordinal/container-guarded to preserve per-row
+    disambiguation in repeated groups (must_fix #7) when either side is
+    part of a detected repeated-sibling group.
+    """
+    if not candidate.testid_canon:
+        return None
+    for elem_id, fp in existing:
+        if fp.testid_canon != candidate.testid_canon:
+            continue
+        if fp.tag_canon != candidate.tag_canon:
+            continue
+        if candidate.ordinal is not None or fp.ordinal is not None:
+            if candidate.ordinal != fp.ordinal or candidate.container_key != fp.container_key:
+                continue
+        return elem_id
+    return None
+
+
+def score(a: ElementFingerprint, b: ElementFingerprint) -> float:
+    """Layer-2 weighted-overlap fuzzy similarity in ``[0, 1]``.
+
+    Similo two-tier weights over the signal set, with proportional
+    redistribution of absent signals (shared with the page scorer). State
+    signals are excluded from identity scoring by construction.
+    """
+    a_id, a_id_present = _id_signal(a)
+    b_id, b_id_present = _id_signal(b)
+    id_present = a_id_present and b_id_present
+
+    geom = a.bbox is not None and b.bbox is not None
+    loc = (normalized_euclidean(a.location(), b.location(), scale=_LOCATION_SCALE), geom)
+    area = (normalized_euclidean(a.area(), b.area(), scale=_AREA_SCALE), geom)
+    shape = (normalized_euclidean(a.shape(), b.shape(), scale=_SHAPE_SCALE), geom)
+    acc_name = _lev_present(a.accessible_name_canon, b.accessible_name_canon)
+    vis_text = _lev_present(canon_text(a.visible_text), canon_text(b.visible_text))
+    nbr_text = _jaccard_present(_tokens(a.neighbor_text), _tokens(b.neighbor_text))
+    placeholder = _lev_present(canon_text(a.placeholder), canon_text(b.placeholder))
+    aria_desc = _lev_present(canon_text(a.aria_description), canon_text(b.aria_description))
+
+    signals: list[SignalScore] = [
+        # ── Tier 1 (1.5) — the identity spine ──
+        _sig("testid", _W_TIER1, _eq_canon(a.testid_canon, b.testid_canon)),
+        _sig("id", _W_TIER1, (1.0 if a_id == b_id else 0.0, id_present)),
+        _sig("name_attr", _W_TIER1, _eq_canon(a.name_attr_canon, b.name_attr_canon)),
+        _sig("tag", _W_TIER1, _eq_canon(a.tag_canon, b.tag_canon)),
+        _sig("role", _W_TIER1, _eq_canon(a.role_canon, b.role_canon)),
+        _sig("accessible_name", _W_TIER1, acc_name),
+        _sig("visible_text", _W_TIER1, vis_text),
+        _sig("neighbor_text", _W_TIER1, nbr_text),
+        _sig("location", _W_TIER1, loc),
+        _sig("area", _W_TIER1, area),
+        _sig("shape", _W_TIER1, shape),
+        # ── Tier 2 (0.5) — supporting ──
+        _sig("class", _W_TIER2, _jaccard_present_set(a.class_tokens, b.class_tokens)),
+        _sig("href", _W_TIER2, _lev_present(a.href, b.href)),
+        _sig("alt", _W_TIER2, _lev_present(a.alt, b.alt)),
+        _sig("title", _W_TIER2, _lev_present(a.title, b.title)),
+        _sig("type", _W_TIER2, _eq_canon(a.type_attr, b.type_attr)),
+        _sig("placeholder", _W_TIER2, placeholder),
+        _sig("aria_description", _W_TIER2, aria_desc),
+        _sig("id_xpath", _W_TIER2, _lev_present(a.id_xpath, b.id_xpath)),
+    ]
+    return weighted_overlap(signals)
+
+
+def _sig(name: str, weight: float, sim_present: tuple[float, bool]) -> SignalScore:
+    sim, present = sim_present
+    return SignalScore(name=name, weight=weight, similarity=sim, present=present)
+
+
+def _eq_canon(a: str, b: str) -> tuple[float, bool]:
+    """Equality over a canonical field; absent when either side is empty."""
+    if not a or not b:
+        return (0.0, False)
+    return (1.0 if a == b else 0.0, True)
+
+
+def _lev_present(a: str, b: str) -> tuple[float, bool]:
+    if not a and not b:
+        return (0.0, False)
+    return (normalized_levenshtein(a, b), True)
+
+
+def _jaccard_present(a: set[str], b: set[str]) -> tuple[float, bool]:
+    if not a and not b:
+        return (0.0, False)
+    return (token_jaccard(a, b), True)
+
+
+def _jaccard_present_set(a: frozenset[str], b: frozenset[str]) -> tuple[float, bool]:
+    if not a and not b:
+        return (0.0, False)
+    return (token_jaccard(a, b), True)
+
+
+def _tokens(text: str) -> set[str]:
+    return {t for t in canon_text(text).split() if t}
+
+
+@dataclass(frozen=True)
+class MatchResult:
+    """Outcome of :func:`match`.
+
+    - ``verdict`` SAME → ``matched_id`` is the existing element's id.
+    - ``verdict`` AMBIGUOUS → ``top`` holds the narrowed (id, score) pairs
+      Phase-4 hands to the thin LLM tiebreaker / human gate.
+    - ``verdict`` NEW → no existing element cleared the bar.
+    """
+
+    verdict: Verdict
+    matched_id: str | None
+    best_score: float
+    margin: float
+    top: list[tuple[str, float]]
+    exact_hash_hit: bool
+
+
+def match(
+    candidate: ElementFingerprint,
+    existing: list[tuple[str, ElementFingerprint]],
+    *,
+    accept: float = ACCEPT_THRESHOLD,
+    fuzzy: float = FUZZY_THRESHOLD,
+    margin: float = MARGIN,
+) -> MatchResult:
+    """Deterministic element match → SAME / AMBIGUOUS / NEW.
+
+    Decision gates (plan §DECISION GATES):
+      1. exact ``fingerprint_hash`` hit → SAME (O(1) relocation).
+      1.5. else exact ``testid`` match (tag + ordinal guarded) → SAME. Covers
+         the i18n case where ``accessible_name`` churns (breaking gate 1) but
+         the author-supplied testid — the strongest identity anchor when
+         present — did not (see :func:`_testid_fast_path`).
+      2. else argmax over Layer-2 score:
+         - best >= accept AND (best - 2nd) >= margin → SAME (auto).
+         - best in [fuzzy, accept) OR margin too thin → AMBIGUOUS
+           (top-5 → Phase-4 LLM tiebreaker / human gate).
+         - best < fuzzy → NEW.
+
+    Container scoping (repeated-element disambiguation): when the candidate
+    is part of a detected repeated-sibling group, existing rows in the SAME
+    container are preferred — the hash already folds ordinal+leaf-text so the
+    fast path resolves each row distinctly with ZERO LLM tiebreaker calls.
+    """
+    if not existing:
+        return MatchResult(Verdict.NEW, None, 0.0, 0.0, [], exact_hash_hit=False)
+
+    cand_hash = compute_fingerprint_hash(candidate)
+    for elem_id, fp in existing:
+        if compute_fingerprint_hash(fp) == cand_hash:
+            return MatchResult(
+                Verdict.SAME, elem_id, 1.0, 1.0, [(elem_id, 1.0)], exact_hash_hit=True
+            )
+
+    testid_hit = _testid_fast_path(candidate, existing)
+    if testid_hit is not None:
+        return MatchResult(
+            Verdict.SAME, testid_hit, 1.0, 1.0, [(testid_hit, 1.0)], exact_hash_hit=True
+        )
+
+    scored = sorted(
+        ((elem_id, score(candidate, fp)) for elem_id, fp in existing),
+        key=lambda t: t[1],
+        reverse=True,
+    )
+    best_id, best = scored[0]
+    second = scored[1][1] if len(scored) > 1 else 0.0
+    gap = best - second
+    top5 = scored[:5]
+
+    if best >= accept and gap >= margin:
+        return MatchResult(Verdict.SAME, best_id, best, gap, top5, exact_hash_hit=False)
+    # Either the FUZZY band [fuzzy, accept), OR a high best with too thin a
+    # margin (two near-ties): both route to the deferred LLM tiebreaker / human
+    # gate. Since accept > fuzzy (by construction), one ``best >= fuzzy`` check
+    # covers the thin-margin high-score case too.
+    if best >= fuzzy:
+        return MatchResult(Verdict.AMBIGUOUS, None, best, gap, top5, exact_hash_hit=False)
+    return MatchResult(Verdict.NEW, None, best, gap, top5, exact_hash_hit=False)

ordel_engine-0.1.0/ordel_engine/heal.py

@@ -0,0 +1,84 @@
+"""Deterministic self-heal — the free-tier runtime healer.
+
+Assembles the existing pure matcher (:func:`ordel_engine.element_fingerprint.match`)
+into a runtime heal call. NO LLM on any path — the whole free-tier "zero Ordel LLM"
+guarantee lives here by construction:
+
+- confident match  → :class:`HealOutcome` (the healed element id).
+- ambiguous tail   → raise :class:`AmbiguityError` carrying the ranked candidates.
+  The MCP server catches this and hands the tiebreak to the BYO coding agent — the
+  agent's own LLM, never Ordel's.
+- element gone     → raise :class:`HealFailedError` → an ACTIONABLE red, never a
+  silent skip (a testing tool must not hide breakage).
+
+This is a strict improvement over the hosted heal path, which resolves ambiguity by
+silently picking the top candidate; here the agent (which is right there) decides.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ordel_engine.element_fingerprint import ElementFingerprint, MatchResult, Verdict, match
+
+
+class HealError(Exception):
+    """Base — the deterministic engine could not confidently heal on its own."""
+
+
+class AmbiguityError(HealError):
+    """Thin-margin / FUZZY band: several candidates, none a clear winner.
+
+    Carries the ranked ``candidates`` (``[(element_id, score), ...]``) so the caller
+    (the MCP server) can hand them to the BYO agent to adjudicate. On the free path
+    this is what the engine RAISES instead of ever calling an LLM itself.
+    """
+
+    def __init__(self, candidates: list[tuple[str, float]], best: float) -> None:
+        self.candidates = candidates
+        self.best = best
+        super().__init__(
+            f"ambiguous heal: {len(candidates)} candidates, best={best:.3f} below "
+            f"the confident margin — defer to the BYO agent"
+        )
+
+
+class HealFailedError(HealError):
+    """No candidate cleared the fuzzy bar — the element is gone from this snapshot.
+
+    The caller surfaces this as an ACTIONABLE test failure (broken selector + the
+    best-effort candidates), which the coding agent repairs in a later editor
+    session. Never silently skipped.
+    """
+
+    def __init__(self, best: float) -> None:
+        self.best = best
+        super().__init__(f"no heal: best score {best:.3f} below the fuzzy threshold")
+
+
+@dataclass(frozen=True)
+class HealOutcome:
+    """A confident heal. ``exact`` is True when Layer-1 (hash / testid) resolved it,
+    False when the Layer-2 fuzzy scorer carried it (survived real DOM churn)."""
+
+    healed_id: str
+    score: float
+    exact: bool
+
+
+def heal_by_fingerprint(
+    broken: ElementFingerprint,
+    candidates: list[tuple[str, ElementFingerprint]],
+) -> HealOutcome:
+    """Heal a broken element against the current page's elements.
+
+    Pure delegation to the deterministic matcher — no DB, no LLM. Raises
+    :class:`AmbiguityError` / :class:`HealFailedError` for the tail the matcher
+    cannot resolve alone.
+    """
+    result: MatchResult = match(broken, candidates)
+    if result.verdict is Verdict.SAME and result.matched_id is not None:
+        return HealOutcome(result.matched_id, result.best_score, result.exact_hash_hit)
+    if result.verdict is Verdict.AMBIGUOUS:
+        raise AmbiguityError(result.top, result.best_score)
+    raise HealFailedError(result.best_score)

ordel_engine-0.1.0/ordel_engine/similarity.py

@@ -0,0 +1,159 @@
+"""Shared similarity primitives for the recognition layer.
+
+ONE engine consumed by BOTH the element matcher
+(:mod:`ordel.core.element_fingerprint`) AND the shipped page-identity
+scorer (:mod:`ordel.core.services.page_identity_service`). Extracting
+these primitives into a single module is gap #4 of the recognition-layer
+plan: the two weighted-overlap engines users perceive as one feature must
+not drift.
+
+Pure functions, no I/O. Every comparator returns a similarity in ``[0, 1]``
+(1.0 = identical). The weighted aggregator implements the
+"redistribute-proportionally-on-missing-signal" rule so an artifact with an
+absent signal is not penalised for the gap.
+
+Reference: Healenium treecomparing (weighted-LCS + heuristic node distance),
+Similo tiered weighting. Ported to Python; not a dependency.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+# ── String comparators ────────────────────────────────────────────────────
+
+
+def normalized_levenshtein(a: str, b: str) -> float:
+    """Edit-distance similarity in ``[0, 1]``: ``1 - dist / max(len)``.
+
+    Two empty strings are identical (1.0). Case-sensitive — callers that
+    want case-insensitivity should pass already-lowered strings (the
+    identity *_canon fields are pre-lowered Node-side).
+    """
+    if a == b:
+        return 1.0
+    if not a or not b:
+        return 0.0
+    dist = _levenshtein_distance(a, b)
+    longest = max(len(a), len(b))
+    if longest == 0:
+        return 1.0
+    return 1.0 - dist / longest
+
+
+def _levenshtein_distance(a: str, b: str) -> int:
+    """Classic two-row dynamic-programming Levenshtein distance."""
+    if a == b:
+        return 0
+    if not a:
+        return len(b)
+    if not b:
+        return len(a)
+    # Ensure b is the shorter for a narrower row.
+    if len(a) < len(b):
+        a, b = b, a
+    previous = list(range(len(b) + 1))
+    for i, ca in enumerate(a, start=1):
+        current = [i]
+        for j, cb in enumerate(b, start=1):
+            insert = current[j - 1] + 1
+            delete = previous[j] + 1
+            substitute = previous[j - 1] + (0 if ca == cb else 1)
+            current.append(min(insert, delete, substitute))
+        previous = current
+    return previous[-1]
+
+
+def token_jaccard(a: Iterable[str], b: Iterable[str]) -> float:
+    """Jaccard overlap of two token sets in ``[0, 1]``.
+
+    Two empty sets are identical (1.0) — an element with no classes
+    matches another with no classes on this signal rather than being
+    forced to 0.
+    """
+    set_a = set(a)
+    set_b = set(b)
+    if not set_a and not set_b:
+        return 1.0
+    union = set_a | set_b
+    if not union:
+        return 1.0
+    return len(set_a & set_b) / len(union)
+
+
+def exact_ci(a: str | None, b: str | None) -> float:
+    """Case-insensitive exact-equality comparator → 1.0 / 0.0.
+
+    Empty/None on either side → 0.0 (absent, not a match). Callers that
+    want absent-on-both to be treated as "present and equal" should mark
+    the signal absent via the weighted aggregator instead.
+    """
+    if not a or not b:
+        return 0.0
+    return 1.0 if a.strip().lower() == b.strip().lower() else 0.0
+
+
+# ── Numeric comparators ───────────────────────────────────────────────────
+
+
+def normalized_euclidean(
+    a: tuple[float, ...], b: tuple[float, ...], *, scale: float
+) -> float:
+    """Geometry similarity in ``[0, 1]`` from Euclidean distance.
+
+    ``scale`` is the distance at which similarity reaches 0 (clamped). A
+    distance of 0 → 1.0; distance >= ``scale`` → 0.0. Used for bounding-box
+    location/area/shape signals where a tunable tolerance is wanted.
+    """
+    if len(a) != len(b):
+        raise ValueError(f"dimension mismatch: {len(a)} vs {len(b)}")
+    if scale <= 0:
+        return 1.0 if a == b else 0.0
+    dist_sq: float = sum((x - y) ** 2 for x, y in zip(a, b, strict=True))
+    dist: float = dist_sq**0.5
+    if dist >= scale:
+        return 0.0
+    return 1.0 - dist / scale
+
+
+# ── Weighted aggregation with proportional redistribution ─────────────────
+
+
+@dataclass(frozen=True)
+class SignalScore:
+    """One weighted signal's contribution to an overlap score.
+
+    ``present`` distinguishes "the signal is absent on one/both sides"
+    (weight redistributed) from "the signal is present and scored 0.0"
+    (weight applied, drags the score down).
+    """
+
+    name: str
+    weight: float
+    similarity: float
+    present: bool
+
+
+def weighted_overlap(signals: list[SignalScore]) -> float:
+    """Aggregate weighted signals into a ``[0, 1]`` overlap score.
+
+    Implements the "redistribute proportionally" rule: the weights of
+    *present* signals are rescaled to sum to 1.0, so an absent signal
+    neither contributes nor dilutes. When no signal is present the score
+    is 0.0.
+
+    This is the exact algorithm the shipped page-identity scorer uses;
+    extracting it here keeps the element matcher and the page scorer on
+    one implementation.
+    """
+    present_weight_total = sum(s.weight for s in signals if s.present)
+    if present_weight_total == 0.0:
+        return 0.0
+    final = 0.0
+    for s in signals:
+        if not s.present:
+            continue
+        scaled = s.weight / present_weight_total
+        final += scaled * s.similarity
+    return float(final)

ordel_engine-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ordel-engine"
+version = "0.1.0"
+description = "Ordel's deterministic QA engine — the pure functional core (fingerprint matching + self-heal) that runs locally in the free CLI with no DB, no backend, no LLM."
+# PyPI-facing readme only (the repo README.md documents SaaS-internal shims and is NOT shipped).
+readme = "README.pypi.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Ordel" }]
+keywords = ["testing", "qa", "fingerprint", "self-healing", "selectors"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = []  # pure stdlib — the whole point: runs standalone on a dev laptop
+
+[project.urls]
+Homepage = "https://ordel.io"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ordel_engine"]
+
+# Lean sdist: ship ONLY the package + license + the PyPI-facing readme (NOT the repo
+# README.md, which documents SaaS-internal shims). No tests/caches.
+[tool.hatch.build.targets.sdist]
+include = [
+    "ordel_engine",
+    "LICENSE",
+    "README.pypi.md",
+    "pyproject.toml",
+]