@gobing-ai/ts-runtime 0.3.17 → 0.3.19

package/README.md

@@ -17,6 +17,7 @@ and Cloudflare Workers through a factory pattern that auto-detects the runtime.
 | Runtime factory | `RuntimeFactory` → `loadRuntimeFactory()` | `nodeBunFactory` | `cloudflareWorkersFactory` |
 | File system | `FileSystem` | `createNodeFileSystem()` (sync `node:fs`) | `createCfFileSystem()` (stub) |
 | Process execution | `ProcessExecutor` (class) | `run()` via execa, `runStreaming()` via `Bun.spawn` | throws |
+| SQL database | `createDbAdapter(config)` → `DbAdapter` | Bun SQLite via `@gobing-ai/ts-db` | throws `D1NotConfiguredError` (D1 round pending) |
 | Configuration | `Config` (Zod schema) | YAML + env vars | CONFIG_YAML blob + env vars |
 | Context | `RuntimeContext` | service locator | service locator |
 | Path utilities | `SEP`, `basenamePath`, `dirnamePath`, `joinPath`, `resolvePath`, `relativePath`, … | runtime-portable (zero `node:*`) | runtime-portable (zero `node:*`) |
@@ -31,24 +32,24 @@ classDiagram
     class RuntimeFactory {
         <<interface>>
         +string runtimeName
-        +RuntimeCapabilities capabilities
         +createFileSystem() FileSystem
         +createProcessExecutor() ProcessExecutor
         +loadConfig() Promise~Config~
+        +createDbAdapter(config) Promise~DbAdapter~
     }
 
     class nodeBunFactory {
-        +string runtimeName
         +createFileSystem() createNodeFileSystem()
         +createProcessExecutor() ProcessExecutor
         +loadConfig() Promise~Config~
+        +createDbAdapter() Promise~DbAdapter~
     }
 
     class cloudflareWorkersFactory {
-        +string runtimeName
         +createFileSystem() createCfFileSystem()
         +createProcessExecutor() never
         +loadConfig() Promise~Config~
+        +createDbAdapter() never
     }
 
     class FileSystem {
@@ -368,7 +369,36 @@ cffs.readFile('/x');     // throws: "use D1, KV, or R2"
 The old `getFs()` / `setFileSystem` global swap and `SyncFileSystem` are marked `@deprecated` —
 use `createNodeFileSystem()` or `ctx.require('fileSystem')` instead.
 
-### 8. Graceful disposal
+### 8. Database adapter (`createDbAdapter`)
+
+The factory's `createDbAdapter(config)` opens a connected adapter satisfying the `RuntimeDbAdapter` contract
+(the runtime-facing subset of `@gobing-ai/ts-db`'s `DbAdapter`) at the configured path. **ts-runtime owns
+connection; the consumer owns schema** — the returned adapter is connected but NOT migrated. The consumer
+composes its own migrations on top.
+
+```ts
+import { loadRuntimeFactory } from '@gobing-ai/ts-runtime';
+
+const factory = await loadRuntimeFactory();
+
+if (factory.capabilities.hasSqlDatabase) {
+    const adapter = await factory.createDbAdapter({ url: '.spur/spur.db' });
+    // adapter is connected — apply YOUR migrations here, then use DAOs.
+    adapter.close();
+}
+```
+
+On Cloudflare Workers, `capabilities.hasSqlDatabase` is `false` and `createDbAdapter` throws a typed
+`D1NotConfiguredError` — the method exists on the interface so consumer code is forward-compatible and
+needs no change when the D1 round ships.
+
+**Dependency note:** `@gobing-ai/ts-db` is not a static dependency of `ts-runtime` (it would create a
+cycle, since `ts-db` depends on `ts-runtime`). The factory interface uses a structural
+`RuntimeDbAdapter` type (defined locally) that a ts-db `DbAdapter` satisfies via structural subtyping;
+`nodeBunFactory.createDbAdapter` loads `ts-db` via a dynamic `import()` at runtime. Consumers that call
+`createDbAdapter` must have `@gobing-ai/ts-db` in their dependency graph.
+
+### 9. Graceful disposal
 
 `RuntimeContext.dispose()` calls `dispose()` on every registered service that implements the pattern:
 

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,KAAK,EAAE,eAAe,IAAI,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEpF,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAChE,4FAA4F;AAC5F,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAErF,8GAA8G;AAC9G,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED,yDAAyD;AACzD,MAAM,WAAW,qBAAqB,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB;IAC1F,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CACjC;AAED,uGAAuG;AACvG,qBAAa,cAAc,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB;IAC/E,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,mDAA0D;gBAE/D,OAAO,GAAE,qBAAqB,CAAC,SAAS,CAAM;IA2B1D,QAAQ,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAKxE,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;IAIhE,OAAO,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAQxD,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO;IAIzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAejC;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,+BAA+B,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB,EACzG,OAAO,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,GAC3C,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAiBpC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB,EACxF,OAAO,GAAE,qBAAqB,CAAC,SAAS,CAAM,GAC/C,cAAc,CAAC,SAAS,CAAC,CAE3B"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,KAAK,EAAE,eAAe,IAAI,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEpF,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAChE,4FAA4F;AAC5F,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAErF,8GAA8G;AAC9G,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,eAAe,CAAC,EAAE,sBAAsB,CAAC;IACzC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED,yDAAyD;AACzD,MAAM,WAAW,qBAAqB,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB;IAC1F,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CACjC;AAED,uGAAuG;AACvG,qBAAa,cAAc,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB;IAC/E,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,mDAA0D;gBAE/D,OAAO,GAAE,qBAAqB,CAAC,SAAS,CAAM;IA4B1D,QAAQ,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI;IAKxE,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;IAIhE,OAAO,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAQxD,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO;IAIzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAejC;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,+BAA+B,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB,EACzG,OAAO,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,GAC3C,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAiBpC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,SAAS,iBAAiB,GAAG,iBAAiB,EACxF,OAAO,GAAE,qBAAqB,CAAC,SAAS,CAAM,GAC/C,cAAc,CAAC,SAAS,CAAC,CAE3B"}

package/dist/context.js

@@ -17,6 +17,7 @@ export class RuntimeContext {
                     hasFilesystem: true,
                     hasProcessExecution: true,
                     hasPersistentStorage: true,
+                    hasSqlDatabase: true,
                 };
         this.register('config', (options.services?.config ?? buildConfigFromObject({})));
         this.register('fileSystem', (options.services?.fileSystem ?? createNodeFileSystem()));

package/dist/db-errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Thrown by {@link RuntimeFactory.createDbAdapter} on runtimes that cannot yet
+ * provide a SQL database adapter.
+ *
+ * Today only the Cloudflare Workers factory throws this: the D1 `DbAdapter`
+ * lives in a future `@gobing-ai/ts-db` round. The method exists on the
+ * interface so consumer app code is forward-compatible — it calls
+ * `createDbAdapter` uniformly and the Worker path surfaces this clear typed
+ * failure instead of a silent `undefined`.
+ */
+export declare class D1NotConfiguredError extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=db-errors.d.ts.map

package/dist/db-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-errors.d.ts","sourceRoot":"","sources":["../src/db-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBAC/B,OAAO,SAAiE;CAIvF"}

package/dist/db-errors.js

@@ -0,0 +1,16 @@
+/**
+ * Thrown by {@link RuntimeFactory.createDbAdapter} on runtimes that cannot yet
+ * provide a SQL database adapter.
+ *
+ * Today only the Cloudflare Workers factory throws this: the D1 `DbAdapter`
+ * lives in a future `@gobing-ai/ts-db` round. The method exists on the
+ * interface so consumer app code is forward-compatible — it calls
+ * `createDbAdapter` uniformly and the Worker path surfaces this clear typed
+ * failure instead of a silent `undefined`.
+ */
+export class D1NotConfiguredError extends Error {
+    constructor(message = 'D1 DbAdapter is not yet implemented; see the ts-db D1 round.') {
+        super(message);
+        this.name = 'D1NotConfiguredError';
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './config';
 export * from './context';
 export { createRuntimeContextFromFactory } from './context';
+export { D1NotConfiguredError } from './db-errors';
 export type { FileStat, FileSystem } from './file-system';
 export { createCfFileSystem } from './file-system-cf';
 export { createNodeFileSystem, findProjectRoot } from './file-system-node';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,UAAU,IAAI,gBAAgB,EACnC,KAAK,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,KAAK,cAAc,EACnB,aAAa,EACb,OAAO,EACP,aAAa,GAChB,MAAM,MAAM,CAAC;AACd,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjG,YAAY,EACR,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1E,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAExG;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;AAE3G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EACH,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,UAAU,IAAI,gBAAgB,EACnC,KAAK,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,KAAK,cAAc,EACnB,aAAa,EACb,OAAO,EACP,aAAa,GAChB,MAAM,MAAM,CAAC;AACd,cAAc,QAAQ,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACjG,YAAY,EACR,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC1E,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AAIxB,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAExG;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;AAE3G;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,cAAc,oBAAoB,EAAE,qBAAqB,CAAC,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './config.js';
 export * from './context.js';
 export { createRuntimeContextFromFactory } from './context.js';
+export { D1NotConfiguredError } from './db-errors.js';
 export { createCfFileSystem } from './file-system-cf.js';
 export { createNodeFileSystem, findProjectRoot } from './file-system-node.js';
 export { atomicWriteFile, atomicWriteJson, CloudflareFileSystem, createLogStream, ensureDirForFile, ensureDirForFileSync, getFs, getProjectRoot, NodeFileSystem, NodeSyncFileSystem, readJsonFile, resolveProjectPath, setFileSystem, walkDir, writeJsonFile, } from './fs.js';

package/dist/runtime-cf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-cf.d.ts","sourceRoot":"","sources":["../src/runtime-cf.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,cA6BtC,CAAC"}
+{"version":3,"file":"runtime-cf.d.ts","sourceRoot":"","sources":["../src/runtime-cf.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,cAoCtC,CAAC"}

package/dist/runtime-cf.js

@@ -1,5 +1,6 @@
 import { parse as parseYaml } from 'yaml';
 import { buildConfigFromObject } from './config.js';
+import { D1NotConfiguredError } from './db-errors.js';
 import { createCfFileSystem } from './file-system-cf.js';
 /** Binding name for the YAML config text blob set in wrangler.toml. */
 const CONFIG_YAML_BINDING = 'CONFIG_YAML';
@@ -12,11 +13,18 @@ export const cloudflareWorkersFactory = {
         hasFilesystem: false,
         hasProcessExecution: false,
         hasPersistentStorage: false,
+        hasSqlDatabase: false,
     },
     createFileSystem: () => createCfFileSystem(),
     createProcessExecutor: (_config) => {
         throw new Error('ProcessExecutor is not available on Cloudflare Workers.');
     },
+    createDbAdapter(_config) {
+        // The D1 DbAdapter ships in a future ts-db round. The method exists on
+        // the interface so consumer code is forward-compatible and needs no
+        // change when D1 lands. Until then, surface a clear typed failure.
+        return Promise.reject(new D1NotConfiguredError());
+    },
     async loadConfig(options) {
         const yamlString = options?.envBindings?.[CONFIG_YAML_BINDING];
         let raw = {};

package/dist/runtime-factory.d.ts

@@ -1,7 +1,7 @@
 import type { Config } from './config';
 import type { FileSystem } from './file-system';
 import type { ProcessExecutor, ProcessExecutorConfig } from './process-executor';
-import type { LoadConfigOptions, RuntimeCapabilities, RuntimeName } from './types';
+import type { DatabaseConfig, LoadConfigOptions, RuntimeCapabilities, RuntimeDbAdapter, RuntimeName } from './types';
 /**
  * Abstract factory for creating runtime-aware infrastructure.
  *
@@ -20,5 +20,16 @@ export interface RuntimeFactory {
     createProcessExecutor(config?: ProcessExecutorConfig): ProcessExecutor;
     /** Load config from the runtime's config backend. */
     loadConfig(options?: LoadConfigOptions): Promise<Config>;
+    /**
+     * Create a runtime-specific database adapter.
+     *
+     * ts-runtime owns *connection* (opens the adapter at `config.url`); the
+     * consumer owns *schema* (migrations). The returned adapter is connected
+     * but NOT migrated.
+     *
+     * On runtimes without a SQL database (`capabilities.hasSqlDatabase === false`)
+     * this throws {@link D1NotConfiguredError}.
+     */
+    createDbAdapter(config: DatabaseConfig): Promise<RuntimeDbAdapter>;
 }
 //# sourceMappingURL=runtime-factory.d.ts.map

package/dist/runtime-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-factory.d.ts","sourceRoot":"","sources":["../src/runtime-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEnF;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAElC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAE3C,yFAAyF;IACzF,gBAAgB,IAAI,UAAU,CAAC;IAE/B,oGAAoG;IACpG,qBAAqB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,eAAe,CAAC;IAEvE,qDAAqD;IACrD,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5D"}
+{"version":3,"file":"runtime-factory.d.ts","sourceRoot":"","sources":["../src/runtime-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAErH;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAElC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAE3C,yFAAyF;IACzF,gBAAgB,IAAI,UAAU,CAAC;IAE/B,oGAAoG;IACpG,qBAAqB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,eAAe,CAAC;IAEvE,qDAAqD;IACrD,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzD;;;;;;;;;OASG;IACH,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtE"}

package/dist/runtime-node-bun.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-node-bun.d.ts","sourceRoot":"","sources":["../src/runtime-node-bun.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUxD,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAgB5B,CAAC"}
+{"version":3,"file":"runtime-node-bun.d.ts","sourceRoot":"","sources":["../src/runtime-node-bun.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUxD,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cA8B5B,CAAC"}

package/dist/runtime-node-bun.js

@@ -22,12 +22,24 @@ export const nodeBunFactory = {
         hasFilesystem: true,
         hasProcessExecution: true,
         hasPersistentStorage: true,
+        hasSqlDatabase: true,
     },
     createFileSystem: () => getNodeFileSystem(),
     createProcessExecutor: (config) => new ProcessExecutor(config),
     async loadConfig(options) {
         return loadNodeConfig(options);
     },
+    async createDbAdapter(config) {
+        // Dynamic import via a variable specifier keeps ts-db out of the
+        // static dependency graph (it depends on ts-runtime, so a static dep
+        // would cycle). The variable prevents tsc from type-resolving the
+        // module at build time (ts-db builds after ts-runtime); at runtime
+        // Bun resolves it via the workspace + tsconfig paths. Connection only
+        // — the caller owns schema/migrations.
+        const moduleSpecifier = '@gobing-ai/ts-db';
+        const mod = (await import(moduleSpecifier));
+        return mod.createDbAdapter({ driver: 'bun-sqlite', url: config.url });
+    },
 };
 // ── Config loading (Node/Bun) ────────────────────────────────────────────
 /**

package/dist/types.d.ts

@@ -1,11 +1,63 @@
 import type { Config } from './config';
 /** Identifier for the target runtime platform. */
 export type RuntimeName = 'node-bun' | 'cloudflare-workers' | 'test';
-/** Feature flags describing what a runtime platform supports (filesystem, process execution, persistent storage). */
+/**
+ * Feature flags describing what a runtime platform supports (filesystem, process
+ * execution, persistent storage, SQL database).
+ */
 export interface RuntimeCapabilities {
     readonly hasFilesystem: boolean;
     readonly hasProcessExecution: boolean;
     readonly hasPersistentStorage: boolean;
+    /**
+     * Whether the runtime can provide a connected {@link DbAdapter}.
+     *
+     * `true` on Node/Bun (Bun SQLite); `false` on Cloudflare Workers until the
+     * D1 round ships — the CF factory's `createDbAdapter` throws a typed
+     * {@link D1NotConfiguredError} so consumer code is forward-compatible.
+     */
+    readonly hasSqlDatabase: boolean;
+}
+/**
+ * Configuration for {@link RuntimeFactory.createDbAdapter}.
+ *
+ * Focused on the DB facility so it does not bloat the general runtime {@link Config}.
+ * The Bun path reads `url` (a filesystem path or `":memory:"`); the Cloudflare path
+ * would read `d1Binding` (scoped to a later ts-db round).
+ */
+export interface DatabaseConfig {
+    /** SQLite database path or `":memory:"`. Bun path only. */
+    url: string;
+    /** Optional driver hint. Reserved for future drivers. */
+    driver?: string;
+    /** Name of the D1 binding in wrangler.toml. CF path (future D1 round). */
+    d1Binding?: string;
+}
+/**
+ * Structural database adapter contract — the runtime-facing subset of
+ * `@gobing-ai/ts-db`'s `DbAdapter`.
+ *
+ * ts-runtime cannot import the `DbAdapter` type from ts-db at build time
+ * (ts-db depends on ts-runtime, so the build order is runtime → db). This
+ * structural type captures the public method surface; a ts-db `DbAdapter` is
+ * assignable to it because it implements every method (plus the `@internal db`
+ * property, which is extra and harmless under structural subtyping).
+ *
+ * The full `DbAdapter` type is re-exported from the package index via
+ * `import type` for consumer convenience; this structural type is the
+ * build-time contract used inside the factory.
+ */
+export interface RuntimeDbAdapter {
+    /** Run a raw SQL statement with no parameters (DDL). */
+    exec(sql: string): Promise<void>;
+    /** Parameterized write (INSERT/UPDATE/DELETE) that returns no rows. */
+    run(sql: string, ...params: unknown[]): Promise<void>;
+    /** Parameterized read returning the first row, or undefined. */
+    queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
+    /** Parameterized read returning all rows. */
+    queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    /** Close the underlying connection. */
+    close(): void;
 }
 /** Options passed to config loading functions, including overrides and environment variable bindings. */
 export interface LoadConfigOptions {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,oBAAoB,GAAG,MAAM,CAAC;AAErE,qHAAqH;AACrH,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CAC1C;AAED,yGAAyG;AACzG,MAAM,WAAW,iBAAiB;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CAC1D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,oBAAoB,GAAG,MAAM,CAAC;AAErE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC3B,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC7B,wDAAwD;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,gEAAgE;IAChE,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACzE,6CAA6C;IAC7C,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7D,uCAAuC;IACvC,KAAK,IAAI,IAAI,CAAC;CACjB;AAED,yGAAyG;AACzG,MAAM,WAAW,iBAAiB;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CAC1D"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-runtime",
-    "version": "0.3.17",
+    "version": "0.3.19",
     "description": "@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.",
     "keywords": [
         "typescript",
@@ -58,12 +58,13 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-runtime-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-utils": "^0.3.17",
+        "@gobing-ai/ts-utils": "^0.3.19",
         "execa": "^9.5.0",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },
     "devDependencies": {
+        "@gobing-ai/ts-db": "^0.3.19",
         "@types/bun": "1.3.14"
     },
     "publishConfig": {

package/src/context.ts

@@ -41,6 +41,7 @@ export class RuntimeContext<TServices extends RuntimeServiceMap = RuntimeService
                 hasFilesystem: true,
                 hasProcessExecution: true,
                 hasPersistentStorage: true,
+                hasSqlDatabase: true,
             } satisfies RuntimeCapabilities);
 
         this.register('config', (options.services?.config ?? buildConfigFromObject({})) as TServices['config']);

package/src/db-errors.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown by {@link RuntimeFactory.createDbAdapter} on runtimes that cannot yet
+ * provide a SQL database adapter.
+ *
+ * Today only the Cloudflare Workers factory throws this: the D1 `DbAdapter`
+ * lives in a future `@gobing-ai/ts-db` round. The method exists on the
+ * interface so consumer app code is forward-compatible — it calls
+ * `createDbAdapter` uniformly and the Worker path surfaces this clear typed
+ * failure instead of a silent `undefined`.
+ */
+export class D1NotConfiguredError extends Error {
+    constructor(message = 'D1 DbAdapter is not yet implemented; see the ts-db D1 round.') {
+        super(message);
+        this.name = 'D1NotConfiguredError';
+    }
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './config';
 export * from './context';
 export { createRuntimeContextFromFactory } from './context';
+export { D1NotConfiguredError } from './db-errors';
 export type { FileStat, FileSystem } from './file-system';
 export { createCfFileSystem } from './file-system-cf';
 export { createNodeFileSystem, findProjectRoot } from './file-system-node';

package/src/runtime-cf.ts

@@ -1,10 +1,11 @@
 import { parse as parseYaml } from 'yaml';
 import type { Config } from './config';
 import { buildConfigFromObject } from './config';
+import { D1NotConfiguredError } from './db-errors';
 import { createCfFileSystem } from './file-system-cf';
 import type { ProcessExecutorConfig } from './process-executor';
 import type { RuntimeFactory } from './runtime-factory';
-import type { LoadConfigOptions } from './types';
+import type { DatabaseConfig, LoadConfigOptions, RuntimeDbAdapter } from './types';
 
 /** Binding name for the YAML config text blob set in wrangler.toml. */
 const CONFIG_YAML_BINDING = 'CONFIG_YAML';
@@ -14,11 +15,11 @@ const CONFIG_YAML_BINDING = 'CONFIG_YAML';
  */
 export const cloudflareWorkersFactory: RuntimeFactory = {
     runtimeName: 'cloudflare-workers',
-
     capabilities: {
         hasFilesystem: false,
         hasProcessExecution: false,
         hasPersistentStorage: false,
+        hasSqlDatabase: false,
     },
 
     createFileSystem: () => createCfFileSystem(),
@@ -27,6 +28,13 @@ export const cloudflareWorkersFactory: RuntimeFactory = {
         throw new Error('ProcessExecutor is not available on Cloudflare Workers.');
     },
 
+    createDbAdapter(_config: DatabaseConfig): Promise<RuntimeDbAdapter> {
+        // The D1 DbAdapter ships in a future ts-db round. The method exists on
+        // the interface so consumer code is forward-compatible and needs no
+        // change when D1 lands. Until then, surface a clear typed failure.
+        return Promise.reject(new D1NotConfiguredError());
+    },
+
     async loadConfig(options?: LoadConfigOptions): Promise<Config> {
         const yamlString = options?.envBindings?.[CONFIG_YAML_BINDING] as string | undefined;
         let raw: Record<string, unknown> = {};

package/src/runtime-factory.ts

@@ -1,7 +1,7 @@
 import type { Config } from './config';
 import type { FileSystem } from './file-system';
 import type { ProcessExecutor, ProcessExecutorConfig } from './process-executor';
-import type { LoadConfigOptions, RuntimeCapabilities, RuntimeName } from './types';
+import type { DatabaseConfig, LoadConfigOptions, RuntimeCapabilities, RuntimeDbAdapter, RuntimeName } from './types';
 
 /**
  * Abstract factory for creating runtime-aware infrastructure.
@@ -25,4 +25,16 @@ export interface RuntimeFactory {
 
     /** Load config from the runtime's config backend. */
     loadConfig(options?: LoadConfigOptions): Promise<Config>;
+
+    /**
+     * Create a runtime-specific database adapter.
+     *
+     * ts-runtime owns *connection* (opens the adapter at `config.url`); the
+     * consumer owns *schema* (migrations). The returned adapter is connected
+     * but NOT migrated.
+     *
+     * On runtimes without a SQL database (`capabilities.hasSqlDatabase === false`)
+     * this throws {@link D1NotConfiguredError}.
+     */
+    createDbAdapter(config: DatabaseConfig): Promise<RuntimeDbAdapter>;
 }

package/src/runtime-node-bun.ts

@@ -5,7 +5,7 @@ import type { FileSystem } from './file-system';
 import { createNodeFileSystem } from './file-system-node';
 import { ProcessExecutor, type ProcessExecutorConfig } from './process-executor';
 import type { RuntimeFactory } from './runtime-factory';
-import type { LoadConfigOptions } from './types';
+import type { DatabaseConfig, LoadConfigOptions, RuntimeDbAdapter } from './types';
 
 // Lazy re-initialisable singleton for test isolation.
 let _nodeFileSystem: FileSystem | undefined;
@@ -24,11 +24,11 @@ export function _resetNodeFileSystem(): void {
  */
 export const nodeBunFactory: RuntimeFactory = {
     runtimeName: 'node-bun',
-
     capabilities: {
         hasFilesystem: true,
         hasProcessExecution: true,
         hasPersistentStorage: true,
+        hasSqlDatabase: true,
     },
 
     createFileSystem: () => getNodeFileSystem(),
@@ -38,6 +38,20 @@ export const nodeBunFactory: RuntimeFactory = {
     async loadConfig(options?: LoadConfigOptions): Promise<Config> {
         return loadNodeConfig(options);
     },
+
+    async createDbAdapter(config: DatabaseConfig): Promise<RuntimeDbAdapter> {
+        // Dynamic import via a variable specifier keeps ts-db out of the
+        // static dependency graph (it depends on ts-runtime, so a static dep
+        // would cycle). The variable prevents tsc from type-resolving the
+        // module at build time (ts-db builds after ts-runtime); at runtime
+        // Bun resolves it via the workspace + tsconfig paths. Connection only
+        // — the caller owns schema/migrations.
+        const moduleSpecifier = '@gobing-ai/ts-db';
+        const mod = (await import(moduleSpecifier)) as {
+            createDbAdapter: (config: { driver: 'bun-sqlite'; url?: string }) => RuntimeDbAdapter;
+        };
+        return mod.createDbAdapter({ driver: 'bun-sqlite', url: config.url });
+    },
 };
 
 // ── Config loading (Node/Bun) ────────────────────────────────────────────

package/src/types.ts

@@ -3,11 +3,65 @@ import type { Config } from './config';
 /** Identifier for the target runtime platform. */
 export type RuntimeName = 'node-bun' | 'cloudflare-workers' | 'test';
 
-/** Feature flags describing what a runtime platform supports (filesystem, process execution, persistent storage). */
+/**
+ * Feature flags describing what a runtime platform supports (filesystem, process
+ * execution, persistent storage, SQL database).
+ */
 export interface RuntimeCapabilities {
     readonly hasFilesystem: boolean;
     readonly hasProcessExecution: boolean;
     readonly hasPersistentStorage: boolean;
+    /**
+     * Whether the runtime can provide a connected {@link DbAdapter}.
+     *
+     * `true` on Node/Bun (Bun SQLite); `false` on Cloudflare Workers until the
+     * D1 round ships — the CF factory's `createDbAdapter` throws a typed
+     * {@link D1NotConfiguredError} so consumer code is forward-compatible.
+     */
+    readonly hasSqlDatabase: boolean;
+}
+
+/**
+ * Configuration for {@link RuntimeFactory.createDbAdapter}.
+ *
+ * Focused on the DB facility so it does not bloat the general runtime {@link Config}.
+ * The Bun path reads `url` (a filesystem path or `":memory:"`); the Cloudflare path
+ * would read `d1Binding` (scoped to a later ts-db round).
+ */
+export interface DatabaseConfig {
+    /** SQLite database path or `":memory:"`. Bun path only. */
+    url: string;
+    /** Optional driver hint. Reserved for future drivers. */
+    driver?: string;
+    /** Name of the D1 binding in wrangler.toml. CF path (future D1 round). */
+    d1Binding?: string;
+}
+
+/**
+ * Structural database adapter contract — the runtime-facing subset of
+ * `@gobing-ai/ts-db`'s `DbAdapter`.
+ *
+ * ts-runtime cannot import the `DbAdapter` type from ts-db at build time
+ * (ts-db depends on ts-runtime, so the build order is runtime → db). This
+ * structural type captures the public method surface; a ts-db `DbAdapter` is
+ * assignable to it because it implements every method (plus the `@internal db`
+ * property, which is extra and harmless under structural subtyping).
+ *
+ * The full `DbAdapter` type is re-exported from the package index via
+ * `import type` for consumer convenience; this structural type is the
+ * build-time contract used inside the factory.
+ */
+export interface RuntimeDbAdapter {
+    /** Run a raw SQL statement with no parameters (DDL). */
+    exec(sql: string): Promise<void>;
+    /** Parameterized write (INSERT/UPDATE/DELETE) that returns no rows. */
+    run(sql: string, ...params: unknown[]): Promise<void>;
+    /** Parameterized read returning the first row, or undefined. */
+    queryFirst<T>(sql: string, ...params: unknown[]): Promise<T | undefined>;
+    /** Parameterized read returning all rows. */
+    queryAll<T>(sql: string, ...params: unknown[]): Promise<T[]>;
+    /** Close the underlying connection. */
+    close(): void;
 }
 
 /** Options passed to config loading functions, including overrides and environment variable bindings. */