feat(mapping): add PGE loop for entity/relationship mapping

[FiifiB]

Summary

Introduces agent_mapping_pge, a Planner→Generator→Evaluator (PGE) engine
for entity/relationship mapping, as an additive alternative to the existing
single-agent agent_auto_assignment. The PGE engine plans a source-model,
generates entity and relationship SQL per ontology item, and gates each with a
deterministic evaluator plus an independent semantic critic — replacing the
"implementer marks its own homework" pattern with separation of creator and critic.

This is the second of two independent PGE PRs (ontology generation;
entity/relationship mapping) and is self-contained.

Why additive (both engines retained)

agent_auto_assignment is kept and still reachable via
AgentClient.run_auto_assignment. A new AgentClient.run_mapping_pge gateway
exposes the PGE engine. This lets a downstream orchestrator choose which engine
to run based on source/ontology complexity (a follow-up change).

What changed

• NEW agents/agent_mapping_pge/ — Planner (planner.py), generators
  (generators/{entity,relationship}.py), evaluator
  (evaluator/{deterministic,critic,report}.py), engine orchestrator
  (engine.py), contracts.py, and coverage.py.
  • Engine-enforced coverage: computed from the ontology, not LLM discretion;
    skip[] is advisory and never removes an item.
  • Abstract-superclass UNION derivation + synthetic-endpoint fallback so
    a single failed hub entity can't cascade to drop all relationships.
  • Bounded ThreadPool walk with monotonic progress.
• NEW agents/tools/{planner,evaluation}.py — planner/evaluation terminal
  tools (submit_source_model, submit_evaluation, normalized_value_overlap).
• agents/tools/context.py — adds source_model + semantic_eval_report
  (forward-ref typed); warehouse_id and all existing fields preserved.
• back/objects/mapping/Mapping.py — runs the PGE engine in the auto-assign
  flow and accumulates PGE extras (source_model, mapping_evaluations,
  mapping_run_log); save_mappings_to_session gains three optional params
  (default None, so the legacy path is unaffected). The upstream
  _canonicalize_imported_uris helper is preserved.

Testing

• uv run pytest tests/agents/agent_mapping_pge -q → 90 passed.
• uv run pytest tests/units/agents tests/units/mapping -q → 208 passed.
• New-package imports resolve on the upstream base (v0.5.2).

This pull request and its description were written by Isaac.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Fiifi Botchway seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}