@grafema/core 0.2.5-beta → 0.2.7

package/src/resources/InfraResourceMapImpl.ts

@@ -0,0 +1,119 @@
+import type { InfraResourceMap, ResourceMapping, AbstractResource, AbstractResourceType, ConcreteResourceRef } from '@grafema/types';
+import { INFRA_RESOURCE_MAP_ID } from '@grafema/types';
+
+/**
+ * Default implementation of InfraResourceMap.
+ *
+ * Stores mappings indexed by abstractType -> name -> AbstractResource
+ * for O(1) lookup. Multiple concrete resources can map to the same
+ * abstract resource (e.g., K8s Deployment + Terraform both create compute:service:api).
+ *
+ * Complexity:
+ * - register: O(1) amortized (map insertions)
+ * - findAbstract: O(1) nested map lookup
+ * - findByType: O(n) where n = resources of that type
+ * - findByEnv: O(N) where N = total resources
+ */
+export class InfraResourceMapImpl implements InfraResourceMap {
+  readonly id = INFRA_RESOURCE_MAP_ID;
+
+  /** abstractType -> name -> AbstractResource */
+  private byTypeAndName = new Map<string, Map<string, AbstractResource>>();
+  /** abstractId -> AbstractResource for O(1) lookup */
+  private byId = new Map<string, AbstractResource>();
+
+  register(mapping: ResourceMapping): void {
+    let nameMap = this.byTypeAndName.get(mapping.abstractType);
+    if (!nameMap) {
+      nameMap = new Map();
+      this.byTypeAndName.set(mapping.abstractType, nameMap);
+    }
+
+    const provider: ConcreteResourceRef = {
+      id: mapping.concreteId,
+      type: mapping.concreteType,
+      tool: mapping.sourceTool,
+      file: mapping.sourceFile,
+    };
+
+    const existing = nameMap.get(mapping.name);
+    if (existing) {
+      // Deduplicate providers
+      const isDuplicate = existing.providers.some(p => p.id === provider.id);
+      if (!isDuplicate) {
+        existing.providers.push(provider);
+      }
+      // Merge metadata (later registrations can add fields)
+      existing.metadata = { ...existing.metadata, ...mapping.metadata };
+      // Merge env
+      if (mapping.env !== undefined) {
+        existing.env = mergeEnv(existing.env, mapping.env);
+      }
+    } else {
+      const abstract: AbstractResource = {
+        id: mapping.abstractId,
+        type: mapping.abstractType,
+        name: mapping.name,
+        env: mapping.env,
+        metadata: { ...mapping.metadata },
+        providers: [provider],
+      };
+      nameMap.set(mapping.name, abstract);
+      this.byId.set(mapping.abstractId, abstract);
+    }
+  }
+
+  findAbstract(name: string, type: AbstractResourceType): AbstractResource | null {
+    return this.byTypeAndName.get(type)?.get(name) ?? null;
+  }
+
+  findConcrete(abstractId: string): ConcreteResourceRef[] {
+    const abstract = this.byId.get(abstractId);
+    return abstract ? [...abstract.providers] : [];
+  }
+
+  findByType(type: AbstractResourceType): AbstractResource[] {
+    const nameMap = this.byTypeAndName.get(type);
+    return nameMap ? [...nameMap.values()] : [];
+  }
+
+  findByEnv(env: string): AbstractResource[] {
+    const result: AbstractResource[] = [];
+    for (const abstract of this.byId.values()) {
+      if (matchesEnv(abstract.env, env)) {
+        result.push(abstract);
+      }
+    }
+    return result;
+  }
+
+  getAll(): AbstractResource[] {
+    return [...this.byId.values()];
+  }
+
+  get resourceCount(): number {
+    return this.byId.size;
+  }
+}
+
+/** Merge environment values, deduplicating */
+function mergeEnv(existing: string | string[] | undefined, incoming: string | string[] | undefined): string | string[] | undefined {
+  if (existing === undefined) return incoming;
+  if (incoming === undefined) return existing;
+  const existingArr = Array.isArray(existing) ? existing : [existing];
+  const incomingArr = Array.isArray(incoming) ? incoming : [incoming];
+  const merged = [...new Set([...existingArr, ...incomingArr])];
+  return merged.length === 1 ? merged[0] : merged;
+}
+
+/** Check if resource env matches filter */
+function matchesEnv(resourceEnv: string | string[] | undefined, filterEnv: string): boolean {
+  if (resourceEnv === undefined) return true; // undefined = all environments
+  if (Array.isArray(resourceEnv)) return resourceEnv.includes(filterEnv);
+  return resourceEnv === filterEnv;
+}
+
+/** Factory function for creating an InfraResourceMap Resource */
+export function createInfraResourceMap(): InfraResourceMapImpl {
+  return new InfraResourceMapImpl();
+}

