@gobing-ai/ts-runtime 0.4.5 → 0.4.7

package/README.md

@@ -17,7 +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) |
+| SQL database | `createDbAdapter(config)` → `DbAdapter` | Bun SQLite via `@gobing-ai/ts-db` (optional peer) | 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:*`) |
@@ -63,6 +63,8 @@ classDiagram
         +stat(path) FileStat~|~null~|~Promise~FileStat|~
         +resolve(...segments) string
         +getProjectRoot() string
+        +readFileStream(path) AsyncIterable<string>▀optional (ADR-021)
+        +realPath(path) string▀optional (ADR-022)
     }
 
     class createNodeFileSystem {
@@ -72,6 +74,8 @@ classDiagram
         +ensureDir(path) void
         +stat(path) FileStat | null
         +getProjectRoot() string
+        +readFileStream(path) AsyncIterable<string>
+        +realPath(path) string
     }
 
     class createCfFileSystem {
@@ -346,6 +350,24 @@ assertRelativeExtensionPath('/etc/evil.ts');   // throws: must be relative
 assertRelativeExtensionPath('../escape.ts');   // throws: must not contain ".."
 ```
 
+The string-level guard does not resolve symlinks — a symlink inside `baseDir` that points outside passes
+the check. For symlink-safe confinement (ADR-022), supply a `realPath` canonicalizer to `LoadExtensionsOptions`:
+
+```ts
+import { loadExtensionModules } from '@gobing-ai/ts-runtime/extension';
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
+
+const fs = createNodeFileSystem('/abs/path');
+await loadExtensionModules(refs, {
+    allowExtensions: true,
+    moduleLoader: (p) => import(p),
+    realPath: fs.realPath,  // enables symlink confinement check
+}, register);
+```
+
+When `realPath` is provided, the loader canonicalizes both the resolved path and `baseDir`, rejecting
+symlinks that escape the declaring directory. When absent (e.g. CF Workers), the check is skipped.
+
 ### 7. File system abstraction
 
 Use `createNodeFileSystem()` for a real `node:fs`-backed filesystem (Node/Bun) or
