arango-query-core 0.1.0__tar.gz

arango_query_core-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q --tb=short
+      - run: mypy

arango_query_core-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # Trusted publishing is registered against ArthurKeen/arango-query-core
+    # only — don't attempt to publish from the arango-solutions mirror.
+    if: github.repository == 'ArthurKeen/arango-query-core'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" build twine
+      - run: pytest -q --tb=short
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

arango_query_core-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+
+# Dark-factory drift queue (personal agent infrastructure)
+.prd-drift-queue/

arango_query_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `arango-query-core` are documented here, per
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Consumers pin
+exact versions (contextual-data-fabric CC-9) and re-run their golden /
+eval suites on every bump — pre-1.0, **minor** bumps may break the API
+and this file must say so explicitly.
+
+## [0.1.0] - 2026-07-17
+
+Initial standalone release — extraction step 1 (see `docs/PRD.md`).
+
+### Added
+
+- Conceptual↔physical model contract, seeded verbatim from
+  arango-cypher-py @ `5a1392b`: `MappingBundle`, `MappingResolver`,
+  `mapping_from_wire_dict`, `mapping_hash`, collection-name grammar
+  guard, OWL/Turtle ⇄ bundle round-trip (`owl` extra), AQL fragment
+  types, `safe_execute` / `explain_aql`, extension registry,
+  `CoreError` base — with their five test modules.
+- `arango_query_core.nl` — language-agnostic NL→query engine:
+  `NLQueryEngine` (generate→validate→repair loop), LLM providers
+  (OpenAI / OpenRouter / Anthropic with prompt caching), BM25 few-shot
+  retrieval over `(question, query)` pairs (`nl` extra), and the
+  five-seam `QueryLanguageAdapter` protocol (`nl.seams`).
+- Zero hard runtime dependencies; `owl` / `nl` / `dev` extras.
+- CI: ruff (lint + format), mypy, pytest on Python 3.11 / 3.12.
+
+[0.1.0]: https://github.com/ArthurKeen/arango-query-core/releases/tag/v0.1.0

