Add example-value extraction; fix Long fields; probe for ephemeral store

kec · kec · commit 2673c9f82ca5 · 2026-07-16T21:51:42.000-07:00
KonceptExtractor now picks each pattern's earliest-authored real semantic as its deterministic example, resolving the referenced component and every field value to a koncept identifier when one exists and plain display text otherwise. Feeds the guide's per-pattern shape tables (term -> schema -> example). KonceptExtractorPatternShapeIT covers both paths; note the integration module never binds failsafe (ike-parent only manages its version), so run it via surefire: mvn -pl integration test -Dtest=KonceptExtractorPatternShapeIT. EntityRecordFactory.externalToInternalObject gains the missing Long case -- any Long-valued field (STAMP Time, RosterOrder, DisplaySequence) previously crashed on external-to-internal conversion. BindingsMain now uses a store only when one is available: it probes for the Load Ephemeral Store controller with the same PluggableService discovery selectControllerByName uses, running composition inside a disposable ephemeral-store lifecycle when a provider is on the classpath (sources like ConstraintPatternSet resolve nids eagerly during PatternBuilder.at()) and store-free under the original documented contract when not, so bindings modules without a store provider (rich-surface-bindings) keep working. A store-free composition that needs nids now fails with explicit add-a-provider guidance. Bridge until the ike-knowledge-spi service contract lands (IKE-Network/ike-issues#850). Refs: IKE-Network/ike-issues#880
diff --git a/entity/src/main/java/dev/ikm/tinkar/entity/EntityRecordFactory.java b/entity/src/main/java/dev/ikm/tinkar/entity/EntityRecordFactory.java
@@ -650,6 +650,7 @@ public static Object externalToInternalObject(Object externalObject) {
             case Float floatField -> floatField;
             case byte[] byteField -> byteField;
             case Integer integerField -> integerField;
+            case Long longField -> longField;
             case String stringField -> stringField.strip();
             case Instant instantField -> instantField;
             case PlanarPoint planarPointField -> planarPointField;
diff --git a/entity/src/main/java/dev/ikm/tinkar/entity/builder/BindingsMain.java b/entity/src/main/java/dev/ikm/tinkar/entity/builder/BindingsMain.java
@@ -15,6 +15,14 @@
  */
 package dev.ikm.tinkar.entity.builder;
 
+import dev.ikm.tinkar.common.service.CachingService;
+import dev.ikm.tinkar.common.service.DataServiceController;
+import dev.ikm.tinkar.common.service.PluggableService;
+import dev.ikm.tinkar.common.service.PrimitiveData;
+import dev.ikm.tinkar.common.service.ServiceKeys;
+import dev.ikm.tinkar.common.service.ServiceProperties;
+
+import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
@@ -27,9 +35,17 @@
  * <p>
  * This is the stable reflective seam for the {@code ike:knowledge-bindings} Maven goal:
  * the goal loads this class in a classloader over the project's dependency classpath and
- * invokes {@link #main(String[])} in-process. Composition is store-free (builders defer
- * nid-minting work to {@link KnowledgeSet#write()}), so no datastore, providers, or
- * service registrations are needed on the generation classpath.
+ * invokes {@link #main(String[])} in-process. Composition is store-free when the
+ * source's builders defer all nid-minting to {@link KnowledgeSet#write()}; sources that
+ * resolve nids eagerly during composition ({@code PatternBuilder.at()}/
+ * {@code flushPendingVersion()} via {@code EntityProxy.nid()}) additionally need a
+ * running {@link PrimitiveData} service. To serve both without forcing a store
+ * dependency onto every consumer's generation classpath, this entry point probes for
+ * the {@value #EPHEMERAL_STORE_CONTROLLER} controller: when present, composition runs
+ * inside a disposable ephemeral-store lifecycle (the same pattern used by other
+ * in-process {@code KnowledgeSetSource} consumers, e.g. {@code FoundationFidelityIT});
+ * when absent, composition runs store-free under the original contract. Nothing is
+ * persisted either way.
  * <p>
  * Arguments: {@code outputDir packageName className [sourceClassName]} — the source
  * class argument selects an implementation when the classpath provides more than one
@@ -46,6 +62,13 @@
 @Deprecated
 public final class BindingsMain {
 
+    /**
+     * Controller name of the disposable in-memory store used around composition when a
+     * provider is on the classpath. Must match the name the probe and
+     * {@link PrimitiveData#selectControllerByName(String)} both see.
+     */
+    private static final String EPHEMERAL_STORE_CONTROLLER = "Load Ephemeral Store";
+
     private BindingsMain() {
     }
 
@@ -81,6 +104,63 @@ public static void main(String[] args) throws Exception {
             source = found.getFirst();
         }
 
+        if (ephemeralStoreAvailable()) {
+            CachingService.clearAll();
+            ServiceProperties.set(ServiceKeys.DATA_STORE_ROOT,
+                    Files.createTempDirectory("ike-bindings").toFile());
+            PrimitiveData.selectControllerByName(EPHEMERAL_STORE_CONTROLLER);
+            PrimitiveData.start();
+            try {
+                composeAndWrite(source, outputDir, packageName, className);
+            } finally {
+                PrimitiveData.stop();
+            }
+        } else {
+            try {
+                composeAndWrite(source, outputDir, packageName, className);
+            } catch (IllegalStateException e) {
+                if (e.getMessage() != null
+                        && e.getMessage().startsWith("No PrimitiveDataService provider available")) {
+                    throw new IllegalStateException(source.getClass().getName()
+                            + " resolved nids during composition, which needs a running data store,"
+                            + " but no \"" + EPHEMERAL_STORE_CONTROLLER + "\" controller is on the"
+                            + " generation classpath. Add an ephemeral-store provider (e.g."
+                            + " network.ike.knowledge:ike-knowledge-provider) as a runtime dependency"
+                            + " of the bindings module.", e);
+                }
+                throw e;
+            }
+        }
+    }
+
+    /**
+     * Probes the classpath for the {@value #EPHEMERAL_STORE_CONTROLLER} controller using
+     * the same discovery mechanism as
+     * {@link PrimitiveData#selectControllerByName(String)}, so the probe and the
+     * subsequent selection cannot disagree.
+     *
+     * @return whether an ephemeral-store controller is available to select
+     */
+    private static boolean ephemeralStoreAvailable() {
+        for (DataServiceController<?> controller : PluggableService.load(DataServiceController.class)) {
+            if (EPHEMERAL_STORE_CONTROLLER.equals(controller.controllerName())) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Composes the source and writes the generated bindings class.
+     *
+     * @param source      the knowledge-set source to compose
+     * @param outputDir   directory the bindings source file is written under
+     * @param packageName package of the generated class
+     * @param className   simple name of the generated class
+     * @throws Exception if composition or writing fails
+     */
+    private static void composeAndWrite(KnowledgeSetSource source, Path outputDir,
+                                        String packageName, String className) throws Exception {
         KnowledgeSet knowledgeSet = source.compose();
         Path file = BindingsWriter.write(knowledgeSet, packageName, className, outputDir);
         System.out.println("Bindings written: " + file + " (" + knowledgeSet.declarations().size()
diff --git a/entity/src/main/java/dev/ikm/tinkar/entity/builder/KonceptExtractor.java b/entity/src/main/java/dev/ikm/tinkar/entity/builder/KonceptExtractor.java
@@ -15,6 +15,8 @@
  */
 package dev.ikm.tinkar.entity.builder;
 
+import dev.ikm.tinkar.common.id.IntIdList;
+import dev.ikm.tinkar.common.id.IntIdSet;
 import dev.ikm.tinkar.common.service.PrimitiveData;
 import dev.ikm.tinkar.common.util.time.DateTimeUtil;
 import dev.ikm.tinkar.coordinate.Calculators;
@@ -35,10 +37,12 @@
 import dev.ikm.tinkar.entity.graph.DiTreeEntity;
 import dev.ikm.tinkar.entity.graph.adaptor.axiom.LogicalAxiom;
 import dev.ikm.tinkar.entity.graph.adaptor.axiom.LogicalExpression;
+import dev.ikm.tinkar.terms.EntityFacade;
 import dev.ikm.tinkar.terms.State;
 import dev.ikm.tinkar.terms.TinkarTerm;
 import org.eclipse.collections.api.list.ImmutableList;
 
+import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.LinkedHashMap;
@@ -175,6 +179,11 @@ public static String extractYaml(Integer narrativePatternNid) {
                     sb.append("  referencedComponentPurpose: ")
                             .append(shape.referencedComponentPurpose()).append('\n');
                 }
+                if (shape.referencedComponentExample() != null) {
+                    sb.append("  referencedComponentExample: ")
+                            .append(exampleYaml(shape.referencedComponentExample(), identifierByNid.values()))
+                            .append('\n');
+                }
                 List<PatternFieldShape> resolvedFields = shape.fields().stream()
                         .filter(f -> f.meaning() != null && f.purpose() != null && f.dataType() != null)
                         .toList();
@@ -184,6 +193,11 @@ public static String extractYaml(Integer narrativePatternNid) {
                         sb.append("    - meaning: ").append(field.meaning()).append('\n');
                         sb.append("      purpose: ").append(field.purpose()).append('\n');
                         sb.append("      dataType: ").append(field.dataType()).append('\n');
+                        if (field.example() != null) {
+                            sb.append("      example: ")
+                                    .append(exampleYaml(field.example(), identifierByNid.values()))
+                                    .append('\n');
+                        }
                     }
                 }
             }
@@ -434,18 +448,28 @@ private static List<Integer> statedParents(int componentNid) {
      *                                   meaning concept, or {@code null} if unresolvable
      * @param referencedComponentPurpose the koncept identifier of the referenced-component
      *                                   purpose concept, or {@code null} if unresolvable
+     * @param referencedComponentExample the referenced component of a real, deterministically
+     *                                   chosen semantic of this pattern already in the store —
+     *                                   a koncept identifier if it resolves to one, otherwise its
+     *                                   display text — or {@code null} if this pattern has no
+     *                                   semantics yet
      * @param fields                     the pattern's own field definitions, in declared order
      */
     private record PatternShape(String referencedComponentMeaning, String referencedComponentPurpose,
-                                 List<PatternFieldShape> fields) {
+                                 String referencedComponentExample, List<PatternFieldShape> fields) {
     }
 
     /**
      * One field of a pattern: its own meaning, purpose, and data type, each a koncept
      * identifier, or {@code null} if that field's concept isn't itself resolvable (no FQN
      * description in this store).
+     *
+     * @param example this field's actual value on the same example semantic used for
+     *                {@link PatternShape#referencedComponentExample()} — a koncept identifier
+     *                if the value resolves to one, otherwise its display text — or {@code null}
+     *                if no example semantic was found
      */
-    private record PatternFieldShape(String meaning, String purpose, String dataType) {
+    private record PatternFieldShape(String meaning, String purpose, String dataType, String example) {
     }
 
     /**
@@ -461,21 +485,107 @@ private static PatternShape patternShape(int patternNid, Map<Integer, String> id
         PatternEntity<PatternEntityVersion> pattern = EntityService.get().getEntityFast(patternNid);
         PatternEntityVersion version = pattern.lastVersion();
         if (version == null) {
-            return new PatternShape(null, null, List.of());
+            return new PatternShape(null, null, null, List.of());
         }
         List<PatternFieldShape> fields = new ArrayList<>();
         for (FieldDefinitionForEntity field : version.fieldDefinitions()) {
             fields.add(new PatternFieldShape(
                     identifierByNid.get(field.meaningNid()),
                     identifierByNid.get(field.purposeNid()),
-                    identifierByNid.get(field.dataTypeNid())));
+                    identifierByNid.get(field.dataTypeNid()),
+                    null));
+        }
+
+        String referencedComponentExample = null;
+        ExampleSemantic example = exampleSemanticOf(patternNid);
+        if (example != null) {
+            referencedComponentExample = displayText(example.referencedComponentNid(), identifierByNid);
+            for (int i = 0; i < fields.size() && i < example.fieldValues().size(); i++) {
+                PatternFieldShape f = fields.get(i);
+                fields.set(i, new PatternFieldShape(f.meaning(), f.purpose(), f.dataType(),
+                        displayText(example.fieldValues().get(i), identifierByNid)));
+            }
         }
+
         return new PatternShape(
                 identifierByNid.get(version.semanticMeaningNid()),
                 identifierByNid.get(version.semanticPurposeNid()),
+                referencedComponentExample,
                 fields);
     }
 
+    /**
+     * The referenced component and field values of one real semantic of {@code patternNid},
+     * chosen deterministically as the earliest-authored (by {@link #earliestStampTime}) —
+     * reproducible across regenerations as long as this store's own authoring order doesn't
+     * change, unlike picking by nid (assignment order is an implementation detail).
+     *
+     * @param patternNid the pattern whose semantics to search
+     * @return the chosen semantic's referenced component and field values, or {@code null} if
+     *         this pattern has no semantics with a resolvable current version in this store
+     */
+    private record ExampleSemantic(int referencedComponentNid, ImmutableList<Object> fieldValues) {
+    }
+
+    private static ExampleSemantic exampleSemanticOf(int patternNid) {
+        int bestNid = -1;
+        long bestTime = Long.MAX_VALUE;
+        for (int semanticNid : EntityService.get().semanticNidsOfPattern(patternNid)) {
+            if (latestVersion(EntityHandle.get(semanticNid).expectSemantic()) == null) {
+                continue;
+            }
+            long time = earliestStampTime(semanticNid);
+            if (time < bestTime) {
+                bestTime = time;
+                bestNid = semanticNid;
+            }
+        }
+        if (bestNid == -1) {
+            return null;
+        }
+        SemanticEntity<?> semantic = EntityHandle.get(bestNid).expectSemantic();
+        return new ExampleSemantic(semantic.referencedComponentNid(), latestVersion(semantic).fieldValues());
+    }
+
+    /**
+     * Display text for one example value — an entity-valued field (or the referenced
+     * component itself) resolves to its koncept identifier when this store has one, otherwise
+     * to {@link PrimitiveData#text}; every other {@link dev.ikm.tinkar.component.FieldDataType}
+     * a semantic field can hold falls back to a plain rendering, mirroring
+     * {@code SemanticVersionRecord.toString()}'s existing per-type handling without depending
+     * on that debug format.
+     */
+    private static String displayText(int nid, Map<Integer, String> identifierByNid) {
+        String identifier = identifierByNid.get(nid);
+        return identifier != null ? identifier : PrimitiveData.text(nid);
+    }
+
+    private static String displayText(Object value, Map<Integer, String> identifierByNid) {
+        return switch (value) {
+            case null -> null;
+            case EntityFacade entity -> displayText(entity.nid(), identifierByNid);
+            case Instant instant -> DateTimeUtil.format(instant);
+            case IntIdList intIdList -> intIdList.isEmpty() ? "(none)"
+                    : String.join(", ", intIdList.intStream()
+                            .mapToObj(memberNid -> displayText(memberNid, identifierByNid)).toList());
+            case IntIdSet intIdSet -> intIdSet.isEmpty() ? "(none)"
+                    : String.join(", ", intIdSet.intStream()
+                            .mapToObj(memberNid -> displayText(memberNid, identifierByNid)).toList());
+            default -> value.toString();
+        };
+    }
+
+    /**
+     * YAML for one example value: a bare, unquoted koncept identifier when {@code value} is one
+     * (matching {@code meaning}/{@code purpose}/{@code dataType}'s existing unquoted style, so
+     * the renderer can badge-link it), otherwise a quoted literal via {@link #yaml} — free text
+     * is vanishingly unlikely to collide with the single-word PascalCase identifiers this store
+     * mints, so no separate reference/literal flag is needed.
+     */
+    private static String exampleYaml(String value, java.util.Collection<String> identifiers) {
+        return identifiers.contains(value) ? value : yaml(value);
+    }
+
     /** The latest version of a semantic by stamp time, or null. */
     private static SemanticEntityVersion latestVersion(SemanticEntity<?> semantic) {
         if (semantic == null) {
diff --git a/integration/src/test/java/dev/ikm/tinkar/integration/builder/KonceptExtractorPatternShapeIT.java b/integration/src/test/java/dev/ikm/tinkar/integration/builder/KonceptExtractorPatternShapeIT.java
@@ -15,6 +15,7 @@
  */
 package dev.ikm.tinkar.integration.builder;
 
+import dev.ikm.tinkar.common.id.PublicIds;
 import dev.ikm.tinkar.entity.builder.ActiveStamp;
 import dev.ikm.tinkar.entity.builder.KnowledgeSet;
 import dev.ikm.tinkar.entity.builder.KonceptExtractor;
@@ -28,6 +29,8 @@
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestInstance;
 
+import java.util.UUID;
+
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 /**
@@ -70,6 +73,12 @@ static void composeAndWrite() {
         TEST_SET.concept("Pattern shape probe field data type (Test)").at(birth)
                 .definition("Field data-type concept for the pattern-shape probe test.")
                 .isA(TinkarTerm.MODEL_CONCEPT);
+        // The referenced component of the example semantic below -- a real concept, so
+        // referencedComponentExample resolves to its own koncept identifier (the bare,
+        // unquoted style), the same way a field value that resolves to a koncept does.
+        TEST_SET.concept("Pattern shape probe subject (Test)").at(birth)
+                .definition("The subject an example semantic of the probe pattern attaches to.")
+                .isA(TinkarTerm.MODEL_CONCEPT);
 
         TEST_SET.pattern("Pattern shape probe pattern (Test)").at(birth)
                 .meaning(TEST_SET.conceptRef("Pattern shape probe meaning (Test)"))
@@ -78,6 +87,14 @@ static void composeAndWrite() {
                         TEST_SET.conceptRef("Pattern shape probe field purpose (Test)"),
                         TEST_SET.conceptRef("Pattern shape probe field data type (Test)"));
 
+        // One real semantic of the probe pattern -- exercises exampleSemanticOf()'s search and
+        // both display-text branches: the referenced component resolves to a koncept identifier
+        // (bare/unquoted), while this plain-String field value does not (quoted literal).
+        TEST_SET.concept("Pattern shape probe subject (Test)").at(birth)
+                .semantic(TEST_SET.patternRef("Pattern shape probe pattern (Test)"),
+                        PublicIds.of(UUID.fromString("7a8b5c1d-2e3f-4a5b-8c9d-0e1f2a3b4c5d")),
+                        "an example field value");
+
         TEST_SET.write();
     }
 
@@ -104,6 +121,20 @@ void patternShapeExtracts() {
                 "the field's meaning/purpose/dataType must resolve correctly:\n" + block);
     }
 
+    @Test
+    @DisplayName("a real semantic's referenced component and field values extract as live examples")
+    void exampleValuesExtractFromARealSemantic() {
+        String yaml = KonceptExtractor.extractYaml();
+        String block = entryBlock(yaml, "PatternShapeProbePattern");
+
+        assertTrue(block.contains("  referencedComponentExample: PatternShapeProbeSubject\n"),
+                "an entity-valued referenced component must resolve to its own koncept "
+                        + "identifier, bare and unquoted:\n" + block);
+        assertTrue(block.contains("      example: \"an example field value\"\n"),
+                "a plain-String field value has no koncept identifier to resolve to, so it "
+                        + "must render as a quoted literal, not a bare identifier:\n" + block);
+    }
+
     /** The text from an entry's identifier header to the next blank line. */
     private static String entryBlock(String yaml, String identifier) {
         int start = yaml.indexOf(identifier + ":\n");