@@ -366,6 +388,26 @@ cffs.getProjectRoot();   // '/bundle'
 cffs.readFile('/x');     // throws: "use D1, KV, or R2"
 ```
 
+Optional streaming and symlink-safe operations:
+
+```ts
+// Stream large files line-by-line (ADR-021) — Node/Bun only.
+// The JSONL importer uses this to avoid buffering multi-GB files.
+if (fs.readFileStream) {
+  for await (const line of fs.readFileStream('data/huge.jsonl')) {
+    // process one line at a time
+  }
+}
+
+// Canonical path resolution for symlink-safe extension confinement (ADR-022).
+// The extension loader uses this to verify that a symlink hasn't escaped baseDir.
+if (fs.realPath) {
+  const real = fs.realPath('/base/extensions/linked.ts');
+}
+```
+
+Both are optional — CF Workers stubs omit them. The JSONL importer falls back to `readFile` + split when `readFileStream` is absent; the extension loader skips the symlink check when `realPath` is absent.
+
 The old `getFs()` / `setFileSystem` global swap and `SyncFileSystem` are marked `@deprecated` —
 use `createNodeFileSystem()` or `ctx.require('fileSystem')` instead.
 
@@ -392,11 +434,25 @@ On Cloudflare Workers, `capabilities.hasSqlDatabase` is `false` and `createDbAda
 `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.
+**Dependency note (optional peer):** `@gobing-ai/ts-db` is declared as an **optional
+`peerDependency`** of `ts-runtime` (ADR-012 addendum), not a regular dependency — a regular entry
+would create a manifest cycle (`ts-db` depends on `ts-runtime`) and force-install `ts-db` (plus its
+`drizzle-orm` peer) on every consumer, including Workers bundles and apps that never touch SQL.
+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
+literal dynamic `import()` at runtime.
+
+**Who must install it:** only consumers that call `nodeBunFactory.createDbAdapter` on Node/Bun —
+install `@gobing-ai/ts-db` yourself (`bun add @gobing-ai/ts-db`). Workers consumers do not need it
+(`capabilities.hasSqlDatabase` is `false`; the method throws `D1NotConfiguredError`).
+
+**Bundling (`Bun --compile` / esbuild / Vite):** the literal specifier keeps `ts-db` bundler-visible,
+so `Bun --compile` can fold it into a standalone binary. If you bundle for a different runtime, mark
+`@gobing-ai/ts-db` `external` to preserve the dynamic import.
+
+**Failure mode:** if `@gobing-ai/ts-db` is absent or exports no `createDbAdapter` (incompatible
+version), `createDbAdapter` throws a typed `DbModuleNotInstalledError` (with the underlying resolution
+error chained as `cause`) instead of a raw `MODULE_NOT_FOUND`.
 
 ### 9. Graceful disposal
 

package/dist/db-errors.d.ts

@@ -11,4 +11,17 @@
 export declare class D1NotConfiguredError extends Error {
     constructor(message?: string);
 }
+/**
+ * Thrown by {@link RuntimeFactory.createDbAdapter} on `node-bun` when the
+ * optional peer `@gobing-ai/ts-db` is not installed.
+ *
+ * `ts-db` is an **optional peerDependency** of `ts-runtime` (ADR-012 addendum):
+ * it cannot be a regular dependency because `ts-db` depends on `ts-runtime`
+ * (manifest cycle). Consumers who call `nodeBunFactory.createDbAdapter` must
+ * install `@gobing-ai/ts-db` themselves. This error surfaces a missing module
+ * as an actionable, typed failure instead of a raw `MODULE_NOT_FOUND`.
+ */
+export declare class DbModuleNotInstalledError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
 //# sourceMappingURL=db-errors.d.ts.map

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

@@ -1 +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"}
+{"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;AAED;;;;;;;;;GASG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBAE5C,OAAO,SAAoO,EAC3O,OAAO,CAAC,EAAE,YAAY;CAK7B"}

package/dist/db-errors.js

@@ -14,3 +14,19 @@ export class D1NotConfiguredError extends Error {
         this.name = 'D1NotConfiguredError';
     }
 }
+/**
+ * Thrown by {@link RuntimeFactory.createDbAdapter} on `node-bun` when the
+ * optional peer `@gobing-ai/ts-db` is not installed.
+ *
+ * `ts-db` is an **optional peerDependency** of `ts-runtime` (ADR-012 addendum):
+ * it cannot be a regular dependency because `ts-db` depends on `ts-runtime`
+ * (manifest cycle). Consumers who call `nodeBunFactory.createDbAdapter` must
+ * install `@gobing-ai/ts-db` themselves. This error surfaces a missing module
+ * as an actionable, typed failure instead of a raw `MODULE_NOT_FOUND`.
+ */
+export class DbModuleNotInstalledError extends Error {
+    constructor(message = '@gobing-ai/ts-db is not installed. It is an optional peer of @gobing-ai/ts-runtime, required only for createDbAdapter on node-bun. Install it (`bun add @gobing-ai/ts-db`) or, when bundling, mark `@gobing-ai/ts-db` external.', options) {
+        super(message, options);
+        this.name = 'DbModuleNotInstalledError';
+    }
+}

package/dist/extension/extension-loader.d.ts

@@ -37,6 +37,18 @@ export interface LoadExtensionsOptions {
      * means the shared core has no ambient code-loading capability of its own.
      */
     readonly moduleLoader: (absPath: string) => Promise<Record<string, unknown>>;
+    /**
+     * Optional canonical-path resolver for symlink-safe confinement (ADR-022).
+     *
+     * When provided, the loader resolves the **real** path of the extension module
+     * (following symlinks) and re-checks that it remains within `baseDir`'s real
+     * root. This closes the symlink-escape vector: an authored path like
+     * `extensions/legit.ts` can pass the string-level `..` guard but still point
+     * outside `baseDir` via a symlink. Callers that serve extension modules from a
+     * real filesystem (e.g. `createNodeFileSystem().realPath`) should supply this.
+     * Stub filesystems without symlinks (e.g. CF Workers) may omit it.
+     */
+    readonly realPath?: (absPath: string) => string;
 }
 /** A validated extension module export: an object carrying at least a string `name`. */
 export interface LoadedExtension {

package/dist/extension/extension-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension-loader.d.ts","sourceRoot":"","sources":["../../src/extension/extension-loader.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY,CAAC,cAAc,SAAS,MAAM,GAAG,MAAM;IAChE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACtD;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChF;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CAAC,cAAc,SAAS,MAAM,EACpE,IAAI,EAAE,SAAS,YAAY,CAAC,cAAc,CAAC,EAAE,EAC7C,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,CAAC,GAAG,EAAE,YAAY,CAAC,cAAc,CAAC,EAAE,SAAS,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAClG,OAAO,CAAC,IAAI,CAAC,CAgCf"}
+{"version":3,"file":"extension-loader.d.ts","sourceRoot":"","sources":["../../src/extension/extension-loader.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY,CAAC,cAAc,SAAS,MAAM,GAAG,MAAM;IAChE,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACtD;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7E;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACnD;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CAAC,cAAc,SAAS,MAAM,EACpE,IAAI,EAAE,SAAS,YAAY,CAAC,cAAc,CAAC,EAAE,EAC7C,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,CAAC,GAAG,EAAE,YAAY,CAAC,cAAc,CAAC,EAAE,SAAS,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAClG,OAAO,CAAC,IAAI,CAAC,CAsDf"}

package/dist/extension/extension-loader.js

@@ -35,6 +35,27 @@ export async function loadExtensionModules(refs, options, register) {
         // imports a caller-supplied absolute path it did not resolve itself.
         assertRelativeExtensionPath(ref.path, { sourceName: ref.sourceName });
         const absPath = resolve(ref.baseDir, ref.path);
+        // ADR-022: when realPath is available, canonicalize and re-check confinement
+        // to close the symlink-escape vector — an authored path with no ".." can still
+        // resolve outside baseDir via a symlink.
+        if (options.realPath) {
+            let realAbs;
+            let realBase;
+            try {
+                realAbs = options.realPath(absPath);
+                realBase = options.realPath(ref.baseDir);
+            }
+            catch (error) {
+                // Canonicalizers surface raw filesystem errors (e.g. ENOENT for a
+                // missing module) — rewrap with the declaring ref so the failing
+                // extension is identifiable from the message alone.
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new Error(`"${ref.sourceName}" extension "${ref.path}" cannot be canonicalized: ${reason}`);
+            }
+            if (realAbs !== realBase && !realAbs.startsWith(`${realBase}/`) && !realAbs.startsWith(`${realBase}\\`)) {
+                throw new Error(`"${ref.sourceName}" extension "${ref.path}" resolves outside baseDir via symlink (real: "${realAbs}", base: "${realBase}") — refusing to load`);
+            }
+        }
         const moduleExports = await options.moduleLoader(absPath);
         const candidate = moduleExports.default ?? moduleExports.extension;
         if (candidate === null ||

package/dist/extension/extension-path.d.ts

@@ -1,12 +1,18 @@
 /**
  * Assert that an extension module path is relative and does not escape its
- * declaring directory.
+ * declaring directory via string-level traversal.
  *
  * Extension declarations are data, and a path that is absolute or escapes via `..`
  * is a trust-boundary violation even when extension loading is explicitly allowed.
  * This is a standalone validator (not a schema refinement) so the loader can enforce
  * it at load time, independent of any engine's config schema — defense in depth.
  *
+ * This guard is string-level only: it rejects `..` segments and absolute paths in
+ * the declaration but does NOT resolve symlinks. A symlink inside `baseDir` that
+ * points outside it passes this check. For symlink-safe confinement, supply a
+ * `realPath` canonicalizer to `LoadExtensionsOptions` (ADR-022); the loader
+ * performs the filesystem-level check when `realPath` is provided.
+ *
  * @throws When the path is absolute or contains a `..` traversal segment.
  */
 export declare function assertRelativeExtensionPath(path: string, options?: {

package/dist/extension/extension-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension-path.d.ts","sourceRoot":"","sources":["../../src/extension/extension-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAQrG"}
+{"version":3,"file":"extension-path.d.ts","sourceRoot":"","sources":["../../src/extension/extension-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAQrG"}

package/dist/extension/extension-path.js

@@ -1,12 +1,18 @@
 /**
  * Assert that an extension module path is relative and does not escape its
- * declaring directory.
+ * declaring directory via string-level traversal.
  *
  * Extension declarations are data, and a path that is absolute or escapes via `..`
  * is a trust-boundary violation even when extension loading is explicitly allowed.
  * This is a standalone validator (not a schema refinement) so the loader can enforce
  * it at load time, independent of any engine's config schema — defense in depth.
  *
+ * This guard is string-level only: it rejects `..` segments and absolute paths in
+ * the declaration but does NOT resolve symlinks. A symlink inside `baseDir` that
+ * points outside it passes this check. For symlink-safe confinement, supply a
+ * `realPath` canonicalizer to `LoadExtensionsOptions` (ADR-022); the loader
+ * performs the filesystem-level check when `realPath` is provided.
+ *
  * @throws When the path is absolute or contains a `..` traversal segment.
  */
 export function assertRelativeExtensionPath(path, options = {}) {

package/dist/file-system-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-system-node.d.ts","sourceRoot":"","sources":["../src/file-system-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiBH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CA2D9D;AAWD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAaxD"}
+{"version":3,"file":"file-system-node.d.ts","sourceRoot":"","sources":["../src/file-system-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAmBH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CA+E9D;AAWD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAaxD"}

package/dist/file-system-node.js

@@ -9,7 +9,7 @@
  * `node:fs` fully, so this works on both runtimes without a Bun-specific
  * variant.
  */
-import { appendFileSync, cpSync, createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { appendFileSync, cpSync, createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { dirname, resolve as resolvePath } from 'node:path';
 /**
  * Create a {@link FileSystem} backed by `node:fs`.
@@ -23,6 +23,24 @@ export function createNodeFileSystem(root) {
         resolve: (...segments) => resolvePath(projectRoot, ...segments),
         exists: (path) => existsSync(path),
         readFile: (path) => readFileSync(path, 'utf-8'),
+        readFileStream: async function* (path) {
+            // WHY: large JSONL history files (100MB+) must not be loaded into memory
+            // all at once. createReadStream + manual line splitting lets the importer
+            // process records incrementally with constant memory.
+            const stream = createReadStream(path, { encoding: 'utf-8' });
+            let buffer = '';
+            for await (const chunk of stream) {
+                buffer += chunk;
+                const lines = buffer.split(/\r?\n/);
+                // Keep the last (possibly partial) line in the buffer.
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    yield line;
+                }
+            }
+            if (buffer.length > 0)
+                yield buffer;
+        },
         writeFile: (path, content) => {
             ensureParentDir(path);
             writeFileSync(path, content, 'utf-8');
@@ -62,6 +80,7 @@ export function createNodeFileSystem(root) {
                 return null;
             }
         },
+        realPath: (path) => realpathSync(path),
     };
 }
 // ── Helpers ──────────────────────────────────────────────────────────────

package/dist/file-system.d.ts

@@ -20,6 +20,18 @@ export interface FileSystem {
     exists(path: string): boolean | Promise<boolean>;
     /** Read file contents as UTF-8 string. Throws if not found. */
     readFile(path: string): string | Promise<string>;
+    /**
+     * Read file contents as a stream of UTF-8 text lines.
+     *
+     * Returns an async iterable yielding one line per iteration (without
+     * trailing newline). This is the streaming counterpart of `readFile`
+     * for large files that should not be loaded into memory all at once.
+     *
+     * Optional: Cloudflare Workers and other stubs may omit this method.
+     * Callers must check for its presence before use and fall back to
+     * `readFile` + `split` when unavailable.
+     */
+    readFileStream?(path: string): AsyncIterable<string>;
     /** Write file contents, creating parent directories as needed. */
     writeFile(path: string, content: string): void | Promise<void>;
     /** Append content to a file, creating it if it doesn't exist. */
@@ -41,6 +53,18 @@ export interface FileSystem {
         write(chunk: string): void;
         end(): void;
     };
+    /**
+     * Resolve the canonical (symlink-free) absolute path.
+     *
+     * WHY: used by the extension loader (ADR-022) to verify that an extension
+     * module's real path — after following symlinks — still falls within its
+     * declaring `baseDir`. Without this, a symlink can bypass the string-level
+     * `..` guard and load code from outside the intended directory.
+     *
+     * Optional: stubs without a real filesystem (e.g. CF Workers) may omit this.
+     * When absent, the extension loader skips the symlink confinement check.
+     */
+    realPath?(path: string): string;
     /** Resolve path segments relative to the project root. */
     resolve(...segments: string[]): string;
     /** Get the project root directory path. */

package/dist/file-system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-system.d.ts","sourceRoot":"","sources":["../src/file-system.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,MAAM,WAAW,QAAQ;IACrB,MAAM,IAAI,OAAO,CAAC;IAClB,WAAW,IAAI,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACvB,mCAAmC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjD,kEAAkE;IAClE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/D,iEAAiE;IACjE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE,kFAAkF;IAClF,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C,2DAA2D;IAC3D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEpD,8CAA8C;IAC9C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C,6CAA6C;IAC7C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD,4CAA4C;IAC5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,6EAA6E;IAC7E,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAE/D,6FAA6F;IAC7F,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,GAAG,IAAI,IAAI,CAAA;KAAE,CAAC;IAE7E,0DAA0D;IAC1D,OAAO,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAEvC,2CAA2C;IAC3C,cAAc,IAAI,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"file-system.d.ts","sourceRoot":"","sources":["../src/file-system.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,MAAM,WAAW,QAAQ;IACrB,MAAM,IAAI,OAAO,CAAC;IAClB,WAAW,IAAI,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACvB,mCAAmC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD;;;;;;;;;;OAUG;IACH,cAAc,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAErD,kEAAkE;IAClE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/D,iEAAiE;IACjE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE,kFAAkF;IAClF,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C,2DAA2D;IAC3D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEpD,8CAA8C;IAC9C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C,6CAA6C;IAC7C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD,4CAA4C;IAC5C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,6EAA6E;IAC7E,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAE/D,6FAA6F;IAC7F,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,GAAG,IAAI,IAAI,CAAA;KAAE,CAAC;IAE7E;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEhC,0DAA0D;IAC1D,OAAO,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAEvC,2CAA2C;IAC3C,cAAc,IAAI,MAAM,CAAC;CAC5B"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export * from './config';
 export * from './context';
 export { createRuntimeContextFromFactory } from './context';
-export { D1NotConfiguredError } from './db-errors';
+export { D1NotConfiguredError, DbModuleNotInstalledError } 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,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,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,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,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC9E,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,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,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,7 +1,7 @@
 export * from './config.js';
 export * from './context.js';
 export { createRuntimeContextFromFactory } from './context.js';
-export { D1NotConfiguredError } from './db-errors.js';
+export { D1NotConfiguredError, DbModuleNotInstalledError } from './db-errors.js';
 export { createCfFileSystem } from './file-system-cf.js';
 export { createNodeFileSystem, findProjectRoot } from './file-system-node.js';
 export { atomicWriteFile, atomicWriteJson, createLogStream, ensureDirForFile, readJsonFile, walkDir, writeJsonFile, } from './fs.js';

package/dist/path.d.ts

@@ -8,6 +8,8 @@ export declare function isAbsolutePath(path: string): boolean;
 export declare function dirnamePath(path: string): string;
 /** Return the last segment of a path. Optionally strip a trailing extension. */
 export declare function basenamePath(p: string, ext?: string): string;
+/** Convert a file:// URL into the portable path format used by this package. */
+export declare function fileUrlToPath(url: string): string;
 /** Compute a platform-independent relative path from `from` to `to`. Both paths should be absolute. */
 export declare function relativePath(from: string, to: string): string;
 /** Joins path segments with `/`, normalizing separators and collapsing redundant slashes. */

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAIA,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,oFAAoF;AACpF,eAAO,MAAM,GAAG,EAAE,MACgF,CAAC;AAEnG,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAmBD,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWhD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAkB7D;AAED,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAMtD;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBzD;AAED,qFAAqF;AACrF,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAIA,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,oFAAoF;AACpF,eAAO,MAAM,GAAG,EAAE,MACgF,CAAC;AAEnG,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAmBD,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWhD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBjD;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAkB7D;AAED,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAMtD;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBzD;AAED,qFAAqF;AACrF,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/path.js

@@ -54,6 +54,24 @@ export function basenamePath(p, ext) {
     }
     return base;
 }
+/** Convert a file:// URL into the portable path format used by this package. */
+export function fileUrlToPath(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'file:') {
+        throw new Error(`Expected file URL, got "${parsed.protocol}"`);
+    }
+    // Encoded separators would decode into extra path segments (e.g. "%2F..%2F"
+    // becoming "/../"), silently changing path semantics — reject like node:url does.
+    if (/%2f|%5c/i.test(parsed.pathname)) {
+        throw new Error('File URL path must not include encoded "/" or "\\" characters');
+    }
+    const pathname = decodeURIComponent(parsed.pathname);
+    const localPath = /^\/[A-Za-z]:\//.test(pathname) ? pathname.slice(1) : pathname;
+    if (parsed.hostname.length > 0 && parsed.hostname !== 'localhost') {
+        return normalizeSeparators(`//${parsed.hostname}${localPath}`);
+    }
+    return normalizeSeparators(localPath);
+}
 /** Compute a platform-independent relative path from `from` to `to`. Both paths should be absolute. */
 export function relativePath(from, to) {
     const fromParsed = pathParts(resolvePath(from));

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,cA8B5B,CAAC"}
+{"version":3,"file":"runtime-node-bun.d.ts","sourceRoot":"","sources":["../src/runtime-node-bun.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUxD,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAqC5B,CAAC"}

package/dist/runtime-node-bun.js

@@ -1,5 +1,6 @@
 import { parse as parseYaml } from 'yaml';
 import { buildConfigFromObject, getProcessEnv } from './config.js';
+import { DbModuleNotInstalledError } from './db-errors.js';
 import { createNodeFileSystem } from './file-system-node.js';
 import { ProcessExecutor } from './process-executor.js';
 // Lazy re-initialisable singleton for test isolation.
@@ -30,14 +31,22 @@ export const nodeBunFactory = {
         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));
+        // Dynamic import via variable specifier — ts-db depends on ts-runtime,
+        // so a static (or literal-specifier dynamic) import forces tsc to resolve
+        // the module at build time, raising TS2307 when no prebuilt db dist/
+        // exists (CI/clean checkout). A variable specifier is opaque to tsc.
+        // ts-db is an optional peerDependency (ADR-012 addendum, task 0040).
+        const tsDbSpec = '@gobing-ai/ts-db';
+        let mod;
+        try {
+            mod = await import(tsDbSpec);
+        }
+        catch (cause) {
+            throw new DbModuleNotInstalledError(undefined, { cause });
+        }
+        if (typeof mod.createDbAdapter !== 'function') {
+            throw new DbModuleNotInstalledError('@gobing-ai/ts-db is installed but does not export createDbAdapter — the installed version may be incompatible or partial.');
+        }
         return mod.createDbAdapter({ driver: 'bun-sqlite', url: config.url });
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-runtime",
-    "version": "0.4.5",
+    "version": "0.4.7",
     "description": "@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.",
     "keywords": [
         "typescript",
@@ -58,15 +58,23 @@
         "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.4.5",
+        "@gobing-ai/ts-utils": "^0.4.7",
         "execa": "^9.5.0",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.4.5",
+        "@gobing-ai/ts-db": "^0.4.7",
         "@types/bun": "1.3.14"
     },
+    "peerDependencies": {
+        "@gobing-ai/ts-db": "^0.4.7"
+    },
+    "peerDependenciesMeta": {
+        "@gobing-ai/ts-db": {
+            "optional": true
+        }
+    },
     "publishConfig": {
         "access": "public"
     }

package/src/db-errors.ts

@@ -14,3 +14,23 @@ export class D1NotConfiguredError extends Error {
         this.name = 'D1NotConfiguredError';
     }
 }