package/src/resources/RoutingMapImpl.ts

@@ -0,0 +1,133 @@
+import type { RoutingMap, RoutingRule, MatchContext, MatchResult } from '@grafema/types';
+
+/**
+ * Default implementation of RoutingMap.
+ *
+ * Stores rules in a nested Map<fromService, Map<toService, RoutingRule[]>>
+ * for O(1) lookup by fromService in findMatch.
+ *
+ * Complexity:
+ * - addRule: O(r) dedup check where r = rules for the pair
+ * - findMatch: O(t * r + c * log c) where t = target services for fromService, r = rules per pair, c = matching candidates
+ * - findRulesForPair: O(1) nested map lookup + O(r) copy
+ */
+export class RoutingMapImpl implements RoutingMap {
+  readonly id = 'routing:map' as const;
+
+  /** Rules indexed by fromService → toService → rules[] for O(1) lookup by service */
+  private rulesByFrom = new Map<string, Map<string, RoutingRule[]>>();
+  /** All rules in insertion order */
+  private allRules: RoutingRule[] = [];
+
+  addRule(rule: RoutingRule): void {
+    let toMap = this.rulesByFrom.get(rule.from);
+    if (!toMap) {
+      toMap = new Map();
+      this.rulesByFrom.set(rule.from, toMap);
+    }
+
+    let rules = toMap.get(rule.to);
+    if (!rules) {
+      rules = [];
+      toMap.set(rule.to, rules);
+    }
+
+    // Deduplicate: skip if identical rule already exists
+    const isDuplicate = rules.some(
+      r => r.stripPrefix === rule.stripPrefix && r.addPrefix === rule.addPrefix
+    );
+    if (!isDuplicate) {
+      rules.push(rule);
+      this.allRules.push(rule);
+    }
+  }
+
+  addRules(rules: RoutingRule[]): void {
+    for (const rule of rules) {
+      this.addRule(rule);
+    }
+  }
+
+  findMatch(context: MatchContext): MatchResult | null {
+    const toMap = this.rulesByFrom.get(context.fromService);
+    if (!toMap) return null;
+
+    // Collect all matching candidates across all target services
+    const candidates: { rule: RoutingRule; transformedUrl: string }[] = [];
+
+    for (const rules of toMap.values()) {
+      for (const rule of rules) {
+        const transformed = this.applyRule(context.requestUrl, rule);
+        if (transformed !== null) {
+          candidates.push({ rule, transformedUrl: transformed });
+        }
+      }
+    }
+
+    if (candidates.length === 0) return null;
+
+    // Sort: longer stripPrefix first, then lower priority number
+    candidates.sort((a, b) => {
+      const aLen = a.rule.stripPrefix?.length ?? 0;
+      const bLen = b.rule.stripPrefix?.length ?? 0;
+      if (aLen !== bLen) return bLen - aLen;
+      return (a.rule.priority ?? 0) - (b.rule.priority ?? 0);
+    });
+
+    const best = candidates[0];
+    return {
+      transformedUrl: best.transformedUrl,
+      targetService: best.rule.to,
+      rule: best.rule,
+    };
+  }
+
+  findRulesForPair(fromService: string, toService: string): RoutingRule[] {
+    return [...(this.rulesByFrom.get(fromService)?.get(toService) ?? [])];
+  }
+
+  getAllRules(): RoutingRule[] {
+    return [...this.allRules];
+  }
+
+  get ruleCount(): number {
+    return this.allRules.length;
+  }
+
+  /**
+   * Apply a routing rule to transform a URL.
+   * Returns transformed URL, or null if the rule's stripPrefix doesn't match.
+   */
+  private applyRule(url: string, rule: RoutingRule): string | null {
+    let result = url;
+
+    // Strip prefix
+    if (rule.stripPrefix) {
+      if (!result.startsWith(rule.stripPrefix)) {
+        return null; // Rule doesn't apply — prefix doesn't match
+      }
+      const afterPrefix = result.slice(rule.stripPrefix.length);
+      // Verify prefix boundary: next char must be '/' or end of string
+      if (afterPrefix !== '' && !afterPrefix.startsWith('/')) {
+        return null; // Partial prefix match (e.g., /api doesn't strip from /api-v2)
+      }
+      result = afterPrefix || '/';
+    }
+
+    // Add prefix
+    if (rule.addPrefix) {
+      if (result.startsWith('/') && rule.addPrefix.endsWith('/')) {
+        result = rule.addPrefix + result.slice(1);
+      } else {
+        result = rule.addPrefix + result;
+      }
+    }
+
+    return result;
+  }
+}
+
+/** Factory function for creating a RoutingMap Resource */
+export function createRoutingMap(): RoutingMapImpl {
+  return new RoutingMapImpl();
+}

