refactor(extension): Optional return for tryFrom / findKnown

@nullable return types let callers silently dereference; Optional
forces the caller to handle the empty case at the type level and
reads as idiomatic modern Java per CLAUDE.md.

- ExtensionId.tryFrom: Optional<ExtensionId>
- Extension.findKnown: Optional<Extension>
- Callers updated: Chunk.as, VortexWriter.writeChunk, JdbcImporter.fillExtensionCell, VortexInspectorTui.formatValue.
- ExtensionIdTest assertions: isSameAs -> contains / isNull -> isEmpty.
- ExtensionTestSupport.tzMeta tz arg stays @nullable (string, not a result).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dfa1

cli/src/main/java/io/github/dfa1/vortex/cli/tui/VortexInspectorTui.java

@@ -680,7 +680,8 @@ record Failed(String message) implements DataState {
         private static String formatValue(Array array, int i, DType declared) {
             if (declared instanceof DType.Extension ext
                     && io.github.dfa1.vortex.extension.ExtensionId.tryFrom(ext.extensionId())
-                            == io.github.dfa1.vortex.extension.ExtensionId.VORTEX_DATE) {
+                            .filter(id -> id == io.github.dfa1.vortex.extension.ExtensionId.VORTEX_DATE)
+                            .isPresent()) {
                 try {
                     return io.github.dfa1.vortex.extension.DateExtension.INSTANCE.decode(array, i).toString();
                 } catch (RuntimeException e) {

core/src/main/java/io/github/dfa1/vortex/extension/Extension.java

@@ -4,6 +4,7 @@
 import io.github.dfa1.vortex.core.VortexException;
 
 import java.util.Collection;
+import java.util.Optional;
 
 /// Contract for a Vortex extension type — pairs the wire-format identity
 /// (an [ExtensionId]) with a factory for the matching [DType.Extension]
@@ -37,23 +38,19 @@ default Object encodeAll(DType.Extension dtype, Collection<?> values) {
         throw new VortexException("encode not supported for " + extensionId());
     }
 
-    /// Resolves a {@link DType.Extension} to its spec-defined singleton, or
-    /// {@code null} when the wire id isn't one of the four spec extensions.
+    /// Resolves a {@link DType.Extension} to its spec-defined singleton.
     /// Closes over the closed-set spec impls; third-party extensions go
     /// through {@link io.github.dfa1.vortex.encoding.Registry#lookup(ExtensionId)}.
     ///
     /// @param dtype declared extension dtype
-    /// @return matching spec extension singleton, or {@code null}
-    static @org.jspecify.annotations.Nullable Extension findKnown(DType.Extension dtype) {
-        ExtensionId id = ExtensionId.tryFrom(dtype.extensionId());
-        if (id == null) {
-            return null;
-        }
-        return switch (id) {
+    /// @return matching spec extension singleton, or empty when the wire id
+    ///         isn't one of the four spec extensions
+    static Optional<Extension> findKnown(DType.Extension dtype) {
+        return ExtensionId.tryFrom(dtype.extensionId()).map(id -> switch (id) {
             case VORTEX_DATE -> DateExtension.INSTANCE;
             case VORTEX_TIME -> TimeExtension.INSTANCE;
             case VORTEX_TIMESTAMP -> TimestampExtension.INSTANCE;
             case VORTEX_UUID -> UuidExtension.INSTANCE;
-        };
+        });
     }
 }

core/src/main/java/io/github/dfa1/vortex/extension/ExtensionId.java

@@ -3,6 +3,7 @@
 import io.github.dfa1.vortex.core.VortexException;
 
 import java.util.Map;
+import java.util.Optional;
 import java.util.function.Function;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
@@ -48,9 +49,9 @@ public static ExtensionId from(String id) {
     /// Non-throwing lookup for a raw extension id string.
     ///
     /// @param id raw extension id string
-    /// @return matching constant, or {@code null} if not a known spec extension
-    public static @org.jspecify.annotations.Nullable ExtensionId tryFrom(String id) {
-        return LOOKUP.get(id);
+    /// @return matching constant, or empty if not a known spec extension
+    public static Optional<ExtensionId> tryFrom(String id) {
+        return Optional.ofNullable(LOOKUP.get(id));
     }
 
     /// Returns the canonical wire-format id string.

core/src/test/java/io/github/dfa1/vortex/extension/ExtensionIdTest.java

@@ -20,14 +20,14 @@ class ExtensionIdTest {
     void tryFrom_knownIds_returnEnumConstant(String wire, ExtensionId expected) {
         // Given / When / Then — wire string round-trips to the enum constant
         // so the LOOKUP map stays in sync with the enum definition
-        assertThat(ExtensionId.tryFrom(wire)).isSameAs(expected);
+        assertThat(ExtensionId.tryFrom(wire)).contains(expected);
     }
 
     @Test
-    void tryFrom_unknownId_returnsNull() {
+    void tryFrom_unknownId_returnsEmpty() {
         // Given — open-world extension id; library doesn't recognise it
         // When / Then — non-throwing miss so the registry can route to passthrough
-        assertThat(ExtensionId.tryFrom("acme.geopoint")).isNull();
+        assertThat(ExtensionId.tryFrom("acme.geopoint")).isEmpty();
     }
 
     @Test

core/src/test/java/io/github/dfa1/vortex/extension/ExtensionTestSupport.java

@@ -34,7 +34,7 @@ static ByteBuffer unitByte(byte tag) {
         return meta;
     }
 
-    static ByteBuffer tzMeta(byte unitTag, String tz) {
+    static ByteBuffer tzMeta(byte unitTag, @org.jspecify.annotations.Nullable String tz) {
         byte[] tzBytes = tz == null ? new byte[0] : tz.getBytes(StandardCharsets.UTF_8);
         ByteBuffer meta = ByteBuffer.allocate(3 + tzBytes.length).order(ByteOrder.LITTLE_ENDIAN);
         meta.put(0, unitTag);

jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java

@@ -216,10 +216,8 @@ private static boolean fillCell(Object buffer, int rowIdx, ResultSet rs, int col
     @SuppressWarnings("unchecked")
     private static void fillExtensionCell(List<Object> buffer, ResultSet rs, int colIdx,
             DType.Extension ext) throws SQLException {
-        ExtensionId id = ExtensionId.tryFrom(ext.extensionId());
-        if (id == null) {
-            throw new UnsupportedOperationException("unsupported extension: " + ext.extensionId());
-        }
+        ExtensionId id = ExtensionId.tryFrom(ext.extensionId())
+                .orElseThrow(() -> new UnsupportedOperationException("unsupported extension: " + ext.extensionId()));
         // SQL NULL → null in the buffer. Nullable extension columns round-trip through the
         // writer's ExtEncoding → MaskedEncoding → primitive layout (validity child preserved);
         // NOT NULL columns reject any null element with VortexException during encode.

reader/src/main/java/io/github/dfa1/vortex/scan/Chunk.java

@@ -117,10 +117,8 @@ public <T> List<T> as(String name, Class<T> domainType) {
         if (!(colDtype instanceof DType.Extension ext)) {
             throw new VortexException("not an extension column: " + name);
         }
-        ExtensionId id = ExtensionId.tryFrom(ext.extensionId());
-        if (id == null) {
-            throw new VortexException("not a spec extension id: " + ext.extensionId());
-        }
+        ExtensionId id = ExtensionId.tryFrom(ext.extensionId())
+                .orElseThrow(() -> new VortexException("not a spec extension id: " + ext.extensionId()));
         Array storage = column(name);
         Object result = switch (id) {
             case VORTEX_DATE -> {

writer/src/main/java/io/github/dfa1/vortex/writer/VortexWriter.java

@@ -310,10 +310,10 @@ public void writeChunk(Map<String, Object> columns) throws IOException {
             // ExtEncoding wraps the storage child below — matches Rust's nested layout
             // (ExtEncoding → PrimitiveEncoding) and lets Registry skip its unwrap path.
             if (colDtype instanceof DType.Extension extDtype && data instanceof java.util.Collection<?> coll) {
-                io.github.dfa1.vortex.extension.ExtensionId extId =
-                        io.github.dfa1.vortex.extension.ExtensionId.tryFrom(extDtype.extensionId());
                 io.github.dfa1.vortex.extension.Extension impl =
-                        extId == null ? null : defaultRegistry.lookup(extId);
+                        io.github.dfa1.vortex.extension.ExtensionId.tryFrom(extDtype.extensionId())
+                                .map(defaultRegistry::lookup)
+                                .orElse(null);
                 if (impl != null) {
                     data = impl.encodeAll(extDtype, coll);
                 }