+
+/**
+ * Thrown by {@link RuntimeFactory.createDbAdapter} on `node-bun` when the
+ * optional peer `@gobing-ai/ts-db` is not installed.
+ *
+ * `ts-db` is an **optional peerDependency** of `ts-runtime` (ADR-012 addendum):
+ * it cannot be a regular dependency because `ts-db` depends on `ts-runtime`
+ * (manifest cycle). Consumers who call `nodeBunFactory.createDbAdapter` must
+ * install `@gobing-ai/ts-db` themselves. This error surfaces a missing module
+ * as an actionable, typed failure instead of a raw `MODULE_NOT_FOUND`.
+ */
+export class DbModuleNotInstalledError extends Error {
+    constructor(
+        message = '@gobing-ai/ts-db is not installed. It is an optional peer of @gobing-ai/ts-runtime, required only for createDbAdapter on node-bun. Install it (`bun add @gobing-ai/ts-db`) or, when bundling, mark `@gobing-ai/ts-db` external.',
+        options?: ErrorOptions,
+    ) {
+        super(message, options);
+        this.name = 'DbModuleNotInstalledError';
+    }
+}

package/src/extension/extension-loader.ts

@@ -39,6 +39,18 @@ export interface LoadExtensionsOptions {
      * means the shared core has no ambient code-loading capability of its own.
      */
     readonly moduleLoader: (absPath: string) => Promise<Record<string, unknown>>;
+    /**
+     * Optional canonical-path resolver for symlink-safe confinement (ADR-022).
+     *
+     * When provided, the loader resolves the **real** path of the extension module
+     * (following symlinks) and re-checks that it remains within `baseDir`'s real
+     * root. This closes the symlink-escape vector: an authored path like
+     * `extensions/legit.ts` can pass the string-level `..` guard but still point
+     * outside `baseDir` via a symlink. Callers that serve extension modules from a
+     * real filesystem (e.g. `createNodeFileSystem().realPath`) should supply this.
+     * Stub filesystems without symlinks (e.g. CF Workers) may omit it.
+     */
+    readonly realPath?: (absPath: string) => string;
 }
 
 /** A validated extension module export: an object carrying at least a string `name`. */
