@stream44.studio/encapsulate 0.4.0-rc.28 → 0.4.0-rc.30

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stream44.studio/encapsulate",
-    "version": "0.4.0-rc.28",
+    "version": "0.4.0-rc.30",
     "license": "MIT",
     "repository": {
         "type": "git",

package/src/capsule-projectors/CapsuleModuleProjector.v0.ts

@@ -174,7 +174,7 @@ export function CapsuleModuleProjector({
                             for (const [key, potentialCapsule] of Object.entries(capsules)) {
                                 if (potentialCapsule === capsule) continue
 
-                                const mappedModulePath = potentialCapsule.cst?.source?.moduleFilepath
+                                const mappedModulePath = potentialCapsule.cst?.source?.moduleUri
 
                                 if (mappedModulePath && (
                                     mappedModulePath === mappingValue ||
@@ -224,7 +224,7 @@ export function CapsuleModuleProjector({
                                         for (const [key, potentialCapsule] of Object.entries(capsules)) {
                                             if (potentialCapsule === capsule) continue
 
-                                            const mappedModulePath = potentialCapsule.cst?.source?.moduleFilepath
+                                            const mappedModulePath = potentialCapsule.cst?.source?.moduleUri
 
                                             if (mappedModulePath && (
                                                 mappedModulePath === mappingValue ||
@@ -515,7 +515,7 @@ export function CapsuleModuleProjector({
             projectingCapsules.add(capsuleId)
         }
 
-        timing?.record(`Projector: Start projection for ${capsule.cst.source.moduleFilepath}`)
+        timing?.record(`Projector: Start projection for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}`)
 
         // Only project capsules that have the Capsule struct property
         const spineContract = capsule.cst.spineContracts[spineContractUri]
@@ -571,10 +571,10 @@ export function CapsuleModuleProjector({
                         if (allProjectedFilesExist) {
                             // Restore snapshotValues from cache
                             Object.assign(snapshotValues, merge(snapshotValues, cachedData.snapshotData))
-                            timing?.record(`Projector: Cache HIT for ${capsule.cst.source.moduleFilepath}`)
+                            timing?.record(`Projector: Cache HIT for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}`)
                             return true
                         } else {
-                            timing?.record(timing?.chalk?.yellow?.(`Projector: Cache INVALID (projected files missing) for ${capsule.cst.source.moduleFilepath}`))
+                            timing?.record(timing?.chalk?.yellow?.(`Projector: Cache INVALID (projected files missing) for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}`))
                         }
                     }
                 }
@@ -588,7 +588,7 @@ export function CapsuleModuleProjector({
 
                         // Check if this capsule has the Capsule struct (meaning it should be projected)
                         if (potentialMappedCapsule.cst?.spineContracts?.[spineContractUri]?.propertyContracts?.['#@stream44.studio/encapsulate/structs/Capsule']) {
-                            // Check if this capsule's moduleFilepath is referenced in any mapping property
+                            // Check if this capsule's moduleUri is referenced in any mapping property
                             const mappedModulePath = potentialMappedCapsule.cst.source.moduleFilepath
 
                             for (const [propContractKey, propContract] of Object.entries(spineContract.propertyContracts)) {
@@ -612,7 +612,7 @@ export function CapsuleModuleProjector({
                         }
                     }
                 }
-                timing?.record(timing?.chalk?.red?.(`Projector: Cache MISS for ${capsule.cst.source.moduleFilepath}`))
+                timing?.record(timing?.chalk?.red?.(`Projector: Cache MISS for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}`))
             } catch (error) {
                 // Cache miss or error, proceed with projection
             }
@@ -633,13 +633,13 @@ export function CapsuleModuleProjector({
 
             const cstJson = JSON.stringify(targetCapsule.cst, null, 4)
             const crtJson = JSON.stringify(targetCapsule.crt || {}, null, 4)
-            const moduleFilepath = targetCapsule.cst.source.moduleFilepath
+            const moduleUri = targetCapsule.cst.source.moduleUri
             const importStackLine = targetCapsule.cst.source.importStackLine
 
-            // Replace importMeta: import.meta with moduleFilepath: '...'
+            // Replace importMeta: import.meta with moduleFilepath: '...' (using npm URI)
             expression = expression.replace(
                 /importMeta:\s*import\.meta/g,
-                `moduleFilepath: '${moduleFilepath}'`
+                `moduleFilepath: '${moduleUri}'`
             )
 
             // Replace importStack: makeImportStack() with importStackLine: ..., crt: {...}, cst: {...}
@@ -1662,7 +1662,7 @@ ${mappedDefaultExport}
                 await projectionCacheStore.writeFile(cacheFilename, JSON.stringify(cacheData, null, 2))
             } catch (error) {
                 // Cache write error, continue without failing
-                console.warn(`Warning: Failed to write projection cache for ${capsule.cst.source.moduleFilepath}:`, error)
+                console.warn(`Warning: Failed to write projection cache for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}:`, error)
             }
         }
 
@@ -1749,7 +1749,7 @@ capsule['#'] = ${JSON.stringify(capsuleName)}
                         await projectionStore.writeFile(projectedPath, capsuleFileContent)
                     }
                 } catch (error) {
-                    console.warn(`Warning: Failed to write projection cache for capsule ${registryCapsule.cst.source.moduleFilepath}:`, error)
+                    console.warn(`Warning: Failed to write projection cache for capsule ${registryCapsule.cst.source.moduleUri || registryCapsule.cst.source.moduleFilepath}:`, error)
                 }
             }
         }

package/src/encapsulate.ts

@@ -1,7 +1,7 @@
 
 // CACHE_BUST_VERSION: Increment this whenever CST cache must be invalidated due to structural changes
 // This ensures projected capsules are regenerated when the CST format changes
-const CACHE_BUST_VERSION = 21
+const CACHE_BUST_VERSION = 22
 
 type TSpineOptions = {
     spineFilesystemRoot?: string,
@@ -505,21 +505,30 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
 
     if (typeof importStackLine !== 'number') throw new Error(`Could not determine importStackLine from options`)
 
-    const capsuleSourceLineRef = `${moduleFilepath}:${importStackLine}`
+    // Temporary filesystem-based ref used only for passing to static analyzer
+    const fsBasedRef = `${moduleFilepath}:${importStackLine}`
 
     spine.spineOptions.timing?.record(`Encapsulate: Start for ${moduleFilepath}`)
 
-    const { csts, crts } = await spine.spineOptions.staticAnalyzer?.parseModule({
+    const parseResult = await spine.spineOptions.staticAnalyzer?.parseModule({
         spineOptions: spine.spineOptions,
         encapsulateOptions: {
             moduleFilepath,
             importStackLine,
-            capsuleSourceLineRef,
+            capsuleSourceLineRef: fsBasedRef,
             capsuleName: options.capsuleName,
             ambientReferences: options.ambientReferences,
             cacheBustVersion: CACHE_BUST_VERSION
         }
-    }) || {
+    })
+
+    // Use moduleUri from static analyzer for npm URI-based capsuleSourceLineRef
+    const moduleUri = parseResult?.moduleUri
+    const capsuleSourceLineRef = moduleUri
+        ? `${moduleUri}:${importStackLine}`
+        : fsBasedRef
+
+    const { csts, crts } = parseResult || {
         csts: options.cst ? { [capsuleSourceLineRef]: options.cst } : undefined,
         crts: options.crt ? { [capsuleSourceLineRef]: options.crt } : undefined
     }
@@ -722,12 +731,20 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 const ownSelf = merge({}, defaultInstance, defaultPropertyValues, ...Object.values(mergedValuesByContract))
 
                 // Convert relative paths to absolute for metadata exposure
+                // When a CST exists with a source moduleFilepath, use it to derive the absolute path.
+                // This ensures that projected capsules (loaded from .~o/encapsulate.dev/caps/...)
+                // still expose the original source filepath, not the projected filepath.
+                const originalAbsoluteModuleFilepath = cst?.source?.moduleFilepath
+                    ? (cst.source.moduleFilepath.startsWith('/')
+                        ? cst.source.moduleFilepath
+                        : join(spine.spineOptions.spineFilesystemRoot || '', cst.source.moduleFilepath))
+                    : absoluteModuleFilepath
                 const absoluteCapsuleSourceLineRef = `${absoluteModuleFilepath}:${importStackLine}`
                 const capsuleMetadataStruct: Record<string, any> = {
                     capsuleName: encapsulateOptions.capsuleName,
                     capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
                     capsuleSourceNameRefHash: cst?.capsuleSourceNameRefHash,
-                    moduleFilepath: absoluteModuleFilepath,
+                    moduleFilepath: originalAbsoluteModuleFilepath,
                     // Root capsule metadata will be populated after extends chain is resolved
                     rootCapsule: {
                         capsuleName: undefined as string | undefined,
@@ -845,7 +862,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 const resolvedRootCapsule = rootCapsule || {
                     capsuleName: encapsulateOptions.capsuleName!,
                     capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
-                    moduleFilepath: absoluteModuleFilepath
+                    moduleFilepath: originalAbsoluteModuleFilepath
                 }
                 capsuleMetadataStruct.rootCapsule.capsuleName = resolvedRootCapsule.capsuleName
                 capsuleMetadataStruct.rootCapsule.capsuleSourceLineRef = resolvedRootCapsule.capsuleSourceLineRef

package/src/spine-contracts/CapsuleSpineContract.v0/Membrane.v0.ts

@@ -1,5 +1,7 @@
 import { CapsulePropertyTypes } from "../../encapsulate"
 import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static.v0"
+import { readFileSync, existsSync } from "node:fs"
+import { dirname, relative, join } from "node:path"
 
 type CallerContext = {
     capsuleSourceLineRef: string
@@ -8,9 +10,9 @@ type CallerContext = {
     capsuleSourceNameRefHash?: string
     capsuleSourceUriLineRefInstanceId?: string
     prop?: string
-    filepath?: string
+    fileUri?: string
     line?: number
-    stack?: Array<{ function?: string, filepath?: string, line?: number, column?: number }>
+    stack?: Array<{ function?: string, fileUri?: string, line?: number, column?: number }>
 }
 
 function CapsuleMembrane(target: Record<string, any>, hooks?: {
@@ -140,11 +142,16 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
 
         // delegateOptions is set by encapsulate.ts for property contract delegates
         // options can be a function or an object for regular mappings
-        // Always pass { self, constants } - self is populated when depends is specified, empty otherwise
+        // Always pass { self, constants } - self contains full parent self when depends is specified,
+        // otherwise just the Capsule metadata struct (moduleFilepath, capsuleName, etc.)
         const optionsFn = property.definition.options
+        const capsuleStructKey = '#@stream44.studio/encapsulate/structs/Capsule'
+        const minimalSelf = this.self[capsuleStructKey]
+            ? { [capsuleStructKey]: this.self[capsuleStructKey] }
+            : {}
         const mappingOptions = property.definition.delegateOptions
             || (typeof optionsFn === 'function'
-                ? await optionsFn({ self: property.definition.depends ? this.self : {}, constants })
+                ? await optionsFn({ self: property.definition.depends ? this.self : minimalSelf, constants })
                 : optionsFn)
 
         // Check for existing instance in registry - reuse if available (regardless of options)
@@ -180,7 +187,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                                         const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
                                         if (stackFrames.length > 0) {
                                             const callerInfo = extractCallerInfo(stackFrames, 3)
-                                            callerCtx.filepath = callerInfo.filepath
+                                            callerCtx.fileUri = callerInfo.fileUri
                                             callerCtx.line = callerInfo.line
                                             callerCtx.stack = stackFrames
                                         }
@@ -307,7 +314,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                             const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
                             if (stackFrames.length > 0) {
                                 const callerInfo = extractCallerInfo(stackFrames, 3)
-                                callerCtx.filepath = callerInfo.filepath
+                                callerCtx.fileUri = callerInfo.fileUri
                                 callerCtx.line = callerInfo.line
                                 callerCtx.stack = stackFrames
                             }
@@ -370,7 +377,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                                         const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
                                         if (stackFrames.length > 0) {
                                             const callerInfo = extractCallerInfo(stackFrames, 3)
-                                            callerCtx.filepath = callerInfo.filepath
+                                            callerCtx.fileUri = callerInfo.fileUri
                                             callerCtx.line = callerInfo.line
                                             callerCtx.stack = stackFrames
                                         }
@@ -873,8 +880,8 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
             if (callerCtx.prop) {
                 event.caller.prop = callerCtx.prop
             }
-            if (callerCtx.filepath) {
-                event.caller.filepath = callerCtx.filepath
+            if (callerCtx.fileUri) {
+                event.caller.fileUri = callerCtx.fileUri
             }
             if (callerCtx.line) {
                 event.caller.line = callerCtx.line
@@ -970,9 +977,62 @@ CapsuleSpineContract['#'] = '@stream44.studio/encapsulate/spine-contracts/Capsul
 
 
 
-function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Array<{ function?: string, filepath?: string, line?: number, column?: number }> {
+// Cache for synchronous npm URI lookups (directory -> package name or null)
+const npmUriCache = new Map<string, string | null>()
+
+function constructNpmUriSync(absoluteFilepath: string): string | null {
+    // Check for /node_modules/ in the path — use the last occurrence to handle nested node_modules
+    const nodeModulesMarker = '/node_modules/'
+    const lastIdx = absoluteFilepath.lastIndexOf(nodeModulesMarker)
+    if (lastIdx !== -1) {
+        return absoluteFilepath.substring(lastIdx + nodeModulesMarker.length)
+    }
+
+    let currentDir = dirname(absoluteFilepath)
+    const maxDepth = 20
+
+    for (let i = 0; i < maxDepth; i++) {
+        if (npmUriCache.has(currentDir)) {
+            const cachedName = npmUriCache.get(currentDir)
+            if (cachedName) {
+                const relativeFromPackage = relative(currentDir, absoluteFilepath)
+                return `${cachedName}/${relativeFromPackage}`
+            }
+            // null means no package.json with name found at this level, continue up
+            const parentDir = dirname(currentDir)
+            if (parentDir === currentDir) break
+            currentDir = parentDir
+            continue
+        }
+
+        const packageJsonPath = join(currentDir, 'package.json')
+        try {
+            if (existsSync(packageJsonPath)) {
+                const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+                const packageName = packageJson.name
+                npmUriCache.set(currentDir, packageName || null)
+                if (packageName) {
+                    const relativeFromPackage = relative(currentDir, absoluteFilepath)
+                    return `${packageName}/${relativeFromPackage}`
+                }
+            } else {
+                npmUriCache.set(currentDir, null)
+            }
+        } catch {
+            npmUriCache.set(currentDir, null)
+        }
+
+        const parentDir = dirname(currentDir)
+        if (parentDir === currentDir) break
+        currentDir = parentDir
+    }
+
+    return null
+}
+
+function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Array<{ function?: string, fileUri?: string, line?: number, column?: number }> {
     const lines = stack.split('\n')
-    const result: Array<{ function?: string, filepath?: string, line?: number, column?: number }> = []
+    const result: Array<{ function?: string, fileUri?: string, line?: number, column?: number }> = []
 
     // Skip first line (Error message), then collect ALL frames
     for (let i = 1; i < lines.length; i++) {
@@ -984,9 +1044,11 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
         // "at functionName (file:line:column)"
         const match = line.match(/at\s+(.+)/)
         if (match) {
-            const frame: { function?: string, filepath?: string, line?: number, column?: number } = {}
+            const frame: { function?: string, fileUri?: string, line?: number, column?: number } = {}
             const content = match[1]
 
+            let rawFilepath: string | undefined
+
             // Try to extract function name and location
             const funcMatch = content.match(/^(.+?)\s+\((.+)\)$/)
             if (funcMatch) {
@@ -999,7 +1061,7 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
                 const location = funcMatch[2]
                 const locMatch = location.match(/^(.+):(\d+):(\d+)$/)
                 if (locMatch) {
-                    frame.filepath = locMatch[1]
+                    rawFilepath = locMatch[1]
                     frame.line = parseInt(locMatch[2], 10)
                     frame.column = parseInt(locMatch[3], 10)
                 }
@@ -1007,25 +1069,32 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
                 // No function name: "/path/to/file:line:column"
                 const locMatch = content.match(/^(.+):(\d+):(\d+)$/)
                 if (locMatch) {
-                    frame.filepath = locMatch[1]
+                    rawFilepath = locMatch[1]
                     frame.line = parseInt(locMatch[2], 10)
                     frame.column = parseInt(locMatch[3], 10)
                 }
             }
 
-            // Convert absolute paths to relative paths if spineFilesystemRoot is provided
-            if (frame.filepath && spineFilesystemRoot) {
-                if (frame.filepath.startsWith(spineFilesystemRoot)) {
-                    frame.filepath = frame.filepath.slice(spineFilesystemRoot.length)
-                    // Remove leading slash if present
-                    if (frame.filepath.startsWith('/')) {
-                        frame.filepath = frame.filepath.slice(1)
+            // Convert absolute filepaths to npm URIs
+            if (rawFilepath) {
+                const npmUri = constructNpmUriSync(rawFilepath)
+                if (npmUri) {
+                    // Strip file extension from URI for consistency
+                    frame.fileUri = npmUri.replace(/\.(ts|tsx|js|jsx)$/, '')
+                } else if (spineFilesystemRoot && rawFilepath.startsWith(spineFilesystemRoot)) {
+                    // Fallback: use relative path from spine root if npm URI not resolvable
+                    let relativePath = rawFilepath.slice(spineFilesystemRoot.length)
+                    if (relativePath.startsWith('/')) {
+                        relativePath = relativePath.slice(1)
                     }
+                    frame.fileUri = relativePath
+                } else {
+                    frame.fileUri = rawFilepath
                 }
             }
 
             // Include all frames, even if incomplete
-            if (frame.filepath || frame.function) {
+            if (frame.fileUri || frame.function) {
                 result.push(frame)
             }
         }
@@ -1033,14 +1102,14 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
     return result
 }
 
-function extractCallerInfo(stack: Array<{ function?: string, filepath?: string, line?: number, column?: number }>, offset: number = 0) {
+function extractCallerInfo(stack: Array<{ function?: string, fileUri?: string, line?: number, column?: number }>, offset: number = 0) {
     // Use offset to skip frames in the stack
     // offset 0 = first frame, offset 1 = second frame, etc.
 
     if (offset < stack.length) {
         const frame = stack[offset]
         return {
-            filepath: frame.filepath,
+            fileUri: frame.fileUri,
             line: frame.line
         }
     }
@@ -1048,7 +1117,7 @@ function extractCallerInfo(stack: Array<{ function?: string, filepath?: string,
     // Fallback to first frame if offset is out of bounds
     if (stack.length > 0) {
         return {
-            filepath: stack[0].filepath,
+            fileUri: stack[0].fileUri,
             line: stack[0].line
         }
     }

package/src/spine-contracts/CapsuleSpineContract.v0/README.md

@@ -308,8 +308,8 @@ prop: {
 - **`options`** — forwarded to the mapped capsule. Keys starting with `'#'` target the mapped capsule's own property contracts. Keys without `'#'` are matched against capsule names deeper in the mapping tree (nested capsule-name-targeted options).
 - **`options({ self, constants })`** — when `options` is a function, it receives `{ self, constants }`.
   - `constants` — all `Literal`/`String` values from the mapped capsule's definition.
-  - `self` — the parent capsule's `self` object with resolved sibling mappings. Only populated when `depends` is specified (empty `{}` otherwise).
-- **`depends`** — array of sibling property names that must be resolved before this mapping's `options` function runs. Enables `options({ self })` to access already-resolved siblings (e.g. `self.$auth.realm`) and the Capsule metadata struct (e.g. `self['#@stream44.studio/encapsulate/structs/Capsule'].capsuleName`). Can be declared explicitly or auto-injected by the static analyzer when it detects `self.<name>` references in the options function body.
+  - `self` — always contains the Capsule metadata struct (`self['#@stream44.studio/encapsulate/structs/Capsule']` with `moduleFilepath`, `capsuleName`, etc.). When `depends` is specified, `self` also contains the full parent capsule's resolved sibling mappings.
+- **`depends`** — array of sibling property names that must be resolved before this mapping's `options` function runs. Enables `options({ self })` to access already-resolved siblings (e.g. `self.$auth.realm`). Can be declared explicitly or auto-injected by the static analyzer when it detects `self.<name>` references in the options function body.
 - **Instance reuse** — named capsules are registered in an instance registry. If a capsule with the same name is mapped multiple times without options, the existing instance is reused via a deferred proxy.
 
 Mapped capsules are accessible via `this.<prop>` (unwrapped API) and `api.<prop>` (raw instance with `.api`).
@@ -397,7 +397,7 @@ Both implement the same property mapping logic. The difference is observability.
 | `call` | Function invoked | `{ target, args, eventIndex }` |
 | `call-result` | Function returns | `{ target, result, callEventIndex }` |
 
-Events include `caller` context (source capsule, property, filepath, line) when `enableCallerStackInference` is enabled. Memoized results are tagged with `memoized: true`.
+Events include `caller` context (source capsule, property, fileUri, line) when `enableCallerStackInference` is enabled. Memoized results are tagged with `memoized: true`.
 
 ### SpineRuntime & run()
 

package/src/spine-contracts/CapsuleSpineContract.v0/Static.v0.ts

@@ -129,8 +129,9 @@ export class ContractCapsuleInstanceFactory {
             if (!this.spineFilesystemRoot) throw new Error(`'spineFilesystemRoot' not set!`)
             if (!this.importCapsule) throw new Error(`'importCapsule' not set!`)
 
-            // Use encapsulateOptions.moduleFilepath (always available) instead of cst.source.moduleFilepath
-            const moduleFilepath = this.capsule.encapsulateOptions?.moduleFilepath || this.capsule.cst?.source?.moduleFilepath
+            // Use cst.source.moduleFilepath (always filesystem-relative) for path resolution.
+            // encapsulateOptions.moduleFilepath may be an npm URI when loaded from projected files.
+            const moduleFilepath = this.capsule.cst?.source?.moduleFilepath || this.capsule.encapsulateOptions?.moduleFilepath
             if (!moduleFilepath) throw new Error(`'moduleFilepath' not available on capsule!`)
 
             const parentPath = join(this.spineFilesystemRoot, moduleFilepath)
@@ -197,11 +198,16 @@ export class ContractCapsuleInstanceFactory {
 
         // delegateOptions is set by encapsulate.ts for property contract delegates
         // options can be a function or an object for regular mappings
-        // Always pass { self, constants } - self is populated when depends is specified, empty otherwise
+        // Always pass { self, constants } - self contains full parent self when depends is specified,
+        // otherwise just the Capsule metadata struct (moduleFilepath, capsuleName, etc.)
         const optionsFn = property.definition.options
+        const capsuleStructKey = '#@stream44.studio/encapsulate/structs/Capsule'
+        const minimalSelf = this.self[capsuleStructKey]
+            ? { [capsuleStructKey]: this.self[capsuleStructKey] }
+            : {}
         const mappingOptions = property.definition.delegateOptions
             || (typeof optionsFn === 'function'
-                ? await optionsFn({ self: property.definition.depends ? this.self : {}, constants })
+                ? await optionsFn({ self: property.definition.depends ? this.self : minimalSelf, constants })
                 : optionsFn)
 
         // Check for existing instance in registry - reuse if available when no options

package/src/static-analyzer.v0.ts

@@ -244,25 +244,13 @@ export function StaticAnalyzer({
 
             const moduleFilepath = join(spineOptions.spineFilesystemRoot, encapsulateOptions.moduleFilepath)
 
-            // Determine the cache file path based on whether the module is external or internal
-            let cacheFilePath: string
-            const isExternal = encapsulateOptions.moduleFilepath.startsWith('../')
-            const hasNodeModules = encapsulateOptions.moduleFilepath.includes('node_modules/')
-
-            if (isExternal || hasNodeModules) {
-                // External module or node_modules path - construct npm URI
-                const npmUri = await constructNpmUri(moduleFilepath, spineOptions.spineFilesystemRoot)
-                if (npmUri) {
-                    // Prefix with o/npmjs.com/node_modules/ for external modules
-                    cacheFilePath = `o/npmjs.com/node_modules/${npmUri}`
-                } else {
-                    // Fallback to normalized path if npm URI construction fails
-                    cacheFilePath = normalize(encapsulateOptions.moduleFilepath).replace(/^\.\.\//, '').replace(/\.\.\//g, '')
-                }
-            } else {
-                // Internal module - use relative path as-is
-                cacheFilePath = encapsulateOptions.moduleFilepath
-            }
+            // Construct npm URI for the module upfront — used for cache paths and CST keys
+            const rawModuleUri: string = await constructNpmUri(moduleFilepath, spineOptions.spineFilesystemRoot) || encapsulateOptions.moduleFilepath
+            // Strip file extension from URI
+            const moduleUriWithoutExt = rawModuleUri.replace(/\.(ts|tsx|js|jsx)$/, '')
+
+            // Cache file path always uses npm URI (never filesystem-relative paths)
+            const cacheFilePath = moduleUriWithoutExt
 
             const capsuleSourceLineRef = `${cacheFilePath}:${encapsulateOptions.importStackLine}`
 
@@ -297,7 +285,8 @@ export function StaticAnalyzer({
                                 timing?.record(`StaticAnalyzer: Cache HIT for ${encapsulateOptions.moduleFilepath}`)
                                 return {
                                     csts: cachedCsts,
-                                    crts: JSON.parse(crtsContent)
+                                    crts: JSON.parse(crtsContent),
+                                    moduleUri: moduleUriWithoutExt
                                 }
                             }
                         }
@@ -369,24 +358,12 @@ export function StaticAnalyzer({
                         continue
                     }
 
-                    const capsuleSourceLineRef = `${encapsulateOptions.moduleFilepath}:${encapsulateOptions.importStackLine}`
-                    const capsuleSourceNameRef = encapsulateOptions.capsuleName && `${encapsulateOptions.moduleFilepath}:${encapsulateOptions.capsuleName}`
+                    // Use npm URI for all CST references (never filesystem-relative paths)
+                    const capsuleSourceLineRef = `${moduleUriWithoutExt}:${encapsulateOptions.importStackLine}`
+                    const capsuleSourceNameRef = encapsulateOptions.capsuleName && `${moduleUriWithoutExt}:${encapsulateOptions.capsuleName}`
                     const capsuleSourceNameRefHash = capsuleSourceNameRef && createHash('sha256').update(capsuleSourceNameRef).digest('hex')
 
-                    // Construct npm URI for the module - try for all modules
-                    let moduleUri: string | null = await constructNpmUri(moduleFilepath, spineOptions.spineFilesystemRoot)
-
-                    // If npm URI construction failed, fall back to moduleFilepath
-                    if (!moduleUri) {
-                        moduleUri = encapsulateOptions.moduleFilepath
-                    }
-
-                    // Strip file extension from URI
-                    const moduleUriWithoutExt = moduleUri.replace(/\.(ts|tsx|js|jsx)$/, '')
-                    const capsuleSourceUriLineRef = `${moduleUriWithoutExt}:${encapsulateOptions.importStackLine}`
-
-                    // Store moduleUri without extension
-                    moduleUri = moduleUriWithoutExt
+                    const capsuleSourceUriLineRef = capsuleSourceLineRef
 
                     // Extract the capsule expression text from the source
                     const capsuleExpression = call.getText(sourceFile)
@@ -407,7 +384,7 @@ export function StaticAnalyzer({
                         capsuleSourceUriLineRef,
                         source: {
                             moduleFilepath: encapsulateOptions.moduleFilepath,
-                            moduleUri,
+                            moduleUri: moduleUriWithoutExt,
                             capsuleName: encapsulateOptions.capsuleName,
                             declarationLine,
                             importStackLine: encapsulateOptions.importStackLine,
@@ -760,6 +737,7 @@ export function StaticAnalyzer({
             return {
                 csts,
                 crts,
+                moduleUri: moduleUriWithoutExt
             }
         }
     }
@@ -1028,7 +1006,7 @@ function extractModuleLocalCode(
         if (funcDecl) {
             // Analyze the function to see if it's self-contained
             const dependencies = new Set<string>()
-            const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies)
+            const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies, moduleLocalVariables)
 
             if (isContained) {
                 // Mark this as module-local in ambient references
@@ -1056,9 +1034,33 @@ function extractModuleLocalCode(
                 // Collect the main function
                 collectFunction(name)
 
-                // Collect all dependencies
+                // Collect all dependencies (functions and variables)
                 for (const dep of dependencies) {
                     collectFunction(dep)
+
+                    // Also collect module-local variable dependencies
+                    const depVarDecl = moduleLocalVariables.get(dep)
+                    if (depVarDecl && !processed.has(dep)) {
+                        processed.add(dep)
+                        const varStatement = depVarDecl.parent?.parent
+                        if (varStatement && ts.isVariableStatement(varStatement)) {
+                            const varCode = varStatement.getText(sourceFile)
+                            collectedCode.push(varCode)
+                            if (!moduleLocalCode[dep]) {
+                                moduleLocalCode[dep] = varCode
+                            }
+                        }
+                        // Mark the variable dependency in ambient references
+                        if (!ambientReferences[dep]) {
+                            ambientReferences[dep] = { type: 'module-local' }
+                        }
+                        // Recursively collect transitive variable dependencies
+                        collectTransitiveVariableDependencies(
+                            depVarDecl, sourceFile, importMap, assignmentMap,
+                            moduleLocalFunctions, moduleLocalVariables,
+                            ambientReferences, moduleLocalCode
+                        )
+                    }
                 }
 
                 // Store the collected code (main function with all dependencies)
@@ -1109,7 +1111,7 @@ function extractModuleLocalCode(
 
         // Analyze if it's self-contained
         const dependencies = new Set<string>()
-        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies)
+        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies, moduleLocalVariables)
 
         if (isContained) {
             // Add this function to moduleLocalCode
@@ -1236,14 +1238,15 @@ function collectTransitiveVariableDependencies(
     visit(varDecl.initializer)
 }
 
-// Analyze if a function is self-contained (only depends on other module-local functions or builtins)
+// Analyze if a function is self-contained (only depends on other module-local functions, variables, or builtins)
 function analyzeFunctionDependencies(
     funcDecl: ts.FunctionDeclaration,
     sourceFile: ts.SourceFile,
     importMap: Map<string, { importSpecifier: string, moduleUri: string }>,
     assignmentMap: Map<string, { importSpecifier: string, moduleUri: string }>,
     moduleLocalFunctions: Map<string, ts.FunctionDeclaration>,
-    dependencies: Set<string>
+    dependencies: Set<string>,
+    moduleLocalVariables?: Map<string, ts.VariableDeclaration>
 ): boolean {
     const localIdentifiers = new Set<string>()
     const nestedFunctionScopes = new Map<ts.Node, Set<string>>()
@@ -1370,6 +1373,12 @@ function analyzeFunctionDependencies(
                 return
             }
 
+            // Check if it's a module-local variable - add as dependency
+            if (moduleLocalVariables?.has(identifierName)) {
+                dependencies.add(identifierName)
+                return
+            }
+
             // Check if it's a module-global builtin - allowed
             if (MODULE_GLOBAL_BUILTINS.has(identifierName)) {
                 return
@@ -1703,7 +1712,7 @@ function extractCapsuleAmbientReferences(
                     if (funcDecl) {
                         // Analyze if it's self-contained
                         const dependencies = new Set<string>()
-                        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies)
+                        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies, moduleLocalVariables)
 
                         if (isContained) {
                             // Mark as module-local
@@ -1711,7 +1720,7 @@ function extractCapsuleAmbientReferences(
                                 type: 'module-local'
                             }
 
-                            // Add import dependencies from the function's body
+                            // Add import/variable dependencies from the function's body
                             for (const depName of dependencies) {
                                 if (!ambientRefs[depName]) {
                                     const depImportInfo = importMap.get(depName)
@@ -1729,6 +1738,14 @@ function extractCapsuleAmbientReferences(
                                                 importSpecifier: depAssignmentInfo.importSpecifier,
                                                 moduleUri: depAssignmentInfo.moduleUri
                                             }
+                                        } else if (moduleLocalVariables.has(depName)) {
+                                            ambientRefs[depName] = {
+                                                type: 'module-local'
+                                            }
+                                        } else if (moduleLocalFunctions.has(depName)) {
+                                            ambientRefs[depName] = {
+                                                type: 'module-local'
+                                            }
                                         }
                                     }
                                 }
@@ -2075,7 +2092,7 @@ function extractAndValidateAmbientReferences(
                     if (funcDecl) {
                         // Analyze if it's self-contained
                         const dependencies = new Set<string>()
-                        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies)
+                        const isContained = analyzeFunctionDependencies(funcDecl, sourceFile, importMap, assignmentMap, moduleLocalFunctions, dependencies, moduleLocalVariables)
 
                         if (isContained) {
                             // Mark as module-local
@@ -2083,7 +2100,7 @@ function extractAndValidateAmbientReferences(
                                 type: 'module-local'
                             }
 
-                            // Add import dependencies from the function's body
+                            // Add import/variable dependencies from the function's body
                             for (const depName of dependencies) {
                                 if (!ambientRefs[depName]) {
                                     const depImportInfo = importMap.get(depName)
@@ -2101,6 +2118,14 @@ function extractAndValidateAmbientReferences(
                                                 importSpecifier: depAssignmentInfo.importSpecifier,
                                                 moduleUri: depAssignmentInfo.moduleUri
                                             }
+                                        } else if (moduleLocalVariables.has(depName)) {
+                                            ambientRefs[depName] = {
+                                                type: 'module-local'
+                                            }
+                                        } else if (moduleLocalFunctions.has(depName)) {
+                                            ambientRefs[depName] = {
+                                                type: 'module-local'
+                                            }
                                         }
                                     }
                                 }