fix(parser,ids): keep relationship-resolved classifications on server-parsed stores (#3951)

* fix(parser,ids): distinguish classified-but-unresolved from unclassified on server-parsed stores

Closes #3948. extractClassificationsOnDemand and
extractClassificationSystemsOnDemand (packages/parser/src/classification-resolver.ts)
resolved classification ids via the relationship graph on server-parsed
(source-empty) stores, then unconditionally discarded the result with
`if (!store.source?.length) return [];` right after — a genuinely
classified entity was byte-identical to an unclassified one to every
caller, including the IDS bridge's classification facet.

The classification's own attributes (system name, identification code,
reference chain) need raw STEP bytes to read, and no precomputed table
covers them on a server-parsed store the way the type-inherited property
sets fix (#1795/#1787) had one to fall back to. So both functions now
signal "classified, but unresolved" distinctly from "genuinely
unclassified": extractClassificationsOnDemand returns one
`{ unresolved: true }` entry per resolved id instead of `[]`, and
extractClassificationSystemsOnDemand's return type changes from
`string[]` to `{ names: string[]; unresolved: boolean }`.

The IDS classification facet checker now passes a presence-only ("any
classification") requirement correctly for a classified entity (was a
false CLASSIFICATION_MISSING), and reports a new distinct
CLASSIFICATION_UNRESOLVED failure for a system/value-constrained facet
it cannot verify, instead of silently passing or failing on data it
never read. The viewer's classification-systems panel
(ModelMetadataPanel.tsx) shows an explicit "unavailable on this data
source" state instead of a false "no classification systems".

Claude-Session: https://claude.ai/code/session_01QPHChk3Ve9N519A4kY7436

* fix(ids): surface CLASSIFICATION_UNRESOLVED as a clear message, not the raw enum

Neither describeFailure (translation/service.ts) nor formatFailureReason
(validation/validator.ts) had a case for CLASSIFICATION_UNRESOLVED (added
earlier in this PR for #3948), so both fell through to their default
branch and showed the raw internal enum to the user:

  "Validation failed: CLASSIFICATION_UNRESOLVED"

That string reached the IDS panel (styled identically to a genuine
violation) and the exported HTML/CSV report. Both formatters now say
plainly that the entity is classified but its details could not be read
from this data source, matching the length/voice of the neighbouring
classification cases. ClassificationCard.tsx gets the same "unavailable
on this data source" treatment ModelMetadataPanel.tsx already has,
instead of rendering an empty "Classification / Unknown" card for an
unresolved entry.

No new UI severity was introduced: a fail result has no softer variant
today (StatusIcon's not_applicable is a different, unrelated status), so
a clear message is the fix. The optionality exclusion in validator.ts
that keeps CLASSIFICATION_UNRESOLVED out of `missingFailures` is
untouched — that conservative call (an optional facet that cannot be
verified still fails, rather than silently passing) was deliberate.

Trimmed two unrelated JSDoc blocks to single lines to keep
translation/service.ts and validation/validator.ts within their
checked-in module-size budgets after the new switch cases.

Claude-Session: https://claude.ai/code/session_01QPHChk3Ve9N519A4kY7436

* fix(mcp): forward classification `unresolved` through the playground's own IDS accessor

The playground's `makeIdsAccessor().getClassifications` (used by the
`ids_validate` tool, the chat agent's IDS check) is a separate
reimplementation of `IFCDataAccessor` from `createDataAccessor`
(packages/ids/src/bridge/data-accessor.ts) — the "two paths that must
agree" shape this repo already caught once for materials.

#3948/#3951 added a tri-state `unresolved` marker to
`ClassificationInfo` so a classified-but-unreadable entity
(server-parsed store) reads distinctly from a genuinely unclassified
one. The canonical bridge forwards it; this accessor rebuilt a plain
object from `m.bim.classifications(...)` and dropped the field, so a
classified-but-unresolved entity looked to the IDS engine like a real
classification with an empty system/value — reported as a fabricated
CLASSIFICATION_SYSTEM_MISMATCH/_VALUE_MISMATCH instead of the honest
CLASSIFICATION_UNRESOLVED the viewer's own IDS panel already reports.

`ClassificationData` (@ifc-lite/sdk) gains the same optional
`unresolved` field so the accessor can type-check while forwarding it.

Verified against the real dispatcher + IDS engine: a fixture with a
genuine IfcRelAssociatesClassification edge, forced into the
server-parsed shape (no source bytes, no on-demand map) the same way
#3951's own fixtures do. Reverting the fix reproduces
CLASSIFICATION_SYSTEM_MISMATCH; with the fix, CLASSIFICATION_UNRESOLVED.

Claude-Session: https://claude.ai/code/session_01QPHChk3Ve9N519A4kY7436

---------

Co-authored-by: Louis Trümpler <78563314+louistrue@users.noreply.github.com>

Author: BIMvoice

.changeset/classification-server-parsed-unresolved.md

@@ -0,0 +1,12 @@
+---
+"@ifc-lite/parser": minor
+"@ifc-lite/ids": patch
+---
+
+Fix a server-parsed (source-empty) store reporting a genuinely classified entity as unclassified (#3948). `extractClassificationsOnDemand` and `extractClassificationSystemsOnDemand` (`packages/parser/src/classification-resolver.ts`) resolved classification ids via the relationship graph on server-parsed stores, then unconditionally discarded the result with `if (!store.source?.length) return [];` — a classified entity was byte-identical to an unclassified one to every caller, including the IDS bridge.
+
+The classification's own attributes (system name, identification code, reference chain) genuinely cannot be read without raw STEP bytes, and no equivalent precomputed table exists for them on a server-parsed store (unlike type-inherited property sets, fixed for the same shape of bug in #1795/#1787). So both functions now signal "classified, but unresolved" distinctly from "genuinely unclassified": `extractClassificationsOnDemand` returns one `{ unresolved: true }` entry per resolved id instead of `[]`, and `extractClassificationSystemsOnDemand`'s return type changes from `string[]` to `{ names: string[]; unresolved: boolean }` (a breaking signature change with no known external callers today).
+
+The IDS classification facet checker (`packages/ids/src/facets/classification-facet.ts`) now treats presence-only facets correctly (a classified entity passes an "any classification" requirement instead of a false `CLASSIFICATION_MISSING`), and reports a new `CLASSIFICATION_UNRESOLVED` failure — distinct from `CLASSIFICATION_MISSING`/`CLASSIFICATION_VALUE_MISMATCH`/`CLASSIFICATION_SYSTEM_MISMATCH` — when a system/value-constrained facet cannot be verified because the matching classification's attributes are unreadable, instead of silently passing or failing on data it never read.
+
+Both message formatters (`packages/ids/src/translation/service.ts` and `packages/ids/src/validation/validator.ts`) now have a case for `CLASSIFICATION_UNRESOLVED` — previously both fell through to their `default` branch and showed the raw enum ("Validation failed: CLASSIFICATION_UNRESOLVED") in the viewer's IDS panel and exported reports, indistinguishable from a genuine violation. The message now states plainly that the entity is classified but the details could not be read from this data source. `ClassificationCard.tsx` (properties panel) gets the same "unavailable on this data source" treatment already added to `ModelMetadataPanel.tsx`, instead of rendering an empty "Classification / Unknown" card for an unresolved entry.

.changeset/sdk-classification-unresolved-and-mcp-accessor.md

@@ -0,0 +1,7 @@
+---
+"@ifc-lite/sdk": patch
+---
+
+`ClassificationData` (the SDK's public classification shape) gained an `unresolved?: boolean` field mirroring `@ifc-lite/parser`'s `ClassificationInfo.unresolved` (#3948/#3951), so a classified-but-unreadable entity (server-parsed store) can be told apart from a genuinely unclassified one through the SDK too.
+
+The MCP playground's own `IFCDataAccessor` implementation (`apps/viewer/src/components/mcp/playground-dispatcher.ts`) built its `getClassifications` result from `m.bim.classifications(...)` (this same SDK shape) but dropped the `unresolved` marker — a second, independent reimplementation of the canonical bridge (`packages/ids/src/bridge/data-accessor.ts`) that the viewer's own IDS panel already uses correctly. Without the field, a classified-but-unresolved entity looked to `checkClassificationFacet` like a real classification with an empty system/value, so the agent's `ids_validate` tool reported a fabricated `CLASSIFICATION_SYSTEM_MISMATCH`/`CLASSIFICATION_VALUE_MISMATCH` instead of the honest `CLASSIFICATION_UNRESOLVED` the same fixture produces through the canonical bridge. Fixed by forwarding `unresolved` through the mapping.

apps/viewer/src/components/mcp/playground-dispatcher-classification-unresolved.test.ts

@@ -0,0 +1,112 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * The playground's own `makeIdsAccessor().getClassifications` (used by the
+ * `ids_validate` tool, the chat agent's IDS check) is a SEPARATE
+ * reimplementation of `IFCDataAccessor` from `@ifc-lite/ids`'s
+ * `createDataAccessor` (packages/ids/src/bridge/data-accessor.ts) — the same
+ * "two paths that must agree" shape already caught once for materials (see
+ * playground-dispatcher-materials.test.ts).
+ *
+ * Issue #3948 added a tri-state `unresolved` marker to `ClassificationInfo`
+ * so a classified-but-unreadable entity (server-parsed / source-empty store)
+ * can be told apart from a genuinely unclassified one. The canonical bridge
+ * (`resolveClassifications` / `createDataAccessor`) forwards `unresolved`.
+ * The playground's own `makeIdsAccessor` does not: it rebuilds a plain
+ * object literal from `m.bim.classifications(...)` and drops the
+ * `unresolved` field, so a classified-but-unresolved entity looks to the
+ * IDS engine like a REAL classification with `system: ''` / `value: ''` —
+ * which a system/value-constrained facet then reports as a genuine
+ * CLASSIFICATION_SYSTEM_MISMATCH / CLASSIFICATION_VALUE_MISMATCH instead of
+ * the honest CLASSIFICATION_UNRESOLVED the same fixture reports via the
+ * canonical bridge (packages/ids/src/facets/classification-facet.server-parsed.test.ts).
+ *
+ * A normally-parsed (source-bearing) model never hits this: `source` is
+ * always populated in that case, so this test simulates the server-parsed
+ * shape the way #3948's own fixtures do — parse a real model (so the
+ * relationship graph is genuine), then strip the fields a server-parsed
+ * store never has (`source`, `onDemandClassificationMap`) so the resolver's
+ * existing fallback path is what runs, not a hand-built assumption.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { dispatch, parsePlaygroundModel, type LoadedPlaygroundModel } from './playground-dispatcher.js';
+
+function ifc4(body: string): string {
+  return [
+    'ISO-10303-21;', 'HEADER;', "FILE_DESCRIPTION((''),'2;1');",
+    "FILE_NAME('','',(''),(''),'','','');", "FILE_SCHEMA(('IFC4'));", 'ENDSEC;',
+    'DATA;', body, 'ENDSEC;', 'END-ISO-10303-21;', '',
+  ].join('\n');
+}
+
+const CLASSIFIED_WALL = ifc4(`
+#100=IFCWALL('0Wall0000000000000001',$,'Wall A',$,$,$,$,$,$);
+#300=IFCCLASSIFICATION('Uniclass',$,$,'Uniclass 2015');
+#310=IFCCLASSIFICATIONREFERENCE('','Ss_25_10','Some Name',#300,$,$);
+#320=IFCRELASSOCIATESCLASSIFICATION('0RelCls00000000000001',$,$,$,(#100),#310);
+`);
+
+const SYSTEM_IDS_XML = `<ids xmlns="http://standards.buildingsmart.org/IDS">
+  <info><title>System check</title></info>
+  <specifications>
+    <specification name="Uniclass required" ifcVersion="IFC4" minOccurs="1" maxOccurs="unbounded">
+      <applicability>
+        <entity><name><simpleValue>IFCWALL</simpleValue></name></entity>
+      </applicability>
+      <requirements>
+        <classification><system><simpleValue>Uniclass 2015</simpleValue></system></classification>
+      </requirements>
+    </specification>
+  </specifications>
+</ids>`;
+
+/** Force the parsed model's store into a server-parsed shape: no source
+ *  bytes, no on-demand classification map — the same condition that makes
+ *  `extractClassificationsOnDemand` fall back to the relationship graph and
+ *  report `unresolved: true` (issue #3948). The relationship edge itself
+ *  (`IfcRelAssociatesClassification`) is genuine — built by the real parser
+ *  from the fixture above — not fabricated. */
+function toServerParsedShape(model: LoadedPlaygroundModel): void {
+  const store = model.store as unknown as { source?: Uint8Array; onDemandClassificationMap?: unknown };
+  store.source = new Uint8Array(0);
+  store.onDemandClassificationMap = undefined;
+}
+
+async function runSystemCheck(): Promise<{ status: string; failureType?: string; failureReason?: string }> {
+  const model = await parsePlaygroundModel(
+    new TextEncoder().encode(CLASSIFIED_WALL).buffer as ArrayBuffer,
+    'fixture.ifc',
+  );
+  toServerParsedShape(model);
+  const result = await dispatch(model, 'ids_validate', { ids_xml: SYSTEM_IDS_XML });
+  assert.equal(result.isError, false, `ids_validate should not error: ${result.text}`);
+  const report = result.structured as {
+    specificationResults: Array<{
+      status: string;
+      entityResults: Array<{ requirementResults: Array<{ status: string; failure?: { type: string }; failureReason?: string }> }>;
+    }>;
+  };
+  const req = report.specificationResults[0]?.entityResults[0]?.requirementResults[0];
+  return { status: req?.status ?? '(none)', failureType: req?.failure?.type, failureReason: req?.failureReason };
+}
+
+describe('playground ids_validate — classification facet on a server-parsed-shaped store (#3948/#3951)', () => {
+  it('reports CLASSIFICATION_UNRESOLVED, not a fabricated SYSTEM_MISMATCH, for a classified-but-unresolved entity', async () => {
+    const { status, failureType, failureReason } = await runSystemCheck();
+    assert.equal(status, 'fail', 'entity IS classified but unreadable here, so the facet cannot pass');
+    assert.equal(
+      failureType,
+      'CLASSIFICATION_UNRESOLVED',
+      `expected an honest "cannot verify" reason, got ${failureType} (${failureReason}) — ` +
+        'the playground\'s own IDS accessor dropped the unresolved marker, making the entity ' +
+        'look like a real classification with an empty system, which reads as a genuine mismatch',
+    );
+    assert.notEqual(failureType, 'CLASSIFICATION_SYSTEM_MISMATCH');
+    assert.notEqual(failureType, 'CLASSIFICATION_MISSING');
+  });
+});

apps/viewer/src/components/mcp/playground-dispatcher.ts

@@ -1655,8 +1655,7 @@ const IMPLS: Record<string, ToolImpl> = {
     const t0 = Date.now();
     const initial = v.getSelection();
     if (initial.length > 0) {
-      // Already something selected — return immediately so the agent
-      // doesn't pointlessly stall.
+      // Already something selected — return immediately so the agent doesn't pointlessly stall.
       return {
         text: `Already selected ${initial.length} entit${initial.length === 1 ? 'y' : 'ies'}.`,
         structured: { selection: initial, waitedMs: 0, timedOut: false },
@@ -1871,17 +1870,18 @@ function makeIdsAccessor(m: LoadedPlaygroundModel): import('@ifc-lite/ids').IFCD
       }));
     },
     getClassifications(id) {
+      // Forward `unresolved` (#3948/#3951) — else a classified-but-unresolved entity reads as a fabricated empty match.
       return m.bim.classifications(ref(id)).map((c) => ({
         system: c.system ?? '',
         value: c.identification ?? c.name ?? '',
         name: c.name,
+        unresolved: c.unresolved,
       }));
     },
     getMaterials(id) {
-      // Every variant via the same #1366 lens collector the material
-      // filter/list panels use. Previously only `mat.layers` and the
-      // top-level `mat.name` were checked, so a profile set, constituent
-      // set, or material list was invisible to IDS material requirements.
+      // Every variant via the same #1366 lens collector the material filter/list panels use.
+      // Previously only `mat.layers`/top-level `mat.name` were checked, so a profile set,
+      // constituent set, or material list was invisible to IDS material requirements.
       return lensMaterialNames(m.bim.materials(ref(id))).map((name) => ({ name }));
     },
     getParent(id) {

apps/viewer/src/components/viewer/properties/ClassificationCard.tsx

@@ -11,6 +11,23 @@ import { Tag } from 'lucide-react';
 import type { ClassificationInfo } from '@ifc-lite/parser';
 
 export function ClassificationCard({ classification }: { classification: ClassificationInfo }) {
+  // Matches the "unavailable on this data source" treatment in
+  // ModelMetadataPanel: a server-parsed store (#3948) can prove the entity
+  // is classified via the relationship graph without being able to read
+  // any of the classification's own attributes. Without this branch the
+  // card fell through to the general case below and rendered a
+  // content-free "Classification / Unknown" card.
+  if (classification.unresolved) {
+    return (
+      <div className="border-2 border-emerald-200 dark:border-emerald-800 bg-emerald-50/20 dark:bg-emerald-950/20 w-full max-w-full overflow-hidden flex items-center gap-2 p-2.5">
+        <Tag className="h-3.5 w-3.5 text-emerald-600 dark:text-emerald-400 shrink-0" />
+        <span className="text-xs text-zinc-500 dark:text-zinc-400">
+          Classification present, but unavailable on this data source
+        </span>
+      </div>
+    );
+  }
+
   const displayName = classification.identification || classification.name || 'Unknown';
   const systemName = classification.system;
 

apps/viewer/src/components/viewer/properties/ModelMetadataPanel.tsx

@@ -114,9 +114,12 @@ export function ModelMetadataPanel({ model }: { model: FederatedModel }) {
   // Classification systems used in THIS model (e.g. Uniclass, OmniClass, a
   // national system — a model can carry several at once). Walks only the
   // handful of IfcClassification entities via the byType index, so it's
-  // cheap even on large models — not a per-element scan.
+  // cheap even on large models — not a per-element scan. `unresolved` means
+  // the model HAS classification systems but this store (server-parsed, no
+  // source bytes) can't read their names — distinct from "genuinely none"
+  // (#3948); `names` is always `[]` in that case.
   const classificationSystems = useMemo(() => {
-    if (!dataStore) return [];
+    if (!dataStore) return { names: [], unresolved: false };
     return extractClassificationSystemsOnDemand(dataStore as IfcDataStore);
   }, [dataStore]);
 
@@ -301,13 +304,18 @@ export function ModelMetadataPanel({ model }: { model: FederatedModel }) {
             </h4>
           </div>
           <div className="divide-y divide-zinc-100 dark:divide-zinc-900">
-            {classificationSystems.length === 0 ? (
+            {classificationSystems.unresolved ? (
+              <div className="flex items-center gap-3 px-3 py-2">
+                <BookMarked className="h-3.5 w-3.5 text-zinc-400 shrink-0" />
+                <span className="text-xs text-zinc-500">Classification systems present, but unavailable on this data source</span>
+              </div>
+            ) : classificationSystems.names.length === 0 ? (
               <div className="flex items-center gap-3 px-3 py-2">
                 <BookMarked className="h-3.5 w-3.5 text-zinc-400 shrink-0" />
                 <span className="text-xs text-zinc-500">No classification systems</span>
               </div>
             ) : (
-              classificationSystems.map((system) => (
+              classificationSystems.names.map((system) => (
                 <div key={system} className="flex items-center gap-3 px-3 py-2">
                   <BookMarked className="h-3.5 w-3.5 text-zinc-400 shrink-0" />
                   <span className="text-xs font-mono text-zinc-900 dark:text-zinc-100">

packages/ids/src/bridge/classifications.ts

@@ -14,6 +14,7 @@ interface ClassRecord {
   identification?: string;
   name?: string;
   path?: string[];
+  unresolved?: boolean;
 }
 
 /**
@@ -45,7 +46,7 @@ export function resolveClassifications(
     // even when the value is empty — so optional-cardinality value
     // mismatches register as a value mismatch rather than as a
     // missing-classification (which optional pardons).
-    out.push({ system, value: baseValue, name: c.name });
+    out.push({ system, value: baseValue, name: c.name, unresolved: c.unresolved });
     if (Array.isArray(c.path)) {
       for (const code of c.path) {
         if (code && code !== baseValue) {