@gobing-ai/ts-runtime 0.4.6 → 0.4.8

package/README.md

@@ -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.
 

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/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":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAUxD,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAwC5B,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

@@ -31,18 +31,15 @@ export const nodeBunFactory = {
         return loadNodeConfig(options);
     },
     async createDbAdapter(config) {
-        // Dynamic import via a variable specifier — this prevents tsc from
-        // statically resolving @gobing-ai/ts-db at build time. ts-db builds
-        // AFTER ts-runtime (it depends on ts-runtime), so a literal specifier
-        // or `typeof import()` annotation triggers TS2307 in a clean CI
-        // checkout where no prebuilt dist/ exists yet. At runtime Bun resolves
-        // the module via the workspace symlink.
-        // ts-db is an optional peerDependency (ADR-012 addendum) — if the
-        // consumer has not installed it, surface a typed error.
-        const moduleSpecifier = '@gobing-ai/ts-db';
+        // 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(moduleSpecifier));
+            mod = await import(tsDbSpec);
         }
         catch (cause) {
             throw new DbModuleNotInstalledError(undefined, { cause });

package/package.json

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

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/runtime-node-bun.ts

@@ -41,18 +41,15 @@ export const nodeBunFactory: RuntimeFactory = {
     },
 
     async createDbAdapter(config: DatabaseConfig): Promise<RuntimeDbAdapter> {
-        // Dynamic import via a variable specifier — this prevents tsc from
-        // statically resolving @gobing-ai/ts-db at build time. ts-db builds
-        // AFTER ts-runtime (it depends on ts-runtime), so a literal specifier
-        // or `typeof import()` annotation triggers TS2307 in a clean CI
-        // checkout where no prebuilt dist/ exists yet. At runtime Bun resolves
-        // the module via the workspace symlink.
-        // ts-db is an optional peerDependency (ADR-012 addendum) — if the
-        // consumer has not installed it, surface a typed error.
-        const moduleSpecifier = '@gobing-ai/ts-db';
-        let mod: { 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(moduleSpecifier)) as typeof mod;
+            mod = await import(tsDbSpec);
         } catch (cause) {
             throw new DbModuleNotInstalledError(undefined, { cause });
         }