@@ -91,6 +103,28 @@ export async function loadExtensionModules<TExtensionKind extends string>(
         // imports a caller-supplied absolute path it did not resolve itself.
         assertRelativeExtensionPath(ref.path, { sourceName: ref.sourceName });
         const absPath = resolve(ref.baseDir, ref.path);
+        // ADR-022: when realPath is available, canonicalize and re-check confinement
+        // to close the symlink-escape vector — an authored path with no ".." can still
+        // resolve outside baseDir via a symlink.
+        if (options.realPath) {
+            let realAbs: string;
+            let realBase: string;
+            try {
+                realAbs = options.realPath(absPath);
+                realBase = options.realPath(ref.baseDir);
+            } catch (error) {
+                // Canonicalizers surface raw filesystem errors (e.g. ENOENT for a
+                // missing module) — rewrap with the declaring ref so the failing
+                // extension is identifiable from the message alone.
+                const reason = error instanceof Error ? error.message : String(error);
+                throw new Error(`"${ref.sourceName}" extension "${ref.path}" cannot be canonicalized: ${reason}`);
+            }
+            if (realAbs !== realBase && !realAbs.startsWith(`${realBase}/`) && !realAbs.startsWith(`${realBase}\\`)) {
+                throw new Error(
+                    `"${ref.sourceName}" extension "${ref.path}" resolves outside baseDir via symlink (real: "${realAbs}", base: "${realBase}") — refusing to load`,
+                );
+            }
+        }
         const moduleExports = await options.moduleLoader(absPath);
         const candidate = moduleExports.default ?? moduleExports.extension;
         if (

package/src/extension/extension-path.ts

@@ -1,12 +1,18 @@
 /**
  * Assert that an extension module path is relative and does not escape its
- * declaring directory.
+ * declaring directory via string-level traversal.
  *
  * Extension declarations are data, and a path that is absolute or escapes via `..`
  * is a trust-boundary violation even when extension loading is explicitly allowed.
  * This is a standalone validator (not a schema refinement) so the loader can enforce
  * it at load time, independent of any engine's config schema — defense in depth.
  *
+ * This guard is string-level only: it rejects `..` segments and absolute paths in
+ * the declaration but does NOT resolve symlinks. A symlink inside `baseDir` that
+ * points outside it passes this check. For symlink-safe confinement, supply a
+ * `realPath` canonicalizer to `LoadExtensionsOptions` (ADR-022); the loader
+ * performs the filesystem-level check when `realPath` is provided.
+ *
  * @throws When the path is absolute or contains a `..` traversal segment.
  */
 export function assertRelativeExtensionPath(path: string, options: { sourceName?: string } = {}): void {

package/src/file-system-node.ts

@@ -13,11 +13,13 @@
 import {
     appendFileSync,
     cpSync,
+    createReadStream,
     createWriteStream,
     existsSync,
     mkdirSync,
     readdirSync,
     readFileSync,
+    realpathSync,
     renameSync,
     rmSync,
     statSync,
@@ -44,6 +46,24 @@ export function createNodeFileSystem(root?: string): FileSystem {
 
         readFile: (path: string) => readFileSync(path, 'utf-8'),
 
+        readFileStream: async function* (path: string): AsyncIterable<string> {
+            // WHY: large JSONL history files (100MB+) must not be loaded into memory
+            // all at once. createReadStream + manual line splitting lets the importer
+            // process records incrementally with constant memory.
+            const stream = createReadStream(path, { encoding: 'utf-8' });
+            let buffer = '';
+            for await (const chunk of stream) {
+                buffer += chunk;
+                const lines = buffer.split(/\r?\n/);
+                // Keep the last (possibly partial) line in the buffer.
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    yield line;
+                }
+            }
+            if (buffer.length > 0) yield buffer;
+        },
+
         writeFile: (path: string, content: string) => {
             ensureParentDir(path);
             writeFileSync(path, content, 'utf-8');
@@ -90,6 +110,8 @@ export function createNodeFileSystem(root?: string): FileSystem {
                 return null;
             }
         },
+
+        realPath: (path: string) => realpathSync(path),
     };
 }
 

package/src/file-system.ts

@@ -22,6 +22,18 @@ export interface FileSystem {
 
     /** Read file contents as UTF-8 string. Throws if not found. */
     readFile(path: string): string | Promise<string>;
+    /**
+     * Read file contents as a stream of UTF-8 text lines.
+     *
+     * Returns an async iterable yielding one line per iteration (without
+     * trailing newline). This is the streaming counterpart of `readFile`
+     * for large files that should not be loaded into memory all at once.
+     *
+     * Optional: Cloudflare Workers and other stubs may omit this method.
+     * Callers must check for its presence before use and fall back to
+     * `readFile` + `split` when unavailable.
+     */
+    readFileStream?(path: string): AsyncIterable<string>;
 
     /** Write file contents, creating parent directories as needed. */
     writeFile(path: string, content: string): void | Promise<void>;
@@ -49,6 +61,19 @@ export interface FileSystem {
     /** Create a writable stream for append-only output (Node/Bun only). Throws on CF Workers. */
     createWriteStream(path: string): { write(chunk: string): void; end(): void };
 
+    /**
+     * Resolve the canonical (symlink-free) absolute path.
+     *
+     * WHY: used by the extension loader (ADR-022) to verify that an extension
+     * module's real path — after following symlinks — still falls within its
+     * declaring `baseDir`. Without this, a symlink can bypass the string-level
+     * `..` guard and load code from outside the intended directory.
+     *
+     * Optional: stubs without a real filesystem (e.g. CF Workers) may omit this.
+     * When absent, the extension loader skips the symlink confinement check.
+     */
+    realPath?(path: string): string;
+
     /** Resolve path segments relative to the project root. */
     resolve(...segments: string[]): string;
 

package/src/index.ts

@@ -1,7 +1,7 @@
 export * from './config';
 export * from './context';
 export { createRuntimeContextFromFactory } from './context';
-export { D1NotConfiguredError } from './db-errors';
+export { D1NotConfiguredError, DbModuleNotInstalledError } 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/path.ts

@@ -58,6 +58,27 @@ export function basenamePath(p: string, ext?: string): string {
     return base;
 }
 
+/** Convert a file:// URL into the portable path format used by this package. */
+export function fileUrlToPath(url: string): string {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'file:') {
+        throw new Error(`Expected file URL, got "${parsed.protocol}"`);
+    }
+
+    // Encoded separators would decode into extra path segments (e.g. "%2F..%2F"
+    // becoming "/../"), silently changing path semantics — reject like node:url does.
+    if (/%2f|%5c/i.test(parsed.pathname)) {
+        throw new Error('File URL path must not include encoded "/" or "\\" characters');
+    }
+
+    const pathname = decodeURIComponent(parsed.pathname);
+    const localPath = /^\/[A-Za-z]:\//.test(pathname) ? pathname.slice(1) : pathname;
+    if (parsed.hostname.length > 0 && parsed.hostname !== 'localhost') {
+        return normalizeSeparators(`//${parsed.hostname}${localPath}`);
+    }
+    return normalizeSeparators(localPath);
+}
+
 /** Compute a platform-independent relative path from `from` to `to`. Both paths should be absolute. */
 export function relativePath(from: string, to: string): string {
     const fromParsed = pathParts(resolvePath(from));

package/src/runtime-node-bun.ts

@@ -1,6 +1,7 @@
 import { parse as parseYaml } from 'yaml';
 import type { Config } from './config';
 import { buildConfigFromObject, getProcessEnv } from './config';
+import { DbModuleNotInstalledError } from './db-errors';
 import type { FileSystem } from './file-system';
 import { createNodeFileSystem } from './file-system-node';
 import { ProcessExecutor, type ProcessExecutorConfig } from './process-executor';
@@ -40,16 +41,23 @@ export const nodeBunFactory: RuntimeFactory = {
     },
 
     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;
-        };
+        // Dynamic import via variable specifier — ts-db depends on ts-runtime,
+        // so a static (or literal-specifier dynamic) import forces tsc to resolve
+        // the module at build time, raising TS2307 when no prebuilt db dist/
+        // exists (CI/clean checkout). A variable specifier is opaque to tsc.
+        // ts-db is an optional peerDependency (ADR-012 addendum, task 0040).
+        const tsDbSpec = '@gobing-ai/ts-db';
+        let mod: { createDbAdapter: (config: DatabaseConfig) => Promise<RuntimeDbAdapter> };
+        try {
+            mod = await import(tsDbSpec);
+        } catch (cause) {
+            throw new DbModuleNotInstalledError(undefined, { cause });
+        }
+        if (typeof mod.createDbAdapter !== 'function') {
+            throw new DbModuleNotInstalledError(
+                '@gobing-ai/ts-db is installed but does not export createDbAdapter — the installed version may be incompatible or partial.',
+            );
+        }
         return mod.createDbAdapter({ driver: 'bun-sqlite', url: config.url });
     },
 };