[P0] Build semantic-model client consumption, alignment, and query contract

[seonghobae]

Buyer outcome

A consuming product or data platform can load a governed ConceptWeave semantic release and use it safely without knowing generator internals: validate integrity/provenance, resolve concepts, align local vocabularies, inspect mappings, plan semantic queries, and surface conflicts instead of silently coercing meaning.

Client Consumption boundary

Client Consumption owns the provider-independent public semantic_release contract and deterministic admission/integrity/compatibility/diff/resolution/supersession behavior. It does not own consuming-product tenant/purpose authorization, business truth, physical query execution, catalog UX, or LLM/provider routing.

The generator publishes immutable/versioned artifacts; clients consume only released contracts. No client may depend on generator-private classes, prompts, provider payloads, internal persistence tables, orchestration state, mutable PR heads, or cross-service SQL. semantic-data-portal remains catalog/governance/consumption, context-graph-contracts interop, enterprise-architecture-core EA, and contextual-orchestrator production model/provider routing.

A public release seam must preserve release/version identity, ontology/schema versions, concept/relation identifiers, truth/publication status, evidence/provenance references, physical mappings, dimensions/measures/calculation metadata, constraints, compatibility/deprecation metadata, and cryptographic integrity evidence where the contract defines it.

Current dependency-first Client lane — 2026-09-05

Foundation #1 is b538470c963e6524ddc0c3f652a46a4fc8265150. Client PR #5 is exact fcf36c8a99f015b963c9f812787df127ac2e2f9e, Draft/open/mergeable. It is a non-force successor retaining the previous Client semantic tree while adopting current Foundation ancestry; predecessor/local evidence is not exact-head GREEN.

The current source already contains a versioned public semantic-release schema, offline published/authoritative admission, digest/provenance validation, compatibility checks, deterministic resolution/diff behavior, immutable-content collision rejection, and explicit predecessor/successor supersession validation. The earlier issue text that described the supersession/publication schema and fixtures as still missing is stale and is superseded by this authority.

Repository-owned Product CI still cannot materialize from protected main until bootstrap #35 is normally integrated. #35 remains exact a31ae0c2df920f2794f7ddb456795b04797ab472, open/non-Draft/mergeable with central Security/CodeQL/SAST lanes queued and no independent approving review. Do not move #5 merely to chase a newer central workflow revision or transfer predecessor evidence as GREEN.

Next Client gaps after exact-head verification

1. Complete generic explain, match, resolve, validate, diff, compatibility, and query-plan client operations with reproducible receipts rather than product-specific forks.
2. Add ontology/concept alignment APIs that return typed candidate correspondences with lexical/structural/provenance evidence and explicit ambiguity/abstention; they must not mutate either ontology or promote candidates to authority.
3. Use retrieve/filter/match and graph-neighborhood pruning before any optional LLM assistance. Production LLM calls route only through released contextual-orchestrator; deterministic validation, authorization, publication-state checks, and final acceptance remain non-LLM.
4. Keep semantic query planning separate from physical execution. Consuming products retain their own authorized data-access boundary and domain calculations.
5. Add a frozen GRC-shaped conformance fixture only as a consumer of the generic released contract. governance-risk-compliance remains authoritative for its own business truth; no GRC tuple becomes part of ConceptWeave's canonical public model.
6. Verify older-supported, superseded, malformed, unknown-version, partial, conflicting, unpublished and digest-invalid releases fail or resolve exactly according to the public compatibility policy.
7. Publish language-neutral contract/package artifacts only from a release-ready protected head with immutable version/tag/SBOM/provenance/reproducibility/rollback evidence.

Research/evaluation basis

Client matching and alignment work remains traceable to the repository's doctoring register, including Hertling & Paulheim (2023) OLaLa, Giglou et al. (2024) LLMs4OM, Sousa et al. (2025) complex ontology matching, Taboada et al. (2025) prioritized graph search, Barcelos et al. (2025) KROMA, Xiao et al. (2025) LLM4VKG, and Li et al. (2026) systematic review. Every cited work must map to an implemented capability, evaluation family, ADR, or explicit rejection reason; bibliography history is evidence, not a mutable runtime dependency.

