Epic: Address Remaining Ontology Platform Gaps (Live Agent Resolution, Advanced Resolvers, SHACL, Spanner/MAKO)

[haiyuan-eng-google]

Description

With the successful implementation of SKOS import support (#57) and runtime entity resolution primitives (#58), the bulk analytics and trace-consumption layers of the SDK are firmly established. However, to fully satisfy the Ontology_Platform_Requirements_Spec_GCP.

This epic tracks the implementation of the four remaining architectural gaps to transition from trace consumption to a fully governed, production-scale reasoning engine.

---

Gap 1: Turn-Time Live Agent Resolution (The Integration Gap)

Feature #58 explicitly scoped out a live-agent integration surface, focusing instead on consumption/analytics over trace data already in BigQuery.

• Requirement: We need a separate, agent-facing package (ideally an extension of the ADK) that allows a live agent to invoke the EntityResolver protocol at turn-time.
• Goal: Enable agents to perform low-latency grounding of brief arguments against the ontology before calling a tool, reusing the existing resolution contract but engineered for live inference.

Gap 2: Advanced LLM & Embedding-Based Resolvers

Currently, the entity resolution primitives only ship with deterministic, SQL-based resolvers (ExactMatchResolver and SynonymResolver). To handle typos, phrasing drift, and complex cross-language semantics, we need to implement the deferred LLM composition patterns.

• Requirement: Promote the Embedding fuzzy matching (P1) pattern into core, leveraging compile-time AI.EMBED and runtime ML.DISTANCE.
• Requirement: Implement LLM disambiguation passes (P2) using AI.GENERATE on ambiguous, multi-match hard cases.

Gap 3: SHACL Constraints & Validation Service (REQ-ONT-030 to 033)

The current pipeline lacks a managed SHACL validator service to automatically enforce cardinality, datatypes, and closed shapes on every materialization batch.

• Requirement: Implement a validator endpoint/Cloud Function that evaluates RDF/Property Graph instances against SHACL shapes.
• Requirement: Ensure that validation failures do not result in silent data drops; instead, the system must generate structured violation nodes inside the BigQuery context graph, making them queryable by shape and parent DecisionPoint.

Gap 4: Spanner Graph Backend & MAKO Governance Bridge

To realize the targeted Two-Layer Reference Architecture (Hot Spanner Runtime for <100ms targeting vs. Warm BigQuery Analytics for deep lineage), the infrastructure must bridge both environments.

• Requirement (Epic B3): Implement the Spanner Graph backend, including Spanner target configurations in bindings and Spanner DDL emission in the compiler.
• Requirement (Epic B5): Build the MAKO Governance Bridge to synchronize the two layers. This must include temporal EVOLVED_FROM replication from Spanner's active negotiations into BigQuery's immutable decision lineage tables to support regulatory auditing (DSA/GDPR).

---

Proposed Acceptance Criteria

• ADK extension published allowing live agents to execute sub-50ms resolution queries against the concept index.
• EmbeddingResolver added to core, alongside compilation flags to generate embedding labels.
• Managed SHACL validator service deployed, emitting Violation nodes directly into the Context Graph upon constraint failure.
• Epic B3 and B5 completed: Spanner DDL generation is supported, and the MAKO bridge successfully replicates EVOLVED_FROM temporal edges from Spanner to BigQuery.