@malloydata/malloy 0.0.387 → 0.0.388

package/dist/api/foundation/config.d.ts

@@ -133,27 +133,42 @@ export declare class MalloyConfig {
      */
     wrapConnections(wrapper: (base: LookupConnection<Connection>) => LookupConnection<Connection>): void;
     /**
-     * Notify every connection this config has handed out that it is time to
-     * release its resources, then drop them from the internal cache.
+     * Notify every connection this config has handed out that the host is
+     * done with it, applying the requested disposition to its backend
+     * resources. Two policies:
      *
-     * Most callers should use `Runtime.releaseConnections()` instead — the
-     * expected contract is one MalloyConfig per Runtime, and the runtime is
-     * the natural handle for lifecycle. This method exists because Runtime
+     * - `'close'` (default) — destructive. Calls `Connection.close()` on each
+     *   cached entry and drops the cache. Subsequent operations on those
+     *   connection objects may fail. Use this at real shutdown: process
+     *   exit, extension deactivate, config-file change.
+     *
+     * - `'idle'` — reversible. Calls `Connection.idle()` on each cached entry
+     *   without dropping the cache. The same Connection objects are reused
+     *   on next lookup; schema cache and other in-process state survive.
+     *   The next operation transparently reattaches any backend resources
+     *   that were released. Use this between operations in long-lived hosts
+     *   (VSCode, MCP servers, anything that builds Runtimes per request) to
+     *   release file locks / pooled sockets while the host is otherwise
+     *   idle.
+     *
+     * Most callers should use `Runtime.shutdown(...)` instead — the expected
+     * contract is one MalloyConfig per Runtime, and the runtime is the
+     * natural handle for lifecycle. This method exists because Runtime
      * forwards to it, and for the rare case of a MalloyConfig constructed
      * without an accompanying Runtime.
      *
      * MalloyConfig does not own any connection resources itself — pools,
      * sockets, file handles, and in-process databases all live inside the
      * individual Connection objects. What the managed lookup owns is a cache
-     * of `name → Connection` populated lazily as callers request connections.
-     * This method walks that cache and calls `Connection.close()` on each
-     * entry, which is the signal each connection uses to shut down whatever
-     * resources it actually holds.
-     *
-     * Connections that were never looked up were never constructed and have
-     * nothing to release; they are skipped. Wrapping lookups installed via
-     * `wrapConnections()` do not interfere — the managed lookup under the
-     * wrap is the one holding the cache.
+     * of `name → Connection` populated lazily as callers request
+     * connections. Connections that were never looked up were never
+     * constructed and have nothing to release; they are skipped. Wrapping
+     * lookups installed via `wrapConnections()` do not interfere — the
+     * managed lookup under the wrap is the one holding the cache.
+     */
+    shutdown(connections?: 'close' | 'idle'): Promise<void>;
+    /**
+     * @deprecated Use `shutdown('close')` instead.
      */
     releaseConnections(): Promise<void>;
     /**

package/dist/api/foundation/config.js

@@ -216,30 +216,52 @@ class MalloyConfig {
         this._connections = wrapper(this._connections);
     }
     /**
-     * Notify every connection this config has handed out that it is time to
-     * release its resources, then drop them from the internal cache.
+     * Notify every connection this config has handed out that the host is
+     * done with it, applying the requested disposition to its backend
+     * resources. Two policies:
      *
-     * Most callers should use `Runtime.releaseConnections()` instead — the
-     * expected contract is one MalloyConfig per Runtime, and the runtime is
-     * the natural handle for lifecycle. This method exists because Runtime
+     * - `'close'` (default) — destructive. Calls `Connection.close()` on each
+     *   cached entry and drops the cache. Subsequent operations on those
+     *   connection objects may fail. Use this at real shutdown: process
+     *   exit, extension deactivate, config-file change.
+     *
+     * - `'idle'` — reversible. Calls `Connection.idle()` on each cached entry
+     *   without dropping the cache. The same Connection objects are reused
+     *   on next lookup; schema cache and other in-process state survive.
+     *   The next operation transparently reattaches any backend resources
+     *   that were released. Use this between operations in long-lived hosts
+     *   (VSCode, MCP servers, anything that builds Runtimes per request) to
+     *   release file locks / pooled sockets while the host is otherwise
+     *   idle.
+     *
+     * Most callers should use `Runtime.shutdown(...)` instead — the expected
+     * contract is one MalloyConfig per Runtime, and the runtime is the
+     * natural handle for lifecycle. This method exists because Runtime
      * forwards to it, and for the rare case of a MalloyConfig constructed
      * without an accompanying Runtime.
      *
      * MalloyConfig does not own any connection resources itself — pools,
      * sockets, file handles, and in-process databases all live inside the
      * individual Connection objects. What the managed lookup owns is a cache
-     * of `name → Connection` populated lazily as callers request connections.
-     * This method walks that cache and calls `Connection.close()` on each
-     * entry, which is the signal each connection uses to shut down whatever
-     * resources it actually holds.
-     *
-     * Connections that were never looked up were never constructed and have
-     * nothing to release; they are skipped. Wrapping lookups installed via
-     * `wrapConnections()` do not interfere — the managed lookup under the
-     * wrap is the one holding the cache.
+     * of `name → Connection` populated lazily as callers request
+     * connections. Connections that were never looked up were never
+     * constructed and have nothing to release; they are skipped. Wrapping
+     * lookups installed via `wrapConnections()` do not interfere — the
+     * managed lookup under the wrap is the one holding the cache.
+     */
+    async shutdown(connections = 'close') {
+        if (connections === 'idle') {
+            await this._managedLookup.idle();
+        }
+        else {
+            await this._managedLookup.close();
+        }
+    }
+    /**
+     * @deprecated Use `shutdown('close')` instead.
      */
     async releaseConnections() {
-        await this._managedLookup.close();
+        await this.shutdown('close');
     }
     /**
      * Query a value from the overlays used to resolve this config.

package/dist/api/foundation/config_lookup.js

@@ -83,6 +83,13 @@ function buildManagedLookup(compiledConnections, overlays, log) {
                 await conn.close();
             }
         },
+        async idle() {
+            // Cache is preserved — same Connection objects are reused so that
+            // schema cache and other in-process state survive the idle.
+            for (const conn of cache.values()) {
+                await conn.idle();
+            }
+        },
     };
 }
 /**
@@ -91,7 +98,14 @@ function buildManagedLookup(compiledConnections, overlays, log) {
  * gets handed to the factory.
  */
 async function resolveCompiledEntry(entry, overlays, log) {
-    const resolved = (await resolveNode(entry, overlays, log));
+    const resolved = await resolveNode(entry, overlays, log);
+    // resolveNode returns `unknown`. The compileConnections pipeline
+    // guarantees every connection entry is an object dict with `is` set to
+    // a literal string, so this should always pass — but a structured
+    // throw beats a downstream NPE if a compiler bug ever sneaks through.
+    if (!(0, registry_1.isConnectionConfigEntry)(resolved)) {
+        throw new Error('Connection entry did not resolve to a valid {is: string, ...} dict');
+    }
     await applyPropertyDefaults(resolved, overlays);
     return resolved;
 }

package/dist/api/foundation/runtime.d.ts

@@ -126,16 +126,27 @@ export declare class Runtime {
     get virtualMap(): VirtualMap | undefined;
     set virtualMap(map: VirtualMap | undefined);
     /**
-     * Notify every connection this runtime's config has handed out that it
-     * is time to release its resources (pools, sockets, file handles,
-     * in-process databases). A no-op for runtimes constructed without a
-     * MalloyConfig — in that case the caller owns the connections they
-     * passed in and is responsible for closing them.
-     *
-     * The expected contract is one MalloyConfig per Runtime. Long-running
-     * hosts (Publisher, a VS Code extension tearing down a project) should
-     * call this when a runtime goes out of scope; one-shot CLIs can skip it
-     * and let process exit clean up.
+     * Tell this runtime's connections what to do with their backend
+     * resources now that the host is done with this Runtime. Two policies:
+     *
+     * - `'close'` (default) — destructive shutdown. Connections release
+     *   resources and become unusable. Use at real shutdown: process exit,
+     *   extension deactivate, config-file change.
+     *
+     * - `'idle'` — reversible release. Connections release expensive
+     *   resources (DuckDB file locks, socket pools) but stay logically
+     *   valid. The same Connection objects are reused on next lookup;
+     *   schema cache and other in-process state survive. Use between
+     *   operations in long-lived hosts (a VSCode extension, an MCP server,
+     *   any host that builds Runtimes per request) so that other writers
+     *   can claim resources during idle gaps.
+     *
+     * A no-op for runtimes constructed without a MalloyConfig — in that
+     * case the caller owns the connections they passed in.
+     */
+    shutdown(connections?: 'close' | 'idle'): Promise<void>;
+    /**
+     * @deprecated Use `shutdown('close')` instead.
      */
     releaseConnections(): Promise<void>;
     /**

package/dist/api/foundation/runtime.js

@@ -160,7 +160,11 @@ class Runtime {
                     return undefined;
                 }
                 try {
-                    return JSON.parse(text);
+                    const parsed = JSON.parse(text);
+                    if (!isBuildManifestShape(parsed)) {
+                        throw new Error('manifest is not an object with an "entries" map');
+                    }
+                    return parsed;
                 }
                 catch (e) {
                     // File was present but couldn't be parsed. Return an empty
@@ -193,20 +197,33 @@ class Runtime {
         this._virtualMap = map;
     }
     /**
-     * Notify every connection this runtime's config has handed out that it
-     * is time to release its resources (pools, sockets, file handles,
-     * in-process databases). A no-op for runtimes constructed without a
-     * MalloyConfig — in that case the caller owns the connections they
-     * passed in and is responsible for closing them.
+     * Tell this runtime's connections what to do with their backend
+     * resources now that the host is done with this Runtime. Two policies:
+     *
+     * - `'close'` (default) — destructive shutdown. Connections release
+     *   resources and become unusable. Use at real shutdown: process exit,
+     *   extension deactivate, config-file change.
+     *
+     * - `'idle'` — reversible release. Connections release expensive
+     *   resources (DuckDB file locks, socket pools) but stay logically
+     *   valid. The same Connection objects are reused on next lookup;
+     *   schema cache and other in-process state survive. Use between
+     *   operations in long-lived hosts (a VSCode extension, an MCP server,
+     *   any host that builds Runtimes per request) so that other writers
+     *   can claim resources during idle gaps.
      *
-     * The expected contract is one MalloyConfig per Runtime. Long-running
-     * hosts (Publisher, a VS Code extension tearing down a project) should
-     * call this when a runtime goes out of scope; one-shot CLIs can skip it
-     * and let process exit clean up.
+     * A no-op for runtimes constructed without a MalloyConfig — in that
+     * case the caller owns the connections they passed in.
      */
-    async releaseConnections() {
+    async shutdown(connections = 'close') {
         var _a;
-        await ((_a = this._config) === null || _a === void 0 ? void 0 : _a.releaseConnections());
+        await ((_a = this._config) === null || _a === void 0 ? void 0 : _a.shutdown(connections));
+    }
+    /**
+     * @deprecated Use `shutdown('close')` instead.
+     */
+    async releaseConnections() {
+        await this.shutdown('close');
     }
     /**
      * Load a Malloy model by URL or contents.
@@ -532,7 +549,7 @@ class ModelMaterializer extends FluentState {
         const result = await this.loadQuery(searchMapMalloy, options).run({
             rowLimit: 1000,
         });
-        const rawResult = result._queryResult.result;
+        const rawResult = result.data.toObject();
         return rawResult.map(row => ({
             ...row,
             cardinality: (0, row_data_utils_1.rowDataToNumber)(row.cardinality),
@@ -870,4 +887,18 @@ class ExploreMaterializer extends FluentState {
     }
 }
 exports.ExploreMaterializer = ExploreMaterializer;
+/**
+ * Structural check for the `BuildManifest` shape: a non-null object with an
+ * object `entries` field. Doesn't validate every entry — `BuildManifestEntry`
+ * is just `{tableName: string}`, so a stricter walk could come later if we
+ * find malformed entries causing trouble. The current goal is to fail
+ * cleanly on a manifest file that parsed to a string/array/null instead of
+ * leaving a downstream `entries[buildId]` lookup to crash on `undefined`.
+ */
+function isBuildManifestShape(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const entries = value.entries;
+    return typeof entries === 'object' && entries !== null;
+}
 //# sourceMappingURL=runtime.js.map

package/dist/connection/base_connection.d.ts

@@ -40,6 +40,7 @@ export declare abstract class BaseConnection implements Connection {
     canPersist(): this is PersistSQLResults;
     canStream(): this is StreamingConnection;
     close(): Promise<void>;
+    idle(): Promise<void>;
     estimateQueryCost(_sqlCommand: string): Promise<QueryRunStats>;
     fetchMetadata(): Promise<{}>;
     fetchTableMetadata(_tablePath: string): Promise<{}>;

package/dist/connection/base_connection.js

@@ -78,6 +78,7 @@ class BaseConnection {
         return false;
     }
     async close() { }
+    async idle() { }
     async estimateQueryCost(_sqlCommand) {
         return {};
     }

package/dist/connection/registry.d.ts

@@ -122,11 +122,14 @@ export declare function readConnectionsConfig(jsonText: string): ConnectionsConf
 export declare function writeConnectionsConfig(config: ConnectionsConfig): string;
 /**
  * A LookupConnection with lifecycle management: close() shuts down all
- * cached connections, and an optional onConnectionCreated callback fires
- * once per connection after factory creation (before caching).
+ * cached connections, idle() releases their backend resources but keeps
+ * the cache so the same connection objects are reused on next lookup, and
+ * an optional onConnectionCreated callback fires once per connection after
+ * factory creation (before caching).
  */
 export interface ManagedConnectionLookup extends LookupConnection<Connection> {
     close(): Promise<void>;
+    idle(): Promise<void>;
 }
 /**
  * Create a ManagedConnectionLookup from a ConnectionsConfig using registered

package/dist/connection/registry.js

@@ -159,6 +159,13 @@ function createConnectionsFromConfig(config, onConnectionCreated) {
                 await conn.close();
             }
         },
+        async idle() {
+            // Cache is preserved — the same Connection objects are reused so that
+            // schema cache and other in-process state survive the idle.
+            for (const conn of cache.values()) {
+                await conn.idle();
+            }
+        },
     };
 }
 //# sourceMappingURL=registry.js.map

package/dist/connection/types.d.ts

@@ -77,6 +77,20 @@ export interface Connection extends InfoConnection {
     canPersist(): this is PersistSQLResults;
     canStream(): this is StreamingConnection;
     close(): Promise<void>;
+    /**
+     * Release expensive backend resources (file locks, sockets, sub-processes,
+     * pooled connections) but remain logically valid. The next operation
+     * transparently reattaches whatever was released; schema cache and other
+     * in-process state survive.
+     *
+     * The default is a no-op for backends that hold no release-able resources
+     * between operations. Backends that hold OS-level resources (DuckDB file
+     * locks, persistent socket pools) should override.
+     *
+     * Hosts that share a connection across concurrent operations should not
+     * call `idle()` while an operation is in flight.
+     */
+    idle(): Promise<void>;
     estimateQueryCost(sqlCommand: string): Promise<QueryRunStats>;
     fetchMetadata: () => Promise<ConnectionMetadata>;
     fetchTableMetadata: (tablePath: string) => Promise<TableMetadata>;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const MALLOY_VERSION = "0.0.387";
+export declare const MALLOY_VERSION = "0.0.388";

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MALLOY_VERSION = void 0;
 // generated with 'generate-version-file' script; do not edit manually
-exports.MALLOY_VERSION = '0.0.387';
+exports.MALLOY_VERSION = '0.0.388';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/malloy",
-  "version": "0.0.387",
+  "version": "0.0.388",
   "license": "MIT",
   "exports": {
     ".": "./dist/index.js",
@@ -51,9 +51,9 @@
     "generate-version-file": "VERSION=$(npm pkg get version --workspaces=false | tr -d \\\")\necho \"// generated with 'generate-version-file' script; do not edit manually\\nexport const MALLOY_VERSION = '$VERSION';\" > src/version.ts"
   },
   "dependencies": {
-    "@malloydata/malloy-filter": "0.0.387",
-    "@malloydata/malloy-interfaces": "0.0.387",
-    "@malloydata/malloy-tag": "0.0.387",
+    "@malloydata/malloy-filter": "0.0.388",
+    "@malloydata/malloy-interfaces": "0.0.388",
+    "@malloydata/malloy-tag": "0.0.388",
     "@noble/hashes": "^1.8.0",
     "antlr4ts": "^0.5.0-alpha.4",
     "assert": "^2.0.0",