Evaluation must cover applicable OAEI-style precision/recall/F1, candidate-retrieval recall, ranking quality, complex correspondences, abstention/ambiguity handling, version compatibility, release-diff correctness, stale/superseded handling, provenance completeness, deterministic digest validation, query-plan correctness, unauthorized-access non-occurrence, reproducibility, and LLM-call reduction versus naive full-ontology prompting where an LLM lane exists.

Acceptance

• a consumer validates and inspects an immutable released contract offline without contacting an LLM provider;
• generated artifacts are usable through stable public contracts without generator internals;
• LLM-assisted client behavior is optional, proposed/inferred, and routed only through contextual-orchestrator;
• alignment outputs retain evidence/truth status and never become authoritative automatically;
• current/older-supported/superseded/malformed/unknown-version/conflicting cases are covered by deterministic conformance fixtures;
• physical mappings and governed dimensions/measures can be resolved while downstream products retain authorization and execution authority;
• owned production doc/test/edge coverage meets the repository's 100% contract and one unchanged exact head reaches terminal protected evidence before integration.

Out of scope

• becoming an enterprise catalog UI;
• owning consuming-product authorization or business-domain truth;
• direct client writes to foreign product databases;
• auto-accepting LLM mappings as authoritative;
• duplicating semantic-data-portal search/catalog responsibilities.

Refs #5, #1, #35.

[seonghobae]

GRC reference-client binding

ContextualWisdomLab/governance-risk-compliance#63 is now the first concrete reference-client program for this Client/release contract. GRC stacked PR ContextualWisdomLab/governance-risk-compliance#64 has already established a test-first provider-neutral SemanticModelClientPort boundary on top of the GRC Analytics root PR.

ConceptWeave #3 must therefore treat GRC as a mandatory golden consumer, not a prose example. Release/client acceptance must include at least:

• offline release validation without an LLM provider;
• exact release/schema/semantic-layer version and SHA-256 content identity;
• publication/truth-status preservation and rejection of proposed/superseded artifacts for authoritative use;
• concept/relation resolution and physical↔semantic mappings usable without generator-private imports;
• governed dimensions/measures with deterministic calculation metadata;
• release diff/compatibility reporting that identifies affected client query assumptions;
• provider-neutral validate, resolve, match, align, diff, compatibility, explain, and query-plan semantics;
• tenant/purpose scope remaining owned by the client and never widened by semantic metadata;
• optional LLM matching/query interpretation only through contextual-orchestrator;
• no direct access from ConceptWeave to GRC application tables;
• golden cross-repo contract fixtures exercised by both ConceptWeave and GRC.

Do not invent a GRC-specific wire protocol inside ConceptWeave. Publish one general versioned Client contract and make the GRC adapter prove that it is sufficient. If the GRC reference case exposes a missing generic capability, fix the generic ConceptWeave contract and re-run both sides.

[seonghobae]

Client/reference update — 2026-09-01

The Client lane now has an expanded research-to-capability register in PR #1. Current accepted Client implications include retrieval-before-prompt, concept/parent/children and neighborhood evidence, deterministic lexical signals, candidate pruning, complex correspondences, LLM-specific hallucination benchmarks, explicit ontology/release versioning, and human validation quality. Agent-OM and GenOM were added as concrete evidence for separated retrieval/matching responsibilities and definition-enriched matching; OM4OV is now explicitly mapped to release-diff/version-compatibility requirements rather than treating versioning as ordinary ontology matching.

The first enterprise reference client remains GRC. Live external state was re-read: governance-risk-compliance#63 is open and GRC PR #64 remains an open Draft stacked on its Analytics root, with a provider-neutral SemanticModelClientPort and exact-head Product evidence recorded on the GRC side. ConceptWeave must satisfy that consumer through a general published semantic_release/Client contract; do not add a GRC-only endpoint or import GRC internals.