package/src/storage/backends/RFDBServerBackend.ts

@@ -22,18 +22,15 @@ import { RFDBClient } from '@grafema/rfdb-client';
 import { existsSync, unlinkSync } from 'fs';
 import { spawn, type ChildProcess } from 'child_process';
 import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { createRequire } from 'module';
 import { setTimeout as sleep } from 'timers/promises';
 
-import type { WireNode, WireEdge, FieldDeclaration, AttrQuery as RFDBAttrQuery } from '@grafema/types';
+import type { WireNode, WireEdge, FieldDeclaration, CommitDelta, AttrQuery as RFDBAttrQuery } from '@grafema/types';
 import type { NodeType, EdgeType } from '@grafema/types';
-import type { BaseNodeRecord, EdgeRecord } from '@grafema/types';
+import { findRfdbBinary } from '../../utils/findRfdbBinary.js';
+import type { BaseNodeRecord, EdgeRecord, AnyBrandedNode } from '@grafema/types';
+import { brandNodeInternal } from '../../core/brandNodeInternal.js';
 import type { AttrQuery, GraphStats, GraphExport } from '../../core/GraphBackend.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
 /**
  * Options for RFDBServerBackend
  */
@@ -105,6 +102,7 @@ export class RFDBServerBackend {
   private client: RFDBClient | null;
   private serverProcess: ChildProcess | null;
   connected: boolean;  // Public for compatibility
+  private protocolVersion: number = 2; // Negotiated protocol version
   private edgeTypes: Set<string>;
   private _cachedNodeCounts: Record<string, number> | undefined;
   private _cachedEdgeCounts: Record<string, number> | undefined;
@@ -166,7 +164,8 @@ export class RFDBServerBackend {
       // Verify server is responsive
       await this.client.ping();
       this.connected = true;
-      this.log(`[RFDBServerBackend] Connected to RFDB server at ${this.socketPath}`);
+      await this._negotiateProtocol();
+      this.log(`[RFDBServerBackend] Connected to RFDB server at ${this.socketPath} (protocol v${this.protocolVersion})`);
       return;
     } catch {
       // Server not running or stale socket
@@ -190,7 +189,8 @@ export class RFDBServerBackend {
     await this.client.connect();
     await this.client.ping();
     this.connected = true;
-    this.log(`[RFDBServerBackend] Connected to RFDB server at ${this.socketPath}`);
+    await this._negotiateProtocol();
+    this.log(`[RFDBServerBackend] Connected to RFDB server at ${this.socketPath} (protocol v${this.protocolVersion})`);
   }
 
   /**
@@ -201,62 +201,15 @@ export class RFDBServerBackend {
   }
 
   /**
-   * Find RFDB server binary in order of preference:
-   * 1. packages/rfdb-server/target/release (monorepo development - prioritized for dev)
-   * 2. packages/rfdb-server/target/debug
-   * 3. @grafema/rfdb npm package
-   * 4. ~/.local/bin/rfdb-server (user-installed binary)
+   * Find RFDB server binary using shared utility.
+   * Delegates to findRfdbBinary() for consistent search across all entry points.
    */
   private _findServerBinary(): string | null {
-    // 1. Check packages/rfdb-server in monorepo (prioritized for development)
-    const projectRoot = join(__dirname, '../../../../..');
-    const releaseBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
-    if (existsSync(releaseBinary)) {
-      this.log(`[RFDBServerBackend] Found release binary: ${releaseBinary}`);
-      return releaseBinary;
-    }
-
-    // 2. Check debug build
-    const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
-    if (existsSync(debugBinary)) {
-      this.log(`[RFDBServerBackend] Found debug binary: ${debugBinary}`);
-      return debugBinary;
-    }
-
-    // 3. Check @grafema/rfdb npm package
-    try {
-      const require = createRequire(import.meta.url);
-      const rfdbPkg = require.resolve('@grafema/rfdb');
-      const rfdbDir = dirname(rfdbPkg);
-      const platform = process.platform;
-      const arch = process.arch;
-
-      let platformDir: string;
-      if (platform === 'darwin') {
-        platformDir = arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
-      } else if (platform === 'linux') {
-        platformDir = arch === 'arm64' ? 'linux-arm64' : 'linux-x64';
-      } else {
-        platformDir = `${platform}-${arch}`;
-      }
-
-      const npmBinary = join(rfdbDir, 'prebuilt', platformDir, 'rfdb-server');
-      if (existsSync(npmBinary)) {
-        this.log(`[RFDBServerBackend] Found binary in @grafema/rfdb: ${npmBinary}`);
-        return npmBinary;
-      }
-    } catch {
-      // @grafema/rfdb not installed
-    }
-
-    // 4. Check ~/.local/bin (user-installed binary for unsupported platforms)
-    const homeBinary = join(process.env.HOME || '', '.local', 'bin', 'rfdb-server');
-    if (existsSync(homeBinary)) {
-      this.log(`[RFDBServerBackend] Found user binary: ${homeBinary}`);
-      return homeBinary;
+    const binaryPath = findRfdbBinary();
+    if (binaryPath) {
+      this.log(`[RFDBServerBackend] Found binary: ${binaryPath}`);
     }
-
-    return null;
+    return binaryPath;
   }
 
   /**
@@ -310,6 +263,23 @@ export class RFDBServerBackend {
     this.log(`[RFDBServerBackend] Server started on ${this.socketPath}`);
   }
 
+  /**
+   * Negotiate protocol version with server.
+   * Requests v3 (semantic IDs), falls back to v2 if server doesn't support it.
+   * Called after ping() confirmed connectivity, so failures here indicate
+   * the server doesn't support hello/v3, not network issues.
+   */
+  private async _negotiateProtocol(): Promise<void> {
+    if (!this.client) return;
+    try {
+      const hello = await this.client.hello(3);
+      this.protocolVersion = hello.protocolVersion;
+    } catch {
+      // Server predates hello command or doesn't support v3 — safe v2 fallback
+      this.protocolVersion = 2;
+    }
+  }
+
   /**
    * Close client connection. Server continues running to serve other clients.
    */
@@ -376,18 +346,25 @@ export class RFDBServerBackend {
     if (!this.client) throw new Error('Not connected');
     if (!nodes.length) return;
 
+    const useV3 = this.protocolVersion >= 3;
     const wireNodes: WireNode[] = nodes.map(n => {
       // Extract metadata from node
       const { id, type, nodeType, node_type, name, file, exported, ...rest } = n;
 
-      return {
+      const wire: WireNode = {
         id: String(id),
         nodeType: (nodeType || node_type || type || 'UNKNOWN') as NodeType,
         name: name || '',
         file: file || '',
         exported: exported || false,
-        metadata: JSON.stringify({ originalId: String(id), ...rest }),
+        metadata: useV3
+          ? JSON.stringify(rest)
+          : JSON.stringify({ originalId: String(id), ...rest }),
       };
+      if (useV3) {
+        wire.semanticId = String(id);
+      }
+      return wire;
     });
 
     await this.client.addNodes(wireNodes);
@@ -413,22 +390,19 @@ export class RFDBServerBackend {
       if (typeof edgeType === 'string') this.edgeTypes.add(edgeType);
     }
 
+    const useV3 = this.protocolVersion >= 3;
     const wireEdges: WireEdge[] = edges.map(e => {
       const { src, dst, type, edgeType, edge_type, etype, metadata, ...rest } = e;
 
       // Flatten metadata: spread both edge-level properties and nested metadata
-      const flatMetadata = {
-        _origSrc: String(src),
-        _origDst: String(dst),
-        ...rest,
-        ...(typeof metadata === 'object' && metadata !== null ? metadata : {})
-      };
+      const flatMetadata = useV3
+        ? { ...rest, ...(typeof metadata === 'object' && metadata !== null ? metadata : {}) }
+        : { _origSrc: String(src), _origDst: String(dst), ...rest, ...(typeof metadata === 'object' && metadata !== null ? metadata : {}) };
 
       return {
         src: String(src),
         dst: String(dst),
         edgeType: (edgeType || edge_type || etype || type || 'UNKNOWN') as EdgeType,
-        // Store flattened metadata for retrieval
         metadata: JSON.stringify(flatMetadata),
       };
     });
@@ -474,7 +448,7 @@ export class RFDBServerBackend {
   /**
    * Parse a node from wire format to JS format
    */
-  private _parseNode(wireNode: WireNode): BaseNodeRecord {
+  private _parseNode(wireNode: WireNode): AnyBrandedNode {
     const metadata: Record<string, unknown> = wireNode.metadata ? JSON.parse(wireNode.metadata) : {};
 
     // Parse nested JSON strings
@@ -488,7 +462,9 @@ export class RFDBServerBackend {
       }
     }
 
-    const humanId = (metadata.originalId as string) || wireNode.id;
+    // Prefer metadata.semanticId (original v1 format preserved by RFDB server),
+    // then v3 semanticId, then v2 originalId metadata hack, then raw id
+    const humanId = (metadata.semanticId as string) || wireNode.semanticId || (metadata.originalId as string) || wireNode.id;
 
     // Exclude standard fields from metadata to prevent overwriting wireNode values
     // REG-325: Metadata spread was overwriting name with LITERAL node data
@@ -500,10 +476,11 @@ export class RFDBServerBackend {
       exported: _exported,
       nodeType: _nodeType,
       originalId: _originalId,  // Already extracted above
+      semanticId: _semanticId,  // Exclude from safeMetadata (used for humanId above)
       ...safeMetadata
     } = metadata;
 
-    return {
+    const parsed = {
       id: humanId,
       type: wireNode.nodeType,
       name: wireNode.name,
@@ -511,6 +488,9 @@ export class RFDBServerBackend {
       exported: wireNode.exported,
       ...safeMetadata,
     };
+
+    // Re-brand nodes coming from database
+    return brandNodeInternal(parsed);
   }
 
   /**
@@ -518,11 +498,18 @@ export class RFDBServerBackend {
    */
   private _parseEdge(wireEdge: WireEdge): EdgeRecord {
     const meta: Record<string, unknown> = wireEdge.metadata ? JSON.parse(wireEdge.metadata) : {};
-    // Use original string IDs if stored, otherwise use wire IDs
+    // v3: server resolves src/dst to semantic IDs, use directly
+    // v2: fall back to _origSrc/_origDst metadata hack
     const { _origSrc, _origDst, ...rest } = meta;
+    const src = this.protocolVersion >= 3
+      ? wireEdge.src
+      : (_origSrc as string) || wireEdge.src;
+    const dst = this.protocolVersion >= 3
+      ? wireEdge.dst
+      : (_origDst as string) || wireEdge.dst;
     return {
-      src: (_origSrc as string) || wireEdge.src,
-      dst: (_origDst as string) || wireEdge.dst,
+      src,
+      dst,
       type: wireEdge.edgeType,
       metadata: Object.keys(rest).length > 0 ? rest : undefined,
     };
@@ -754,6 +741,48 @@ export class RFDBServerBackend {
     }));
   }
 
+  /**
+   * Execute unified Datalog query or program.
+   * Auto-detects whether input is rules or direct query.
+   */
+  async executeDatalog(source: string): Promise<Array<{ bindings: Array<{ name: string; value: string }> }>> {
+    if (!this.client) throw new Error('Not connected');
+    const results = await this.client.executeDatalog(source);
+    return results.map(r => ({
+      bindings: Object.entries(r.bindings).map(([name, value]) => ({ name, value }))
+    }));
+  }
+
+  // ===========================================================================
+  // Batch Operations (RFD-16: CommitBatch protocol)
+  // ===========================================================================
+
+  /**
+   * Begin a batch operation. While batching, addNodes/addEdges buffer locally.
+   * Call commitBatch() to send all buffered data atomically.
+   */
+  beginBatch(): void {
+    if (!this.client) throw new Error('Not connected to RFDB server');
+    this.client.beginBatch();
+  }
+
+  /**
+   * Commit the current batch to the server atomically.
+   * Returns a CommitDelta describing what changed.
+   */
+  async commitBatch(tags?: string[]): Promise<CommitDelta> {
+    if (!this.client) throw new Error('Not connected to RFDB server');
+    return this.client.commitBatch(tags);
+  }
+
+  /**
+   * Abort the current batch, discarding all buffered data.
+   */
+  abortBatch(): void {
+    if (!this.client) throw new Error('Not connected to RFDB server');
+    this.client.abortBatch();
+  }
+
   // ===========================================================================
   // Export/Import
   // ===========================================================================

package/src/utils/findRfdbBinary.ts

@@ -12,12 +12,13 @@
  * 2. GRAFEMA_RFDB_SERVER environment variable
  * 3. Monorepo target/release (development)
  * 4. Monorepo target/debug (development)
- * 5. @grafema/rfdb npm package (prebuilt)
- * 6. ~/.local/bin/rfdb-server (user-installed)
+ * 5. System PATH lookup
+ * 6. @grafema/rfdb npm package (prebuilt)
+ * 7. ~/.local/bin/rfdb-server (user-installed)
  */
 
 import { existsSync } from 'fs';
-import { join, dirname, resolve } from 'path';
+import { join, delimiter, dirname, resolve } from 'path';
 import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
 
@@ -83,7 +84,17 @@ export function findRfdbBinary(options: FindBinaryOptions = {}): string | null {
     }
   }
 
-  // 5. @grafema/rfdb npm package
+  // 5. System PATH lookup
+  const pathDirs = (process.env.PATH || '').split(delimiter);
+  for (const dir of pathDirs) {
+    if (!dir) continue;
+    const candidate = join(dir, 'rfdb-server');
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  // 6. @grafema/rfdb npm package
   try {
     const require = createRequire(import.meta.url);
     const rfdbPkg = require.resolve('@grafema/rfdb');
@@ -97,7 +108,7 @@ export function findRfdbBinary(options: FindBinaryOptions = {}): string | null {
     // @grafema/rfdb not installed
   }
 
-  // 6. User-installed binary in ~/.local/bin
+  // 7. User-installed binary in ~/.local/bin
   const homeBinary = join(process.env.HOME || '', '.local', 'bin', 'rfdb-server');
   if (existsSync(homeBinary)) {
     return homeBinary;
@@ -147,14 +158,18 @@ Options:
 3. Set environment variable:
    export GRAFEMA_RFDB_SERVER=/path/to/rfdb-server
 
-4. Build from source and install:
+4. Install to system PATH:
+   cargo build --release
+   cp target/release/rfdb-server /usr/local/bin/
+
+5. Build from source and install:
    git clone https://github.com/Disentinel/grafema.git
    cd grafema/packages/rfdb-server
    cargo build --release
    mkdir -p ~/.local/bin
    cp target/release/rfdb-server ~/.local/bin/
 
-5. Install prebuilt (if available for your platform):
+6. Install prebuilt (if available for your platform):
    npm install @grafema/rfdb
 `;
 }

package/src/utils/moduleResolution.ts

@@ -11,7 +11,7 @@
  */
 
 import { existsSync, statSync } from 'fs';
-import { dirname, resolve, join } from 'path';
+import { dirname, extname, resolve, join } from 'path';
 
 /**
  * Default file extensions to try when resolving modules.
@@ -19,6 +19,19 @@ import { dirname, resolve, join } from 'path';
  */
 export const DEFAULT_EXTENSIONS = ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'];
 
+/**
+ * TypeScript extension redirects (REG-426).
+ * Maps JS-family extensions to their TS equivalents.
+ * Used when an import specifies a .js extension but only a .ts file exists.
+ * This matches TypeScript's own module resolution behavior for ESM.
+ */
+const TS_EXTENSION_REDIRECTS: Record<string, string[]> = {
+  '.js': ['.ts', '.tsx'],
+  '.jsx': ['.tsx'],
+  '.mjs': ['.mts'],
+  '.cjs': ['.cts'],
+};
+
 /**
  * Default index files to try when resolving directory imports.
  * Order: JS variants first (most common), then TS variants.
@@ -177,6 +190,20 @@ export function resolveModulePath(
     }
   }
 
+  // TypeScript extension redirect (REG-426):
+  // import './foo.js' → try ./foo.ts when ./foo.js doesn't exist
+  const ext = extname(normalizedPath);
+  const tsAlternatives = TS_EXTENSION_REDIRECTS[ext];
+  if (tsAlternatives) {
+    const withoutExt = normalizedPath.slice(0, -ext.length);
+    for (const tsExt of tsAlternatives) {
+      const testPath = withoutExt + tsExt;
+      if (pathExists(testPath, useFilesystem, fileIndex)) {
+        return testPath;
+      }
+    }
+  }
+
   // Try index files in directory
   for (const indexFile of indexFiles) {
     const testPath = join(normalizedPath, indexFile);