# CTX-001C – Qualifier-aware Discovery

**Status:** Implemented for integration test  
**Date:** 2026-08-15  
**Context Type:** `https://reconcilix.vocnet.org/context/0011` (`Qualifier`)

## Scope

CTX-001C makes the already transported Qualifier ContextItem effective during Candidate Discovery for:

- xTree vocabulary search (`getSearchVocItemsByTerm`)
- xTree sub-vocabulary search (`getFetchHierarchy`)
- Local Reconciliation Store

No changes are made to ContextItem persistence, OpenRefine request mapping, database schema, ranking, or Discovery Access Audit.

## xTree

The source value remains the lexical search term.

For a command containing:

```text
SourceValue = Bogen
Qualifier   = Architektur
```

Reconcilix forwards:

```text
getSearchVocItemsByTerm
searchtermslist=Bogen
homonymlexicalvalue=Architektur
```

or for a sub-vocabulary:

```text
getFetchHierarchy
term=Bogen
homonymlexicalvalue=Architektur
```

Without a Qualifier ContextItem, `homonymlexicalvalue` remains empty and previous behavior is preserved.

The xTree HTTP client receives the already interpreted qualifier as an optional scalar argument. It has no dependency on Reconcilix Context Type URIs.

## LocalStore

The LocalStore already contains `qualifier` in `terms.json` candidate records.

If no Qualifier ContextItem is supplied, existing search behavior is unchanged.

If a Qualifier ContextItem is supplied, the discovered lexical/token hits are filtered by normalized exact equality:

```text
normalize(candidate.qualifier) = normalize(context qualifier)
```

This is deliberately a disambiguation filter, not fuzzy matching and not a score boost.

Examples:

```text
Bogen                         -> all lexical Bogen candidates
Bogen + Qualifier Architektur -> only candidates qualified as Architektur
Bogen + unknown qualifier     -> no candidates
```

## Cardinality

For the current use cases, a SourceValue supplies at most one Qualifier ContextItem. The implementation consumes the first non-empty `0011` value. Multiple qualifier semantics are outside CTX-001C.

## Shared URI

The controlled Context Type URI is exposed centrally as:

```php
ContextTypeUri::QUALIFIER
```

This avoids duplicating the vocabulary URI in the xTree and LocalStore discovery implementations.

## Tests

Updated/extended tests cover:

- xTree vocabulary qualifier forwarding
- xTree sub-vocabulary qualifier forwarding
- xTree behavior without changes to runtime/audit integration
- LocalStore exact qualifier filtering
- LocalStore unknown qualifier -> empty result

The xTree tests pass in the ED runtime. The container used to prepare this changeset does not provide PHP `mbstring`; therefore the existing LocalStore adapter test cannot execute there because `TextNormalizer` already depends on `mb_strtolower()`. Syntax checks pass; LocalStore runtime verification is required in the normal Reconcilix PHP environment where `mbstring` is installed.