Required cross-repo acceptance remains: published release validates offline; proposed/superseded/unknown/malformed/digest-invalid releases fail closed; mappings and governed dimensions/measures preserve provenance/calculation metadata; release diff identifies affected GRC queries; tenant/purpose authorization remains GRC-owned; LLM-assisted matching/query interpretation routes only through contextual-orchestrator.

Foundation PR #1 currently carries a test-first publication-evidence regression and is intentionally not merge-ready until the exact-head RED is observed and repaired.

[seonghobae]

Fresh GRC reference-client evidence — 2026-09-01

Do not use the scheduler's remembered GRC parent SHA. ContextualWisdomLab/governance-risk-compliance#64 is still open/draft/mergeable with child head eea4f054fbfe8901eb1fd4562094e552f93df1e6, but its base branch feat/grc-analytics-query-contract-20260831 has advanced: parent PR #62 is now at 72e0120085430a269a73c0503bcab307fd2e645c (open, non-Draft, mergeable). Therefore #64's prior Product GREEN is useful predecessor evidence only; it is not current integrated GRC reference-client evidence.

ConceptWeave Client acceptance must remain independent of those internal GRC SHAs and use a versioned language-neutral fixture. Before declaring the GRC golden client current, require the GRC owner path to integrate the fresh #62 parent into #64 without destructive history, then re-run its exact-head Product/security/review gates. ConceptWeave's side must prove the same published semantic-release fixture validates offline and that proposed/superseded/unknown-version/digest-invalid variants fail closed.

This is intentionally a cross-repository acceptance coordinate, not permission for ConceptWeave to modify GRC source or PR state.

[seonghobae]

Consensus accepted-search delta — 2026-09-01

The fresh Client/alignment search set adds two relevant studies not yet represented in docs/doctoring/RESEARCH_CAPABILITY_TRACEABILITY.md:

• He, Chen, Dong, & Horrocks (2023), Exploring Large Language Models for Ontology Alignment (current Consensus record: arXiv abs/2309.07172; 64 citations). Class: client; decision: adapt. Product implication: equivalence matching must test concept labels together with bounded structural context, including OAEI Bio-ML-style hard subsets. Add a structural-context ablation beside concept-only matching; zero-shot LLM output remains a correspondence candidate and never authoritative alignment.
• Amini, Saki Norouzi, Hitzler, & Amini (2024), Towards Complex Ontology Alignment using Large Language Models (current Consensus record; pp. 17–31; 35 citations). Class: client; decision: adapt. Product implication: complex-correspondence evaluation should permit bounded ontology modules/rich local context rather than only 1:1 label matching. Add module-size/context-bound receipts and complex-alignment fixtures; rich prompts must not bypass retrieval bounds, evidence provenance, or release truth state.

GenOM (Song, Chen, & Schmidt, 2025) is already mapped in the current register to definition-enriched retrieval/matching and deterministic lexical evidence, and MILA/OLaLa are already mapped to retrieve-before-prompt and OAEI evaluation, so no duplicate rows are needed.

As with the Generation delta, do not move foundation PR #1 solely for this documentation update while its publication-invariant RED head is waiting for a runner. Add these two rows in the first code-current documentation commit after the current RED/GREEN authority-boundary repair.

[seonghobae]

GRC reference-client contract — fresh consumer evidence

Revalidated the first real consumer before defining ConceptWeave's public release contract.

Current GRC integration lane:

• ContextualWisdomLab/governance-risk-compliance#63 remains the cross-repo acceptance issue.
• GRC PR #64 is currently Draft/mergeable at exact head ddee8c9f254a95a8e205a8bb7b6a54f74351395f, stacked on its Analytics root. Its current exact-head Product evidence is recorded by that owning repository; ConceptWeave does not transfer or reinterpret it as ConceptWeave CI evidence.
• GRC's provider-neutral SemanticModelClientPort intentionally defers the concrete adapter until ConceptWeave publishes a versioned contract.

The current GRC consumer boundary requires only a minimal immutable reference today:

release_id
schema_version
content_digest_sha256 (exact lowercase 64-hex)
publication_state

For authoritative GRC use, the release must be published; proposed/superseded releases fail closed. The GRC port also requires validate_release and resolve_term and explicitly does not carry endpoint/provider credentials/raw source/generator-private state.

ConceptWeave must generalize, not mirror GRC's local DTO

The public semantic_release contract should include the GRC minimum while remaining language-neutral and sufficient for other clients. Its first version must define at least:

• release identity and semantic-release schema version;
• immutable content digest/canonicalization rules;
• publication state and release-level truth/governance semantics;
• ontology/semantic-model version coordinates;
• concepts/relations with stable identifiers and truth status;
• evidence/provenance references;
• physical↔semantic mappings;
• dimensions/measures including deterministic source/formula/null/time metadata where present;
• constraints;
• compatibility/deprecation/supersession coordinates.

The Client side must be able to validate those deterministic fields offline, without contacting contextual-orchestrator or any model provider. Matching/alignment/query interpretation may optionally use LLM assistance later, but only after deterministic release validation and only through contextual-orchestrator.

Next executable RED after runner admission

Before implementing release production code, add a failing contract test proving the current repository cannot yet:

1. accept a canonical published release with the GRC-required coordinates;
2. reject proposed/superseded, malformed/unknown-version, non-canonical digest and provenance-invalid releases;
3. resolve a stable concept/mapping from a published fixture without provider access;
4. diff a previous and current release and identify affected semantic identifiers;
5. preserve generated/private implementation independence from the Client package.

Then implement the minimal general Release Contract + Rust-first Client boundary and re-run the same fixture against the GRC reference client. Do not add a network endpoint or GRC-specific adapter merely to satisfy this fixture.

ConceptWeave #4 currently blocks executable RED/GREEN because Product/Security/SAST jobs on PR #1 have not acquired runners. Keep PR #1 exact head stable until that admission boundary moves; queued evidence is not a test result.

[seonghobae]

Fresh Consensus interoperability delta — 2026-09-01

The accepted Client/alignment search set adds two domain-specific but product-relevant studies not yet represented in docs/doctoring/RESEARCH_CAPABILITY_TRACEABILITY.md. They are retained as bounded evidence, not generalized accuracy claims.

• Pournik et al. (2026), Large Language Models for Health Knowledge Modelling in Data Interoperability: A Scoping Review of Methods, Standards, and Applications (Studies in Health Technology and Informatics, 336, 1287–1291; current Consensus citation count 0). Class: client / cross_cutting; decision: research_only. Capability implication: terminology mapping, schema integration, ontology alignment, and KG construction repeatedly use retrieval/embedding/LLM methods, while trustworthy use still needs standardized benchmarks and explainability. Keep this as secondary evidence for benchmark disclosure/explainability requirements; healthcare-specific standards/results do not become ConceptWeave defaults.
• Ozonze, Okonor, Dike, & Adedeji (2026), Enabling interoperability across disparate health data sources using Large Language Models (PLOS Digital Health, 5; current Consensus citation count 0). Class: client; decision: adapt. Capability implication: cross-schema mapping errors should be stratified by semantic confusion, structural misalignment, ambiguous terminology, and terminology variance rather than reported only as aggregate F1. Add these error families to GRC/public cross-repo matching diagnostics and require human/steward validation for authoritative adoption. The healthcare CDM→FHIR setting and web-chat execution are not production architecture for ConceptWeave.

The same fresh search re-returned MILA, KROMA, GenOM, Agent-OM, LLMs4OM, OLaLa, and He et al.; these are already registered or already queued as research deltas, so no duplicate rows should be added. The two rows above belong in the first code-current research-register/bibliography commit after runner admission can execute the resulting ConceptWeave head.

Consensus records used for this delta:

• https://consensus.app/papers/large-language-models-for-health-knowledge-modelling-in-pournik-abbasi/c4329d7897485b1f8c9a6261dbc3b6a0/?utm_source=chatgpt
• https://consensus.app/papers/enabling-interoperability-across-disparate-health-data-ozonze-okonor/b73a1ad613ac581d8cd2bdfcbfc96f22/?utm_source=chatgpt