arango_query_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Keen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arango_query_core-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: arango-query-core
+Version: 0.1.0
+Summary: Shared conceptual-model and NL substrate for ArangoDB query transpilers (arango-cypher-py, arango-sparql-py)
+Project-URL: Repository, https://github.com/ArthurKeen/arango-query-core
+Project-URL: Changelog, https://github.com/ArthurKeen/arango-query-core/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ArthurKeen/arango-query-core/issues
+Author: Arthur Keen
+License: MIT License
+        
+        Copyright (c) 2026 Arthur Keen
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: aql,arangodb,cypher,graph-database,nl2query,ontology,owl,sparql,transpiler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.0; extra == 'dev'
+Requires-Dist: rank-bm25>=0.2.2; extra == 'dev'
+Requires-Dist: rdflib>=7.0; extra == 'dev'
+Requires-Dist: requests>=2.31; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: nl
+Requires-Dist: pyyaml>=6.0.0; extra == 'nl'
+Requires-Dist: rank-bm25>=0.2.2; extra == 'nl'
+Requires-Dist: requests>=2.31; extra == 'nl'
+Provides-Extra: owl
+Requires-Dist: rdflib>=7.0; extra == 'owl'
+Description-Content-Type: text/markdown
+
+# arango-query-core
+
+Shared conceptual-model and NL substrate for the ArangoDB query
+transpilers — [`arango-cypher-py`](https://github.com/ArthurKeen/arango-cypher-py)
+(Cypher→AQL) and [`arango-sparql-py`](https://github.com/arango-solutions/arango-sparql-py)
+(SPARQL→AQL) — and, through them, the contextual-data-fabric's
+federated query engine.
+
+Carved out of `arango-cypher-py` (which previously shipped
+`arango_query_core` inside its own wheel) so both transpilers and the
+fabric pin one artifact instead of forking the same code three ways.
+
+## What's here
+
+| Subpackage / module | Purpose |
+| --- | --- |
+| `arango_query_core.mapping` | `MappingBundle` — the conceptual↔physical model contract (entities, relationships, physical annotations) shared by both transpilers and the analyzers' CSI pipeline |
+| `arango_query_core.owl_turtle` / `owl_rdflib` | OWL/Turtle ⇄ MappingBundle round-trip (rdflib optional, via the `owl` extra) |
+| `arango_query_core.aql` / `exec` / `extensions` / `errors` | AQL fragment types, safe execution helpers, extension registry, error base |
+| `arango_query_core.nl` | Language-agnostic NL→query engine: LLM providers (OpenAI / OpenRouter / Anthropic with prompt caching), BM25 few-shot retrieval, and the generate→validate→repair loop |
+| `arango_query_core.nl.seams` | `QueryLanguageAdapter` — the five language-specific seams an adapter implements (grammar prompt, corpus, validator, repair rules, guardrails) |
+
+## What's deliberately NOT here
+
+The per-language adapters. `nl2cypher` (in arango-cypher-py) and
+`nl2sparql` (in arango-sparql-py) implement `QueryLanguageAdapter`
+next to their transpilers, because validating a generated query
+requires the transpiler stack — importing one here would create a
+dependency cycle or force consumers to install both query languages.
+Dependencies point one way: transpilers → this package.
+
+## Install
+
+```bash
+pip install arango-query-core            # mapping/aql core, zero deps
+pip install "arango-query-core[owl]"     # + rdflib OWL round-trip
+pip install "arango-query-core[nl]"      # + NL engine runtime deps
+```
+
+## Versioning
+
+Consumed as a pinned artifact (contextual-data-fabric CC-9): consumers
+pin exact versions and re-run their golden suites on every bump.
+Pre-PyPI, pin a git tag.

arango_query_core-0.1.0/README.md

@@ -0,0 +1,44 @@
+# arango-query-core
+
+Shared conceptual-model and NL substrate for the ArangoDB query
+transpilers — [`arango-cypher-py`](https://github.com/ArthurKeen/arango-cypher-py)
+(Cypher→AQL) and [`arango-sparql-py`](https://github.com/arango-solutions/arango-sparql-py)
+(SPARQL→AQL) — and, through them, the contextual-data-fabric's
+federated query engine.
+
+Carved out of `arango-cypher-py` (which previously shipped
+`arango_query_core` inside its own wheel) so both transpilers and the
+fabric pin one artifact instead of forking the same code three ways.
+
+## What's here
+
+| Subpackage / module | Purpose |
+| --- | --- |
+| `arango_query_core.mapping` | `MappingBundle` — the conceptual↔physical model contract (entities, relationships, physical annotations) shared by both transpilers and the analyzers' CSI pipeline |
+| `arango_query_core.owl_turtle` / `owl_rdflib` | OWL/Turtle ⇄ MappingBundle round-trip (rdflib optional, via the `owl` extra) |
+| `arango_query_core.aql` / `exec` / `extensions` / `errors` | AQL fragment types, safe execution helpers, extension registry, error base |
+| `arango_query_core.nl` | Language-agnostic NL→query engine: LLM providers (OpenAI / OpenRouter / Anthropic with prompt caching), BM25 few-shot retrieval, and the generate→validate→repair loop |
+| `arango_query_core.nl.seams` | `QueryLanguageAdapter` — the five language-specific seams an adapter implements (grammar prompt, corpus, validator, repair rules, guardrails) |
+
+## What's deliberately NOT here
+
+The per-language adapters. `nl2cypher` (in arango-cypher-py) and
+`nl2sparql` (in arango-sparql-py) implement `QueryLanguageAdapter`
+next to their transpilers, because validating a generated query
+requires the transpiler stack — importing one here would create a
+dependency cycle or force consumers to install both query languages.
+Dependencies point one way: transpilers → this package.
+
+## Install
+
+```bash
+pip install arango-query-core            # mapping/aql core, zero deps
+pip install "arango-query-core[owl]"     # + rdflib OWL round-trip
+pip install "arango-query-core[nl]"      # + NL engine runtime deps
+```
+
+## Versioning
+
+Consumed as a pinned artifact (contextual-data-fabric CC-9): consumers
+pin exact versions and re-run their golden suites on every bump.
+Pre-PyPI, pin a git tag.

arango_query_core-0.1.0/arango_query_core/__init__.py

@@ -0,0 +1,46 @@
+from .aql import AqlFragment, AqlQuery
+from .errors import CoreError
+from .exec import AqlExecutor, explain_aql, safe_execute
+from .extensions import ExtensionPolicy, ExtensionRegistry
+from .mapping import (
+    COLLECTION_NAME_RE,
+    IndexInfo,
+    MappingBundle,
+    MappingResolver,
+    MappingSource,
+    PropertyInfo,
+    RelationshipStats,
+    is_valid_collection_name,
+    mapping_from_wire_dict,
+    mapping_hash,
+)
+from .owl_turtle import mapping_to_turtle, turtle_to_mapping
+
+try:
+    from .owl_rdflib import parse_owl_with_rdflib
+except ImportError:
+    parse_owl_with_rdflib = None  # type: ignore[assignment]
+
+__all__ = [
+    "COLLECTION_NAME_RE",
+    "AqlExecutor",
+    "AqlFragment",
+    "AqlQuery",
+    "CoreError",
+    "ExtensionPolicy",
+    "ExtensionRegistry",
+    "explain_aql",
+    "safe_execute",
+    "IndexInfo",
+    "MappingBundle",
+    "MappingResolver",
+    "MappingSource",
+    "PropertyInfo",
+    "RelationshipStats",
+    "is_valid_collection_name",
+    "mapping_from_wire_dict",
+    "mapping_hash",
+    "mapping_to_turtle",
+    "parse_owl_with_rdflib",
+    "turtle_to_mapping",
+]

arango_query_core-0.1.0/arango_query_core/aql.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import CoreError
+
+
+@dataclass
+class AqlFragment:
+    text: str
+    bind_vars: dict[str, Any] = field(default_factory=dict)
+
+    def __add__(self, other: AqlFragment) -> AqlFragment:
+        if not isinstance(other, AqlFragment):
+            return NotImplemented
+        text = self.text.rstrip()
+        other_text = other.text.lstrip()
+        joined = (text + "\n" + other_text).strip() if text and other_text else (text + other_text).strip()
+
+        merged: dict[str, Any] = dict(self.bind_vars)
+        for k, v in other.bind_vars.items():
+            if k in merged and merged[k] != v:
+                raise CoreError(f"Bind var collision for {k!r}", code="BIND_VAR_COLLISION")
+            merged[k] = v
+        return AqlFragment(text=joined, bind_vars=merged)
+
+
+@dataclass(frozen=True)
+class AqlQuery:
+    text: str
+    bind_vars: dict[str, Any]
+    debug: dict[str, Any] | None = None
+    warnings: tuple[str, ...] = ()

arango_query_core-0.1.0/arango_query_core/errors.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+
+class CoreError(Exception):
+    def __init__(self, message: str, *, code: str = "CORE_ERROR"):
+        super().__init__(message)
+        self.code = code

arango_query_core-0.1.0/arango_query_core/exec.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .aql import AqlQuery
+
+
+def _aql_references_bindvar(aql: str, name: str) -> bool:
+    """Whether *aql* references the value bind parameter ``@name``.
+
+    ArangoDB rejects a query (``[ERR 1552] bind parameter '<name>' was
+    not declared in the query``) when ``bind_vars`` carries a key the
+    query text never uses. The Layer-6 session-spread must therefore
+    add ``tenantId`` / ``tenantKey`` **only** when the AQL actually
+    references them — otherwise a perfectly safe global / satellite-only
+    read (e.g. ``FOR c IN Country RETURN c``) explodes at EXPLAIN time
+    just because the session injected an unused tenant bind.
+
+    Matches a single-``@`` *value* reference (``@tenantId``) and
+    deliberately ignores the doubled *collection* form (``@@tenantId``)
+    — tenant scope binds are always value binds. The name boundary
+    stops ``@tenantId`` from matching a longer identifier such as
+    ``@tenantIdentifier``.
+
+    This is a textual heuristic, mirroring Layer 4's textual splice
+    approach. A false positive (``@tenantId`` appearing only inside an
+    AQL comment or string literal) would re-introduce ERR 1552, but the
+    transpiler and Layer 3/4 only ever emit the token in real predicate
+    positions, so the heuristic is safe for produced AQL.
+    """
+    return re.search(r"(?<![@\w])@" + re.escape(name) + r"(?![\w])", aql) is not None
+
+
+@dataclass
+class AqlExecutor:
+    db: Any  # python-arango Database
+
+    def execute(self, query: AqlQuery, *, batch_size: int | None = None, **kwargs: Any) -> Any:
+        aql = self.db.aql
+        return aql.execute(query.text, bind_vars=query.bind_vars, batch_size=batch_size, **kwargs)
+
+
+def safe_execute(
+    *,
+    db: Any,
+    aql: str,
+    client_bind_vars: dict[str, Any] | None,
+    session: Any,
+    validator: Callable[..., None],
+    manifest: Any,
+    sharding_profile: dict[str, Any] | None,
+    collection_to_entity: dict[str, str] | None = None,
+    execute_kwargs: dict[str, Any] | None = None,
+    admin_bypass: bool = False,
+    bypass_reason: str = "",
+) -> tuple[Any, dict[str, Any]]:
+    """Layer 6 — execute AQL only after Layer 5 has certified the plan.
+
+    Implements the contract from ``docs/multitenant_prd.md`` §9 / Wave 7
+    part 4. The bind-var spread order is load-bearing:
+
+    .. code-block:: python
+
+        bind_vars = {
+            **client_bind_vars,
+            "tenantId": session.tenant_id,
+            "tenantKey": session.tenant_key,
+        }
+
+    The session value silently overrides any caller-supplied
+    ``tenantId`` / ``tenantKey``. Layer 5 (``validator``) then
+    verifies the bind-var matches the session — closing T7 (bind-var
+    override) by construction.
+
+    The session binds are spread **only when the AQL references the
+    corresponding ``@tenantId`` / ``@tenantKey`` parameter**. ArangoDB
+    refuses a query that declares a bind value it never uses
+    (``[ERR 1552] bind parameter '<name>' was not declared in the
+    query``), so unconditionally injecting the session tenant would
+    blow up every safe global / satellite-only read at EXPLAIN time.
+    A query that *does* reference the tenant bind always has the
+    session value win; a client-supplied ``tenantId`` on a query that
+    never uses ``@tenantId`` is inert and is dropped (it cannot affect
+    results and would only trip ERR 1552).
+
+    Returns ``(cursor, bind_vars)`` so the caller can echo the final
+    bind vars back to the UI for transparency (§9.2). The validator is
+    injected rather than imported here so ``arango_query_core`` stays
+    free of an ``arango_cypher`` reverse dependency.
+
+    Raises whatever the validator raises — typically
+    ``arango_cypher.tenant_plan_validator.TenantScopeViolation`` — on
+    refusal. The execute never runs in that case.
+    """
+    if session is None:
+        raise PermissionError("safe_execute: no authenticated session; cannot bind tenant context")
+    bind_vars = dict(client_bind_vars or {})
+    if _aql_references_bindvar(aql, "tenantId"):
+        bind_vars["tenantId"] = getattr(session, "tenant_id", None)
+    else:
+        bind_vars.pop("tenantId", None)
+    if _aql_references_bindvar(aql, "tenantKey"):
+        bind_vars["tenantKey"] = getattr(session, "tenant_key", None)
+    else:
+        bind_vars.pop("tenantKey", None)
+
+    validator(
+        db=db,
+        aql=aql,
+        bind_vars=bind_vars,
+        manifest=manifest,
+        sharding_profile=sharding_profile,
+        collection_to_entity=collection_to_entity,
+        session=session,
+        admin_bypass=admin_bypass,
+        bypass_reason=bypass_reason,
+    )
+
+    cursor = db.aql.execute(aql, bind_vars=bind_vars, **(execute_kwargs or {}))
+    return cursor, bind_vars
+
+
+def explain_aql(
+    db: Any,
+    aql: str,
+    bind_vars: dict[str, Any] | None = None,
+) -> tuple[bool, str]:
+    """Plan the query via ``POST /_api/explain`` without executing it.
+
+    Returns ``(ok, error_message)``. On success, *error_message* is the
+    empty string. On failure, it's a short, LLM-friendly description of
+    the planner error — short enough to paste back into a retry prompt,
+    and stripped of stack traces, HTTP payloads, and sensitive detail.
+
+    This is the hook WP-25.3 uses to catch semantic errors
+    (non-existent collections/properties, invalid traversal directions)
+    that ANTLR's grammar-only check happily waves through.  We never
+    execute the query — the ``explain`` endpoint only plans it, so there
+    is no cost to row materialization.
+
+    Safe to call against any read-only or read-write database: the AQL
+    is only planned, never run.  Caller is responsible for ensuring
+    *db* is a valid python-arango database handle.
+    """
+    bv = dict(bind_vars or {})
+    try:
+        result = db.aql.explain(aql, bind_vars=bv)
+    except Exception as exc:
+        return False, _summarize_explain_error(exc)
+
+    if isinstance(result, dict) and result.get("error"):
+        msg = str(result.get("errorMessage") or result.get("error") or "EXPLAIN failed")
+        return False, msg[:500]
+    return True, ""
+
+
+def _summarize_explain_error(exc: BaseException) -> str:
+    """Collapse a python-arango / server error into a single short line.
+
+    python-arango raises ``AQLQueryExplainError`` or ``ArangoServerError``
+    whose ``str()`` can include multi-line HTTP payloads and stack frames.
+    We strip to the most informative line for LLM feedback.
+    """
+    msg = str(exc) or exc.__class__.__name__
+    msg = msg.splitlines()[0] if "\n" in msg else msg
+    msg = msg.strip()
+    if len(msg) > 500:
+        msg = msg[:497] + "..."
+    return msg

arango_query_core-0.1.0/arango_query_core/extensions.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import CoreError
+
+
+@dataclass(frozen=True)
+class ExtensionPolicy:
+    enabled: bool = False
+    allowlist: set[str] | None = None
+    denylist: set[str] | None = None
+
+    def check_allowed(self, name: str) -> None:
+        if not self.enabled:
+            raise CoreError(f"Extensions are disabled (attempted: {name})", code="EXTENSIONS_DISABLED")
+        if self.denylist and name in self.denylist:
+            raise CoreError(f"Extension denied: {name}", code="EXTENSION_DENIED")
+        if self.allowlist is not None and name not in self.allowlist:
+            raise CoreError(f"Extension not in allowlist: {name}", code="EXTENSION_NOT_ALLOWED")
+
+
+FunctionCompiler = Callable[[Any, Any], Any]
+ProcedureCompiler = Callable[[Any, Any], Any]
+
+
+class ExtensionRegistry:
+    def __init__(self, *, policy: ExtensionPolicy | None = None):
+        self.policy = policy or ExtensionPolicy()
+        self._functions: dict[str, FunctionCompiler] = {}
+        self._procedures: dict[str, ProcedureCompiler] = {}
+
+    def register_function(self, name: str, compiler: FunctionCompiler) -> None:
+        self._functions[name] = compiler
+
+    def register_procedure(self, name: str, compiler: ProcedureCompiler) -> None:
+        self._procedures[name] = compiler
+
+    def compile_function(self, name: str, call_ast: Any, ctx: Any) -> Any:
+        self.policy.check_allowed(name)
+        fn = self._functions.get(name)
+        if not fn:
+            raise CoreError(f"Unknown extension function: {name}", code="UNKNOWN_EXTENSION")
+        return fn(call_ast, ctx)
+
+    def compile_procedure(self, name: str, call_ast: Any, ctx: Any) -> Any:
+        self.policy.check_allowed(name)
+        proc = self._procedures.get(name)
+        if not proc:
+            raise CoreError(f"Unknown extension procedure: {name}", code="UNKNOWN_EXTENSION")
+        return proc(call_ast, ctx)