Ontology-KG Virtuoso — Phase-4 Acceptance Run (governed sample intake)

Version: 1.0.0 · Ontology: registry v1.1.0 · Posture: recommend_only (advisory) Claim label: every figure and record below is an illustrative scenario — a committed fixture exercising the governed intake path, never tenant data (demo-fixture rule, AGENTS.md 7.8). Nothing here is a benchmark, pilot, or verified performance result.

This document completes the rollout mission's Phase-4.1 acceptance exercise: profile a sample customer/transaction dataset, map it to the canonical ontology, flag ambiguous mappings, and draft an Ontology Change Proposal (OCP) — while demonstrating the two guardrail refusals. The behavior contract it exercises is skills/ontology-kg-virtuoso/references/semantic_intake_contract.md (20 steps); the canonical concepts are those declared in ontology/ and loaded by src/shared/ontology_registry.py --check.

1. Sample source profile (illustrative fixture)

Source demo_dtc_orders.csv — 12 columns, 500 fixture rows, one row per order line.

Column Inferred type Nulls Distinct Notes
customer_email_hash sha256 hex 0% 214 hashed upstream — raw email never enters the KG
full_name string 2% 209 free text; person vs organization not distinguished
order_id string 0% 350 stable natural key
order_ts ISO-8601 0% 348 business event time
sku / qty / unit_price_usd string / int / decimal 0% 41 / — / — line-item facts
channel enum-like 0% 5 web, email, paid_social, marketplace, pos
consent_flag bool 4% 2 null = no consent (fail-closed)
loyalty_tier string 31% 4 bronze/silver/gold/vip — semantics undeclared

2. Data-to-ontology mapping (governed statuses)

Fine-grained statuses come from the intake contract's vocabulary; each projects onto the envelope's coarse mapping_status (unmapped | mapped | partial | failed).

Source field Canonical target Status Envelope projection
customer_email_hash Customer identity reference (deterministic, hashed) exact_match mapped
order_id, order_ts Transaction (an Event subclass) exact_match mapped
sku Product exact_match mapped
qty, unit_price_usd Transaction attributes exact_match mapped
channel Channel / Touchpoint context narrower_than_canonical mapped
full_name Person or Organization ambiguous unmapped → quarantine
loyalty_tier no declared concept candidate_new_concept unmapped → gap analysis
rows with consent_flag null/false — consent fail-closed quarantined, counted, never persisted

Ambiguity flags raised (quarantined with reason codes, never dropped or forced): 1. full_name has two defensible targets (Person, Organization) — routed to review; no silent guess. 2. loyalty_tier has no defensible declared target — becomes the OCP below rather than an ad-hoc write. No unversioned production-ontology change.

3. Drafted OCP (example draft — NOT a registered proposal)

A registered proposal lives in ontology/proposals/ with a named authentication-derived approver; this example stops at draft by design.

OCP-EXAMPLE-DRAFT — declare LoyaltyTier as a governed Observation concept
Status: draft            Approval level: steward
Proposer: semantic_intake_virtuoso (advisory)
Approver: <empty — steward approval required; self-approval refused>
Problem: loyalty_tier appears in 69% of fixture rows with no declared concept;
  today it can only quarantine as candidate_new_concept.
Proposed state: enterprise concept LoyaltyTier (Observation subclass) with a
  closed value vocabulary; mapping set demo_dtc_orders v2 re-versioned.
Backward compatibility: additive.
Rollback: compensating migration removes the concept and re-quarantines.

4. Guardrail demonstrations (CI-pinned)

  1. Steward-tier self-approval refused. The drafted OCP cannot be auto-approved by the proposing surface: self_approval_of_steward_or_architecture: forbidden (ontology/registry.yaml), pinned by tests/skills/test_ontology_kg_virtuoso.py.
  2. Name-similarity-only merge refused. Two fixture customers named "J. Smith" with different customer_email_hash values are NOT merge candidates: merges require governed deterministic evidence and a reversible split path (name_similarity_only_entity_merge prohibited; test-pinned on every surface).
  3. Probabilistic identity stays recall-only and never enters causal measurement; raw email/phone never enter the KG (hashed references only).

5. What a real run additionally requires

A non-illustrative intake of this source must flow through the canonical envelope (MAPPERS[source](raw) → ingest_gate) via the Cell 6 workflow (src/cells/cell06/workflows/miz3-semantic-intake-v1.json), with tenant scoping, provenance stamping, and the serving-plane checks in docs/skills/ONTOLOGY_KG_VIRTUOSO_REGISTRATION.md passing before any registration claim. Retrieval/reasoning quality figures remain design targets until a live evaluation artifact exists (scripts/ontology_eval.py currently measures the documented registry only).

← All docsView source on GitHub →