Live GRC reference-client coordinate was also re-read: governance-risk-compliance#64 remains open/Draft/mergeable at child head 317524f44544cc94506199c5bd8327dd1a083dd7, stacked on Analytics parent head 72e0120085430a269a73c0503bcab307fd2e645c. Its current contract still deliberately defers the concrete adapter until ConceptWeave publishes the general Client/release contract. Do not encode these GRC branch SHAs into the language-neutral wire format or compatibility semantics.

[seonghobae]

GRC reference-client parity exposed a concrete Client-contract mismatch on the current PR #5 stack: GRC's SemanticReleaseRef requires a lowercase SHA-256 content coordinate, while ConceptWeave ReleaseDigest and contracts/semantic-release.schema.json currently accept uppercase A-F as well. This is a canonicalization/interoperability defect, not cryptographic-byte verification yet.

TDD RED head is now 41629bd0f24c4cbe21b3d14dcec645f980e921b7: it adds a Rust regression that requires sha256: + 64 uppercase hex characters to be rejected, plus a JSON fixture semantic-release.invalid-uppercase-digest.json wired into the Product contract suite. No production digest/parser/schema fix has been applied before observing RED. Product run 33528732254, job 99926129453, is currently queued on requested ubuntu-24.04 with runner_id=0/no steps, so the RED remains pending execution and is simultaneously tracked through central .github#712 runner-acquisition RCA. Once the same test-only head actually executes and fails at the intended Rust/schema boundary, the narrow GREEN is to require canonical lowercase [0-9a-f] in both Rust and JSON Schema and then re-run exact-head parity.

This keeps the GRC-specific observation as evidence while repairing the GENERAL ConceptWeave public release contract rather than adding a GRC-only exception.

[seonghobae]

Fresh GRC reference-client evidence, 2026-09-02.

ContextualWisdomLab/governance-risk-compliance#64 is still open/Draft/mergeable at exact head ecfa729a29dfba6cd3c78046cda2d9d2518fe06e, stacked on Analytics parent dbe7f5d42db0bb1b24d8a0b51eae5032d098d7f5. Its exact-head Product push/pull-request runs are GREEN, but supplier Security/SAST/release evidence is intentionally absent and the child remains Draft. GRC currently validates only consumer-owned pre-wire coordinates: Published state, bounded nonblank release/schema identities, and a lowercase SHA-256 content coordinate. It explicitly refuses to invent ConceptWeave schema-version support, provenance/signature representation, mappings, dimensions/measures, or diff wire format before this generic Client contract is published.

That makes the current PR #5 integrity correction a generic contract requirement rather than a GRC special case. The release manifest itself contains artifact_digest; therefore the old wording that the digest covers the entire serialized release manifest is self-referential unless a canonical exclusion rule exists. Current test-only PR #5 head ed22957471f7c62b644f68e4f37bdb86327d8668 instead specifies detached immutable semantic-artifact bytes as the digest scope. Product run 33562998629 / job 100039652518 remains queued before checkout, so this is not yet an observed RED and production/schema/ADR changes remain deliberately withheld.

Cross-repo acceptance after the RED/GREEN sequence: GRC must be able to receive the manifest coordinate, independently hash the detached artifact bytes offline, reject digest mismatch before semantic use, and do so without importing generator internals or acquiring a provider connection. The contract must stay language-neutral so later bindings reproduce the same bytes/digest semantics.

[seonghobae]

Client-track research acceptance delta from the 2026-09-02 Consensus reconciliation staged on Issue #2.

Two relevant Client papers not present in the remembered baseline are now explicit acceptance evidence:

• Song, Chen, & Schmidt (2025), GenOM: ontology matching with description generation and large language models — primary class client; current Consensus metadata: World Wide Web, vol. 29. Add an optional description-enrichment stage before embedding candidate retrieval, preserve exact lexical/structural evidence as independent signals, and evaluate description/retrieval/lexical ablations. Generated definitions remain proposed evidence and never authorize a correspondence.
• He, Chen, Dong, & Horrocks (2023), Exploring Large Language Models for Ontology Alignment — primary class client; current Consensus metadata: ArXiv abs/2309.07172. Use only as research_only support for label + structural-context representations and an OAEI Bio-ML benchmark/ablation adapter; its preliminary status must remain visible.

The accepted set also revalidated OLaLa, LLMs4OM, MILA/PDFS and Complex Matching. Client evaluation therefore needs to expose candidate-retrieval recall, final P/R/F1, complex-correspondence accuracy, representation/context ablations, LLM-call count/reduction and abstention—not only aggregate F1. GRC remains the mandatory enterprise fixture in addition to public OAEI-style fixtures.

No Client source head is moved for this research update while exact 398d8d6878706251397267d8fd8a660d4c2ecc7e Product evidence remains queued before runner assignment.

[seonghobae]

Fresh GRC reference-client conformance snapshot for the Client P0 lane; this is PR-state/acceptance evidence only and does not move the test-only Client head.

• GRC canonical default/protected source remains develop@85da4e1c64e5b46ca3a11ca71654a82b57366a3e.
• governance-risk-compliance#63 is an open P0 issue, not a PR; it continues to require a provider-neutral SemanticModelClientPort, offline published-release validation, mapping/dimension/measure/diff/query-plan consumption, fail-closed degraded mode, tenant/purpose isolation, and no cross-service SQL.
• GRC stacked reference-client PR #64 is currently open/Draft/mergeable at exact child head ecfa729a29dfba6cd3c78046cda2d9d2518fe06e, base feat/grc-analytics-query-contract-20260831@dbe7f5d42db0bb1b24d8a0b51eae5032d098d7f5. It deliberately defers the concrete ConceptWeave adapter until the generic supplier contract is published.
• ConceptWeave Client PR feat(client): add offline semantic release admission contract #5 remains test-only at exact 398d8d6878706251397267d8fd8a660d4c2ecc7e; Product run 33584293306 / rust-quality job 100105057506 is still queued on explicit Ubuntu 24.04 with runner_id=0, no steps/checkout. Therefore the intended missing verify_detached_artifact RED is not yet observable and production release-integrity code remains withheld.

Cross-repo acceptance remains general rather than GRC-specific: the eventual published semantic_release must let #64 replace its placeholder consumer coordinates with the stable ConceptWeave contract while preserving GRC authority and working offline for deterministic admission. Do not wire #64 to ConceptWeave branch internals or moving source.

[seonghobae]

Current Client Consumption progress, 2026-09-02, linked to canonical PR #5 rather than a new branch.

PR #5 exact head is 9df087a5d8f6e46c7e2e91e9c447ee504d00c677, still Draft/open/mergeable and stacked on foundation PR #1. This iteration preserved and completed the concurrent writer's test-first legacy-compatibility lane. RED commit 091c36b24330671952de378d3596afcde5f62351 specified Current, SupportedLegacy, and Unsupported classification plus fail-closed invalid policy. Production commit 2a4596e88d016e01a3bffded7a8436b14d55ec18 adds an explicit current contract version and explicit supported-legacy set; it never infers compatibility from version ordering, and supported legacy releases still require the same Published + Authoritative admission gate. PRD/ARCHITECTURE/CHANGELOG/product-gap reconciliation is carried through the current head.

Exact-head Product run 33606488054, job 100171557081, is still queued before execution and is not treated as GREEN. Existing deterministic client slices remain offline admission, exact concept resolution, release diff, and exact detached-artifact SHA-256 verification. The next Client gaps remain explicit deprecation/supersession semantics, relation/physical-mapping/dimension/measure inspection, stable signature/provenance verification when publication defines the signing contract, research-backed optional match/align/explain through contextual-orchestrator, and a versioned semantic query-plan DTO while consumers retain physical authorization/execution.