@stream44.studio/encapsulate 0.4.0-rc.22 → 0.4.0-rc.24

package/README.md

@@ -3,6 +3,7 @@
     <td><a href="https://Stream44.Studio"><img src=".o/stream44.studio/assets/Icon-v1.svg" width="42" height="42"></a></td>
     <td><strong><a href="https://Stream44.Studio">Stream44 Studio</a></strong><br/>Open Development Project</td>
     <td>Preview release for community feedback.<br/>Get in touch on <a href="https://discord.gg/9eBcQXEJAN">discord</a>.</td>
+    <td>Hand Designed<br/><b>AI Coded Alpha</a></td>
   </tr>
 </table>
 
@@ -16,6 +17,7 @@ An *experimental* implementation of the [PrivateData.Space](https://privatedata.
 ***NOTE:** Not intended for direct use until it matures in light of the projects below.*
 
 It is being used to underpin:
+- [Framespace Genesis](https://github.com/Stream44/FramespaceGenesis) - Modeling engine with realtime interactive visualization
 - [t44](https://github.com/Stream44/t44) - A web3 + AI ready workspace
 - [Stream44.Studio](https://stream44.studio) - A **full-stack IDE** for building **embodied distributed systems**
 
@@ -44,7 +46,6 @@ The capsule spine contract is implemented here: [src/spine-contracts/CapsuleSpin
 
 ![Capsule Spine Contract Overview](./src/spine-contracts/CapsuleSpineContract.v0/Overview.svg)
 
-
 Provenance
 ===
 

package/package.json

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

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

@@ -28,8 +28,11 @@ function safeCapsuleName(name: string) {
  * @returns The cache file path to use
  */
 async function constructCacheFilePath(moduleFilepath: string, importStackLine: number, spineFilesystemRoot: string): Promise<string> {
-    if (moduleFilepath.startsWith('../')) {
-        // External module - construct npm URI
+    const isExternal = moduleFilepath.startsWith('../')
+    const hasNodeModules = moduleFilepath.includes('node_modules/')
+
+    if (isExternal || hasNodeModules) {
+        // External module or node_modules path - construct npm URI
         const absoluteFilepath = join(spineFilesystemRoot, moduleFilepath)
         const npmUri = await constructNpmUriForCache(absoluteFilepath, spineFilesystemRoot)
         if (npmUri) {
@@ -100,6 +103,7 @@ export function CapsuleModuleProjector({
     projectionStore,
     projectionCacheStore,
     spineFilesystemRoot,
+    capsuleModuleProjectionRoot,
     capsuleModuleProjectionPackage,
     timing
 }: {
@@ -117,6 +121,7 @@ export function CapsuleModuleProjector({
         getStats?: (filepath: string) => Promise<{ mtime: Date } | null>
     },
     spineFilesystemRoot: string,
+    capsuleModuleProjectionRoot?: string,
     capsuleModuleProjectionPackage?: string,
     timing?: { record: (step: string) => void, chalk?: any }
 }) {
@@ -736,6 +741,18 @@ export function CapsuleModuleProjector({
             delete ambientReferences['makeImportStack']
         }
 
+        // Compute the relative path from the projected caps file directory
+        // back to the original source file directory so that relative imports
+        // in the caps file resolve to the original source location.
+        const absSourceDir = dirname(join(spineFilesystemRoot, capsule.cst.source.moduleFilepath))
+        const projectionRoot = capsuleModuleProjectionRoot || spineFilesystemRoot
+        const absCapsDir = dirname(join(projectionRoot, filepath))
+        const capsToSourcePrefix = relative(absCapsDir, absSourceDir)
+        function rewriteRelativeModuleUri(moduleUri: string): string {
+            if (!moduleUri.startsWith('./') && !moduleUri.startsWith('../')) return moduleUri
+            return capsToSourcePrefix + '/' + moduleUri.replace(/^\.\//, '')
+        }
+
         const importStatements = Object.entries(ambientReferences)
             .map(([name, ref]: [string, any]) => {
                 if (ref.type === 'import') {
@@ -745,7 +762,7 @@ export function CapsuleModuleProjector({
                         const cssPath = cssImportMapping[ref.moduleUri] || ref.moduleUri
                         return `import '${cssPath}'`
                     }
-                    return `import ${ref.importSpecifier} from '${ref.moduleUri}'`
+                    return `import ${ref.importSpecifier} from '${rewriteRelativeModuleUri(ref.moduleUri)}'`
                 }
                 if (ref.type === 'assigned') {
                     // If the assignment comes from a spine-factory module, import from encapsulate.ts instead

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 = 18
+const CACHE_BUST_VERSION = 21
 
 type TSpineOptions = {
     spineFilesystemRoot?: string,
@@ -53,7 +53,9 @@ type TCapsuleMakeInstanceOptions = {
         capsuleName: string,
         capsuleSourceLineRef: string,
         moduleFilepath: string
-    }
+    },
+    parentCapsuleSourceUriLineRefInstanceId?: string,
+    sit?: { capsuleInstances: Record<string, { capsuleName: string, capsuleSourceUriLineRef: string, parentCapsuleSourceUriLineRefInstanceId: string }> }
 }
 
 type TCapsule = {
@@ -552,7 +554,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
         encapsulateOptions,
         cst,
         crt: crts?.[capsuleSourceLineRef],
-        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts, sharedSelf, rootCapsule }: TCapsuleMakeInstanceOptions = {}) => {
+        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts, sharedSelf, rootCapsule, parentCapsuleSourceUriLineRefInstanceId, sit }: TCapsuleMakeInstanceOptions = {}) => {
 
             // Create cache key based on parameters
             // When sharedSelf is provided, we must NOT cache because each extending capsule
@@ -811,8 +813,27 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                             capsuleName: encapsulateOptions.capsuleName!,
                             capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
                             moduleFilepath: absoluteModuleFilepath
-                        }
+                        },
+                        parentCapsuleSourceUriLineRefInstanceId: parentCapsuleSourceUriLineRefInstanceId
+                            ? sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + (cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef))
+                            : sha256(cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef),
+                        sit
                     })
+
+                    // Propagate this (child) capsule's encapsulatedApi to all parent spine contract
+                    // instances up the extends chain, so parent functions can resolve child Function
+                    // properties via this (e.g. Engine.mergeNode calling this._mergeNode from QueryAPI).
+                    // Each ancestor accumulates child APIs so the proxy can check all levels.
+                    let ancestor = extendedCapsuleInstance
+                    while (ancestor) {
+                        for (const sci of Object.values(ancestor.spineContractCapsuleInstances || {})) {
+                            if (!(sci as any).childEncapsulatedApis) {
+                                (sci as any).childEncapsulatedApis = []
+                            }
+                            ; (sci as any).childEncapsulatedApis.push(encapsulatedApi)
+                        }
+                        ancestor = ancestor.extendedCapsuleInstance
+                    }
                 }
 
                 // Resolve the root capsule for this instance:
@@ -827,6 +848,23 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 capsuleMetadataStruct.rootCapsule.capsuleSourceLineRef = resolvedRootCapsule.capsuleSourceLineRef
                 capsuleMetadataStruct.rootCapsule.moduleFilepath = resolvedRootCapsule.moduleFilepath
 
+                // Compute deterministic instance ID:
+                //   root:  sha256(capsuleSourceUriLineRef)
+                //   child: sha256(parentCapsuleSourceUriLineRefInstanceId + ":" + capsuleSourceUriLineRef)
+                const capsuleSourceUriLineRef = cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef
+                const capsuleSourceUriLineRefInstanceId = parentCapsuleSourceUriLineRefInstanceId
+                    ? sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + capsuleSourceUriLineRef)
+                    : sha256(capsuleSourceUriLineRef)
+
+                // Register this instance in the sit structure if provided
+                if (sit) {
+                    sit.capsuleInstances[capsuleSourceUriLineRefInstanceId] = {
+                        capsuleName: encapsulateOptions.capsuleName || '',
+                        capsuleSourceUriLineRef,
+                        parentCapsuleSourceUriLineRefInstanceId: parentCapsuleSourceUriLineRefInstanceId || ''
+                    }
+                }
+
                 const capsuleInstance: any = {
                     api: encapsulatedApi,
                     spineContractCapsuleInstances,
@@ -836,7 +874,11 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     initFunctions: [] as Array<() => any>,
                     disposeFunctions: [] as Array<() => any>,
                     mappedCapsuleInstances: [] as Array<any>,
-                    rootCapsule: resolvedRootCapsule
+                    rootCapsule: resolvedRootCapsule,
+                    capsuleSourceUriLineRefInstanceId,
+                    capsuleName: encapsulateOptions.capsuleName,
+                    capsuleSourceUriLineRef,
+                    sit
                 }
 
                 // Set capsule metadata struct on self early so it's available in options() callbacks during mapping
@@ -1062,6 +1104,17 @@ function relative(from: string, to: string): string {
     return result || '.'
 }
 
+function sha256(input: string): string {
+    // Use Bun's native hasher for speed; falls back to Node crypto
+    if (typeof globalThis.Bun !== 'undefined') {
+        const hasher = new globalThis.Bun.CryptoHasher('sha256')
+        hasher.update(input)
+        return hasher.digest('hex') as string
+    }
+    const { createHash } = require('crypto')
+    return createHash('sha256').update(input).digest('hex')
+}
+
 function isObject(item: any): boolean {
     if (!item || typeof item !== 'object' || Array.isArray(item)) return false
     // Only deep-merge plain objects — preserve instances like Map, Set, Date, etc.

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

@@ -6,6 +6,7 @@ type CallerContext = {
     capsuleSourceNameRef?: string
     spineContractCapsuleInstanceId: string
     capsuleSourceNameRefHash?: string
+    capsuleSourceUriLineRefInstanceId?: string
     prop?: string
     filepath?: string
     line?: number
@@ -53,7 +54,8 @@ function CapsuleMembrane(target: Record<string, any>, hooks?: {
 class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFactory {
     private getEventIndex: () => number
     private incrementEventIndex: () => number
-    private currentCallerContext: CallerContext | undefined
+    private getCurrentCallerContext: () => CallerContext | undefined
+    private setCurrentCallerContext: (ctx: CallerContext | undefined) => void
     private onMembraneEvent?: (event: any) => void
     private enableCallerStackInference: boolean
     private encapsulateOptions: any
@@ -77,7 +79,8 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         encapsulateOptions,
         getEventIndex,
         incrementEventIndex,
-        currentCallerContext,
+        getCurrentCallerContext,
+        setCurrentCallerContext,
         runtimeSpineContracts,
         instanceRegistry,
         extendedCapsuleInstance,
@@ -97,7 +100,8 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         encapsulateOptions: any
         getEventIndex: () => number
         incrementEventIndex: () => number
-        currentCallerContext?: CallerContext
+        getCurrentCallerContext: () => CallerContext | undefined
+        setCurrentCallerContext: (ctx: CallerContext | undefined) => void
         runtimeSpineContracts?: Record<string, any>
         instanceRegistry?: CapsuleInstanceRegistry
         extendedCapsuleInstance?: any
@@ -106,7 +110,8 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         super({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance, capsuleInstance })
         this.getEventIndex = getEventIndex
         this.incrementEventIndex = incrementEventIndex
-        this.currentCallerContext = currentCallerContext
+        this.getCurrentCallerContext = getCurrentCallerContext
+        this.setCurrentCallerContext = setCurrentCallerContext
         this.onMembraneEvent = onMembraneEvent
         this.enableCallerStackInference = enableCallerStackInference
         this.encapsulateOptions = encapsulateOptions
@@ -116,8 +121,16 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         this.id = `$${encapsulateOptions.capsuleSourceLineRef}`
     }
 
-    setCurrentCallerContext(context: CallerContext | undefined): void {
-        this.currentCallerContext = context
+    private buildCallerContext(prop?: string): CallerContext {
+        const ctx: CallerContext = {
+            capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
+            spineContractCapsuleInstanceId: this.id,
+        }
+        if (prop) ctx.prop = prop
+        if (this.capsuleSourceNameRef) ctx.capsuleSourceNameRef = this.capsuleSourceNameRef
+        if (this.capsuleSourceNameRefHash) ctx.capsuleSourceNameRefHash = this.capsuleSourceNameRefHash
+        if (this.capsuleInstance?.capsuleSourceUriLineRefInstanceId) ctx.capsuleSourceUriLineRefInstanceId = this.capsuleInstance.capsuleSourceUriLineRefInstanceId
+        return ctx
     }
 
     protected async mapMappingProperty({ overrides, options, property }: { overrides: any, options: any, property: any }) {
@@ -155,25 +168,23 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                                 throw new Error(`Capsule instance not yet resolved: ${capsuleName}`)
                             }
 
-                            this.currentCallerContext = {
-                                capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
-                                capsuleSourceNameRef: this.capsuleSourceNameRef,
-                                spineContractCapsuleInstanceId: this.id,
-                                capsuleSourceNameRefHash: this.capsuleSourceNameRefHash,
-                                prop: apiProp as string
-                            }
-
-                            if (this.enableCallerStackInference) {
-                                const stackStr = new Error('[MAPPED_CAPSULE]').stack
-                                if (stackStr) {
-                                    const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
-                                    if (stackFrames.length > 0) {
-                                        const callerInfo = extractCallerInfo(stackFrames, 3)
-                                        this.currentCallerContext.filepath = callerInfo.filepath
-                                        this.currentCallerContext.line = callerInfo.line
-                                        this.currentCallerContext.stack = stackFrames
+                            // Only update caller context if not already set by a function/getter execution
+                            if (!this.getCurrentCallerContext()) {
+                                const callerCtx = this.buildCallerContext(undefined)
+
+                                if (this.enableCallerStackInference) {
+                                    const stackStr = new Error('[MAPPED_CAPSULE]').stack
+                                    if (stackStr) {
+                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                                        if (stackFrames.length > 0) {
+                                            const callerInfo = extractCallerInfo(stackFrames, 3)
+                                            callerCtx.filepath = callerInfo.filepath
+                                            callerCtx.line = callerInfo.line
+                                            callerCtx.stack = stackFrames
+                                        }
                                     }
                                 }
+                                this.setCurrentCallerContext(callerCtx)
                             }
 
                             // Access through .api if it exists (for capsule instances with getters)
@@ -280,25 +291,23 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
             get: (apiTarget: any, apiProp: string | symbol) => {
                 if (typeof apiProp === 'symbol') return apiTarget[apiProp]
 
-                this.currentCallerContext = {
-                    capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
-                    capsuleSourceNameRef: this.capsuleSourceNameRef,
-                    spineContractCapsuleInstanceId: this.id,
-                    capsuleSourceNameRefHash: this.capsuleSourceNameRefHash,
-                    prop: apiProp as string
-                }
-
-                if (this.enableCallerStackInference) {
-                    const stackStr = new Error('[MAPPED_CAPSULE]').stack
-                    if (stackStr) {
-                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
-                        if (stackFrames.length > 0) {
-                            const callerInfo = extractCallerInfo(stackFrames, 3)
-                            this.currentCallerContext.filepath = callerInfo.filepath
-                            this.currentCallerContext.line = callerInfo.line
-                            this.currentCallerContext.stack = stackFrames
+                // Only update caller context if not already set by a function/getter execution
+                if (!this.getCurrentCallerContext()) {
+                    const callerCtx = this.buildCallerContext(undefined)
+
+                    if (this.enableCallerStackInference) {
+                        const stackStr = new Error('[MAPPED_CAPSULE]').stack
+                        if (stackStr) {
+                            const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                            if (stackFrames.length > 0) {
+                                const callerInfo = extractCallerInfo(stackFrames, 3)
+                                callerCtx.filepath = callerInfo.filepath
+                                callerCtx.line = callerInfo.line
+                                callerCtx.stack = stackFrames
+                            }
                         }
                     }
+                    this.setCurrentCallerContext(callerCtx)
                 }
 
                 // Access through .api if it exists (for capsule instances with getters)
@@ -345,25 +354,23 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                     // Wrap the property access in a proxy to track membrane events
                     Object.defineProperty(delegateTarget, key, {
                         get: () => {
-                            this.currentCallerContext = {
-                                capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
-                                capsuleSourceNameRef: this.capsuleSourceNameRef,
-                                spineContractCapsuleInstanceId: this.id,
-                                capsuleSourceNameRefHash: this.capsuleSourceNameRefHash,
-                                prop: key
-                            }
-
-                            if (this.enableCallerStackInference) {
-                                const stackStr = new Error('[PROPERTY_CONTRACT_DELEGATE]').stack
-                                if (stackStr) {
-                                    const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
-                                    if (stackFrames.length > 0) {
-                                        const callerInfo = extractCallerInfo(stackFrames, 3)
-                                        this.currentCallerContext.filepath = callerInfo.filepath
-                                        this.currentCallerContext.line = callerInfo.line
-                                        this.currentCallerContext.stack = stackFrames
+                            // Only update caller context if not already set by a function/getter execution
+                            if (!this.getCurrentCallerContext()) {
+                                const callerCtx = this.buildCallerContext(undefined)
+
+                                if (this.enableCallerStackInference) {
+                                    const stackStr = new Error('[PROPERTY_CONTRACT_DELEGATE]').stack
+                                    if (stackStr) {
+                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                                        if (stackFrames.length > 0) {
+                                            const callerInfo = extractCallerInfo(stackFrames, 3)
+                                            callerCtx.filepath = callerInfo.filepath
+                                            callerCtx.line = callerInfo.line
+                                            callerCtx.stack = stackFrames
+                                        }
                                     }
                                 }
+                                this.setCurrentCallerContext(callerCtx)
                             }
 
                             // Access the actual value from the instance's api
@@ -513,6 +520,9 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                         if (this.capsuleSourceNameRefHash) {
                             callEvent.target.capsuleSourceNameRefHash = this.capsuleSourceNameRefHash
                         }
+                        if (this.capsuleInstance?.capsuleSourceUriLineRefInstanceId) {
+                            callEvent.target.capsuleSourceUriLineRefInstanceId = this.capsuleInstance.capsuleSourceUriLineRefInstanceId
+                        }
 
                         this.addCallerContextToEvent(callEvent)
                         this.onMembraneEvent?.(callEvent)
@@ -550,11 +560,18 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                     if (this.capsuleSourceNameRefHash) {
                         callEvent.target.capsuleSourceNameRefHash = this.capsuleSourceNameRefHash
                     }
+                    if (this.capsuleInstance?.capsuleSourceUriLineRefInstanceId) {
+                        callEvent.target.capsuleSourceUriLineRefInstanceId = this.capsuleInstance.capsuleSourceUriLineRefInstanceId
+                    }
 
                     this.addCallerContextToEvent(callEvent)
                     this.onMembraneEvent?.(callEvent)
 
+                    // Set this capsule as caller for any inner membrane events triggered by the function body
+                    const previousCallerContext = this.getCurrentCallerContext()
+                    this.setCurrentCallerContext(this.buildCallerContext(property.name))
                     const result = boundFunction(...args)
+                    this.setCurrentCallerContext(previousCallerContext)
 
                     // Store in memoize cache if memoize is enabled
                     if (shouldMemoize) {
@@ -635,8 +652,11 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                     return cachedResult
                 }
 
-                // Call the getter function lazily when accessed with proper this context
+                // Set this capsule as caller for any inner membrane events triggered by the getter body
+                const previousCallerContext = this.getCurrentCallerContext()
+                this.setCurrentCallerContext(this.buildCallerContext(property.name))
                 const result = getterFn.call(selfProxy)
+                this.setCurrentCallerContext(previousCallerContext)
 
                 // Store in memoize cache if memoize is enabled
                 if (shouldMemoize) {
@@ -693,28 +713,32 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
     }
 
     private addCallerContextToEvent(event: any): void {
-        if (this.currentCallerContext) {
+        const callerCtx = this.getCurrentCallerContext()
+        if (callerCtx) {
             event.caller = {
-                capsuleSourceLineRef: this.currentCallerContext.capsuleSourceLineRef,
-                spineContractCapsuleInstanceId: this.currentCallerContext.spineContractCapsuleInstanceId,
+                capsuleSourceLineRef: callerCtx.capsuleSourceLineRef,
+                spineContractCapsuleInstanceId: callerCtx.spineContractCapsuleInstanceId,
+            }
+            if (callerCtx.capsuleSourceNameRef) {
+                event.caller.capsuleSourceNameRef = callerCtx.capsuleSourceNameRef
             }
-            if (this.currentCallerContext.capsuleSourceNameRef) {
-                event.caller.capsuleSourceNameRef = this.currentCallerContext.capsuleSourceNameRef
+            if (callerCtx.capsuleSourceNameRefHash) {
+                event.caller.capsuleSourceNameRefHash = callerCtx.capsuleSourceNameRefHash
             }
-            if (this.currentCallerContext.capsuleSourceNameRefHash) {
-                event.caller.capsuleSourceNameRefHash = this.currentCallerContext.capsuleSourceNameRefHash
+            if (callerCtx.capsuleSourceUriLineRefInstanceId) {
+                event.caller.capsuleSourceUriLineRefInstanceId = callerCtx.capsuleSourceUriLineRefInstanceId
             }
-            if (this.currentCallerContext.prop) {
-                event.caller.prop = this.currentCallerContext.prop
+            if (callerCtx.prop) {
+                event.caller.prop = callerCtx.prop
             }
-            if (this.currentCallerContext.filepath) {
-                event.caller.filepath = this.currentCallerContext.filepath
+            if (callerCtx.filepath) {
+                event.caller.filepath = callerCtx.filepath
             }
-            if (this.currentCallerContext.line) {
-                event.caller.line = this.currentCallerContext.line
+            if (callerCtx.line) {
+                event.caller.line = callerCtx.line
             }
-            if (this.currentCallerContext.stack) {
-                event.caller.stack = this.currentCallerContext.stack
+            if (callerCtx.stack) {
+                event.caller.stack = callerCtx.stack
             }
         } else if (this.enableCallerStackInference) {
             const stackStr = new Error('[MEMBRANE_EVENT]').stack
@@ -771,7 +795,8 @@ export function CapsuleSpineContract({
                 encapsulateOptions,
                 getEventIndex: () => eventIndex,
                 incrementEventIndex: () => eventIndex++,
-                currentCallerContext,
+                getCurrentCallerContext: () => currentCallerContext,
+                setCurrentCallerContext: (ctx: CallerContext | undefined) => { currentCallerContext = ctx },
                 runtimeSpineContracts,
                 instanceRegistry,
                 extendedCapsuleInstance,

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

@@ -16,6 +16,7 @@ export class ContractCapsuleInstanceFactory {
     protected instanceRegistry?: CapsuleInstanceRegistry
     protected extendedCapsuleInstance?: any
     protected ownSelf?: any
+    public childEncapsulatedApis?: Record<string, any>[]
     protected runtimeSpineContracts?: Record<string, any>
     protected capsuleInstance?: any
     public structInitFunctions: Array<() => any> = []
@@ -61,7 +62,9 @@ export class ContractCapsuleInstanceFactory {
             overrides: overrides || {},
             options: options,
             runtimeSpineContracts: this.runtimeSpineContracts,
-            rootCapsule: this.capsuleInstance?.rootCapsule
+            rootCapsule: this.capsuleInstance?.rootCapsule,
+            parentCapsuleSourceUriLineRefInstanceId: this.capsuleInstance?.capsuleSourceUriLineRefInstanceId,
+            sit: this.capsuleInstance?.sit
         })
 
         // Run init functions on the imported capsule instance
@@ -310,7 +313,9 @@ export class ContractCapsuleInstanceFactory {
             overrides: mappedOverrides,
             options: ownMappingOptions,
             runtimeSpineContracts: this.runtimeSpineContracts,
-            rootCapsule: this.capsuleInstance?.rootCapsule
+            rootCapsule: this.capsuleInstance?.rootCapsule,
+            parentCapsuleSourceUriLineRefInstanceId: this.capsuleInstance?.capsuleSourceUriLineRefInstanceId,
+            sit: this.capsuleInstance?.sit
         })
 
         // Register the instance (replaces null pre-registration marker)
@@ -369,6 +374,7 @@ export class ContractCapsuleInstanceFactory {
     protected createSelfProxy() {
         const extendedApi = this.extendedCapsuleInstance?.api
         const ownSelf = this.ownSelf
+        const factory = this
         return new Proxy(this.self, {
             get: (target: any, prop: string | symbol) => {
                 if (typeof prop === 'symbol') return target[prop]
@@ -384,8 +390,15 @@ export class ContractCapsuleInstanceFactory {
                 }
 
                 // Fall back to encapsulatedApi
-                if (prop in this.encapsulatedApi) {
-                    return this.encapsulatedApi[prop]
+                if (prop in factory.encapsulatedApi) {
+                    return factory.encapsulatedApi[prop]
+                }
+
+                // Fall back to child capsule APIs (for parent→child function delegation)
+                if (factory.childEncapsulatedApis) {
+                    for (const childApi of factory.childEncapsulatedApis) {
+                        if (prop in childApi) return childApi[prop]
+                    }
                 }
 
                 // Fall back to extended capsule's API
@@ -393,6 +406,35 @@ export class ContractCapsuleInstanceFactory {
                     return extendedApi[prop]
                 }
 
+                return undefined
+            },
+            ownKeys: (target: any) => {
+                const keys = new Set<string>(Object.keys(target))
+                for (const k of Object.keys(factory.encapsulatedApi)) keys.add(k)
+                if (factory.childEncapsulatedApis) {
+                    for (const childApi of factory.childEncapsulatedApis) {
+                        for (const k of Object.keys(childApi)) keys.add(k)
+                    }
+                }
+                if (extendedApi) {
+                    for (const k of Object.keys(extendedApi)) keys.add(k)
+                }
+                return [...keys]
+            },
+            set: (target: any, prop: string | symbol, value: any) => {
+                target[prop] = value
+                return true
+            },
+            getOwnPropertyDescriptor: (target: any, prop: string | symbol) => {
+                if (typeof prop === 'symbol') return Object.getOwnPropertyDescriptor(target, prop)
+                if (prop in target) return Object.getOwnPropertyDescriptor(target, prop)
+                if (prop in factory.encapsulatedApi) return { configurable: true, enumerable: true, writable: true, value: factory.encapsulatedApi[prop as string] }
+                if (factory.childEncapsulatedApis) {
+                    for (const childApi of factory.childEncapsulatedApis) {
+                        if (prop in childApi) return { configurable: true, enumerable: true, writable: true, value: childApi[prop as string] }
+                    }
+                }
+                if (extendedApi && prop in extendedApi) return { configurable: true, enumerable: true, writable: true, value: extendedApi[prop as string] }
                 return undefined
             }
         })

package/src/spine-factories/CapsuleSpineFactory.v0.ts

@@ -473,6 +473,7 @@ export async function CapsuleSpineFactory({
             },
         },
         spineFilesystemRoot,
+        capsuleModuleProjectionRoot,
         capsuleModuleProjectionPackage,
         timing
     }) : undefined
@@ -570,13 +571,138 @@ export async function CapsuleSpineFactory({
         return capsule
     }
 
+    // Wrap freeze to also write spine instance (.sit.json) files
+    const wrappedFreeze = async function () {
+        const snapshot = await freeze()
+
+        // Write spine instance files if capsuleModuleProjectionRoot is available
+        if (capsuleModuleProjectionRoot) {
+            try {
+                // Deduplicate capsules: the capsules dict has entries keyed by both
+                // capsuleSourceLineRef and capsuleName — only process capsuleSourceLineRef keys
+                const uniqueCapsules: Record<string, any> = {}
+                for (const [key, capsule] of Object.entries(capsules)) {
+                    if (key.includes(':') && /:\d+$/.test(key)) {
+                        uniqueCapsules[key] = capsule
+                    }
+                }
+
+                // Find root capsules — capsules that are NOT referenced as mapped dependencies
+                const mappedCapsuleNames = new Set<string>()
+                for (const [, capsule] of Object.entries(uniqueCapsules)) {
+                    const cst = capsule.cst
+                    if (cst?.spineContracts) {
+                        for (const [, spineContract] of Object.entries(cst.spineContracts) as any) {
+                            if (spineContract.propertyContracts) {
+                                for (const [, propContract] of Object.entries(spineContract.propertyContracts) as any) {
+                                    if (propContract.properties) {
+                                        for (const [, propDef] of Object.entries(propContract.properties) as any) {
+                                            if (propDef.type === 'CapsulePropertyTypes.Mapping' && propDef.mappedModuleUri) {
+                                                mappedCapsuleNames.add(propDef.mappedModuleUri)
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    if (cst?.source?.extendsCapsuleUri) {
+                        mappedCapsuleNames.add(cst.source.extendsCapsuleUri)
+                    }
+                }
+
+                for (const [, capsule] of Object.entries(uniqueCapsules)) {
+                    const cst = capsule.cst
+                    const rootCapsuleName = cst?.source?.capsuleName
+                    if (!rootCapsuleName) continue
+
+                    const moduleUri = cst?.source?.moduleUri
+                    if (mappedCapsuleNames.has(rootCapsuleName) || (moduleUri && mappedCapsuleNames.has(moduleUri))) {
+                        continue
+                    }
+
+                    // This is a root capsule — write its .sit.json
+                    const dirName = rootCapsuleName.replace(/\//g, '~')
+                    const sitDir = join(capsuleModuleProjectionRoot, '.~o/encapsulate.dev/spine-instances', dirName)
+                    const sitFilePath = join(sitDir, `root-capsule.sit.json`)
+
+                    // Build the capsules map
+                    const capsuleEntries: Record<string, { capsuleSourceUriLineRef: string }> = {}
+                    for (const [, cap] of Object.entries(uniqueCapsules)) {
+                        const capCst = cap.cst
+                        if (capCst?.source?.capsuleName) {
+                            capsuleEntries[capCst.source.capsuleName] = {
+                                capsuleSourceUriLineRef: capCst.capsuleSourceUriLineRef
+                            }
+                        }
+                    }
+
+                    // Collect capsuleInstances from the cached root instance using an
+                    // iterative stack — each instance stores its ID and parent ID from init
+                    const rootInstance = await capsule.makeInstance()
+                    const capsuleInstances: Record<string, { capsuleName: string, capsuleSourceUriLineRef: string, parentCapsuleSourceUriLineRefInstanceId: string }> = {}
+
+                    // If the root instance has a sit with pre-populated capsuleInstances, use it directly
+                    if (rootInstance.sit?.capsuleInstances && Object.keys(rootInstance.sit.capsuleInstances).length > 0) {
+                        Object.assign(capsuleInstances, rootInstance.sit.capsuleInstances)
+                    } else {
+                        // Iterative stack-based collection from instance tree
+                        const stack: Array<{ instance: any, parentId: string }> = [{ instance: rootInstance, parentId: '' }]
+                        const visited = new Set<string>()
+                        while (stack.length > 0) {
+                            const { instance, parentId } = stack.pop()!
+                            if (!instance?.capsuleSourceUriLineRefInstanceId) continue
+                            const id = instance.capsuleSourceUriLineRefInstanceId
+                            if (visited.has(id)) continue
+                            visited.add(id)
+
+                            capsuleInstances[id] = {
+                                capsuleName: instance.capsuleName || '',
+                                capsuleSourceUriLineRef: instance.capsuleSourceUriLineRef || '',
+                                parentCapsuleSourceUriLineRefInstanceId: parentId
+                            }
+
+                            if (instance.extendedCapsuleInstance) {
+                                stack.push({ instance: instance.extendedCapsuleInstance, parentId: id })
+                            }
+                            if (instance.mappedCapsuleInstances) {
+                                for (const mapped of instance.mappedCapsuleInstances) {
+                                    stack.push({ instance: mapped, parentId: id })
+                                }
+                            }
+                        }
+                    }
+
+                    const rootInstanceId = rootInstance.capsuleSourceUriLineRefInstanceId || ''
+
+                    const sitData = {
+                        rootCapsule: {
+                            capsuleSourceUriLineRef: cst.capsuleSourceUriLineRef,
+                            capsuleSourceUriLineRefInstanceId: rootInstanceId
+                        },
+                        capsules: capsuleEntries,
+                        capsuleInstances
+                    }
+
+                    await mkdir(sitDir, { recursive: true })
+                    await writeFile(sitFilePath, JSON.stringify(sitData, null, 2), 'utf-8')
+                }
+            } catch (error) {
+                // Spine instance file writing is best-effort
+                console.warn('Warning: Failed to write spine instance files:', error)
+            }
+        }
+
+        return snapshot
+    }
+
     return {
         commonSpineContractOpts,
         CapsulePropertyTypes,
         makeImportStack,
         encapsulate,
         run,
-        freeze,
+        freeze: wrappedFreeze,
         loadCapsule,
         spineContractInstances, // Expose for testing
         hoistSnapshot: async ({ snapshot }: { snapshot: any }) => {

package/src/static-analyzer.v0.ts

@@ -202,6 +202,11 @@ const MODULE_GLOBAL_BUILTINS = new Set([
     'Intl',
     'WebAssembly',
 
+    // Global scope references
+    'globalThis',
+    'window',
+    'global',
+
     // Global functions
     'isNaN',
     'isFinite',
@@ -241,8 +246,11 @@ export function StaticAnalyzer({
 
             // Determine the cache file path based on whether the module is external or internal
             let cacheFilePath: string
-            if (encapsulateOptions.moduleFilepath.startsWith('../')) {
-                // External module - construct npm URI
+            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
@@ -363,7 +371,7 @@ export function StaticAnalyzer({
 
                     const capsuleSourceLineRef = `${encapsulateOptions.moduleFilepath}:${encapsulateOptions.importStackLine}`
                     const capsuleSourceNameRef = encapsulateOptions.capsuleName && `${encapsulateOptions.moduleFilepath}:${encapsulateOptions.capsuleName}`
-                    const capsuleSourceNameRefHash = capsuleSourceNameRef && createHash('md5').update(capsuleSourceNameRef).digest('hex')
+                    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)
@@ -525,20 +533,39 @@ export function StaticAnalyzer({
                                             if (propName.startsWith('#')) {
                                                 const propertyContractUri = propName.substring(1) // Remove the '#' prefix
 
+                                                // Resolve relative property contract URIs to full npm URIs
+                                                let resolvedPropertyContractUri = propertyContractUri
+                                                let resolvedPropName = propName
+                                                if (propertyContractUri.startsWith('./') || propertyContractUri.startsWith('../')) {
+                                                    const resolvedPath = resolve(dirname(moduleFilepath), propertyContractUri)
+                                                    const npmUri = await constructNpmUri(resolvedPath + '.ts', spineOptions.spineFilesystemRoot)
+                                                    if (npmUri) {
+                                                        resolvedPropertyContractUri = npmUri.replace(/\.(ts|tsx|js|jsx)$/, '')
+                                                        resolvedPropName = '#' + resolvedPropertyContractUri
+                                                    }
+                                                }
+
                                                 if (ts.isObjectLiteralExpression(propValue)) {
                                                     // Create property contract entry
-                                                    if (!spineContractDef.propertyContracts[propName]) {
-                                                        spineContractDef.propertyContracts[propName] = {
-                                                            propertyContractUri,
+                                                    if (!spineContractDef.propertyContracts[resolvedPropName]) {
+                                                        spineContractDef.propertyContracts[resolvedPropName] = {
+                                                            propertyContractUri: resolvedPropertyContractUri,
                                                             properties: {}
                                                         }
                                                     }
 
-                                                    // Check for 'as' property at the property contract level
+                                                    // Check for 'as' and 'options' properties at the property contract level
                                                     for (const contractProp of propValue.properties) {
-                                                        if (ts.isPropertyAssignment(contractProp) && ts.isIdentifier(contractProp.name) && contractProp.name.text === 'as') {
-                                                            if (ts.isStringLiteral(contractProp.initializer)) {
-                                                                spineContractDef.propertyContracts[propName].as = contractProp.initializer.text
+                                                        if (ts.isPropertyAssignment(contractProp) && ts.isIdentifier(contractProp.name)) {
+                                                            if (contractProp.name.text === 'as') {
+                                                                if (ts.isStringLiteral(contractProp.initializer)) {
+                                                                    spineContractDef.propertyContracts[resolvedPropName].as = contractProp.initializer.text
+                                                                }
+                                                            } else if (contractProp.name.text === 'options') {
+                                                                // Store literal options object on the property contract for graph queries
+                                                                if (ts.isObjectLiteralExpression(contractProp.initializer)) {
+                                                                    spineContractDef.propertyContracts[resolvedPropName].options = await extractLiteralObject(contractProp.initializer, sourceFile, moduleFilepath, spineOptions.spineFilesystemRoot)
+                                                                }
                                                             }
                                                         }
                                                     }
@@ -629,6 +656,9 @@ export function StaticAnalyzer({
                                                                                 if (selfRefs.size > 0) {
                                                                                     propDef.depends = Array.from(selfRefs)
                                                                                 }
+                                                                            } else if (ts.isObjectLiteralExpression(fieldValue)) {
+                                                                                // Store literal options object in the CST for graph queries
+                                                                                propDef.options = await extractLiteralObject(fieldValue, sourceFile, moduleFilepath, spineOptions.spineFilesystemRoot)
                                                                             }
                                                                         } else if (fieldName === 'kind') {
                                                                             propDef.kind = fieldValue.getText(sourceFile)
@@ -640,7 +670,7 @@ export function StaticAnalyzer({
                                                                     }
                                                                 }
 
-                                                                spineContractDef.propertyContracts[propName].properties[contractPropName] = propDef
+                                                                spineContractDef.propertyContracts[resolvedPropName].properties[contractPropName] = propDef
                                                             }
                                                         }
                                                     }
@@ -2185,6 +2215,75 @@ function extractAndValidateAmbientReferences(
     return ambientRefs
 }
 
+// Extract a literal object from a TypeScript AST ObjectLiteralExpression.
+// Recursively walks the object tree and extracts string, number, boolean,
+// null values, arrays, and nested objects. String values that look like
+// relative paths (starting with ./ or ../) are resolved to npm URIs.
+async function extractLiteralObject(
+    node: ts.ObjectLiteralExpression,
+    sourceFile: ts.SourceFile,
+    moduleFilepath: string,
+    spineFilesystemRoot: string
+): Promise<Record<string, any>> {
+    const result: Record<string, any> = {}
+
+    for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue
+        let key: string | null = null
+        if (ts.isIdentifier(prop.name)) key = prop.name.text
+        else if (ts.isStringLiteral(prop.name)) key = prop.name.text
+        if (!key) continue
+
+        result[key] = await extractLiteralValue(prop.initializer, sourceFile, moduleFilepath, spineFilesystemRoot)
+    }
+
+    return result
+}
+
+// Extract a single literal value from a TS AST node.
+// Handles strings (with relative path resolution), numbers, booleans,
+// null, undefined, arrays, and nested objects.
+async function extractLiteralValue(
+    node: ts.Expression,
+    sourceFile: ts.SourceFile,
+    moduleFilepath: string,
+    spineFilesystemRoot: string
+): Promise<any> {
+    // String literals — resolve relative paths to npm URIs
+    if (ts.isStringLiteral(node)) {
+        const text = node.text
+        if (text.startsWith('./') || text.startsWith('../')) {
+            const resolvedPath = resolve(dirname(moduleFilepath), text)
+            const npmUri = await constructNpmUri(resolvedPath + '.ts', spineFilesystemRoot)
+            if (npmUri) return npmUri.replace(/\.(ts|tsx|js|jsx)$/, '')
+        }
+        return text
+    }
+    // Numeric literals
+    if (ts.isNumericLiteral(node)) return Number(node.text)
+    // Boolean literals
+    if (node.kind === ts.SyntaxKind.TrueKeyword) return true
+    if (node.kind === ts.SyntaxKind.FalseKeyword) return false
+    // Null
+    if (node.kind === ts.SyntaxKind.NullKeyword) return null
+    // Undefined
+    if (node.kind === ts.SyntaxKind.UndefinedKeyword) return undefined
+    // Nested objects
+    if (ts.isObjectLiteralExpression(node)) {
+        return await extractLiteralObject(node, sourceFile, moduleFilepath, spineFilesystemRoot)
+    }
+    // Arrays
+    if (ts.isArrayLiteralExpression(node)) {
+        const arr: any[] = []
+        for (const elem of node.elements) {
+            arr.push(await extractLiteralValue(elem, sourceFile, moduleFilepath, spineFilesystemRoot))
+        }
+        return arr
+    }
+    // Fallback: store the raw expression text
+    return node.getText(sourceFile)
+}
+
 // Check if a value is a literal type
 function isLiteralType(value: any): boolean {
     const type = typeof value

package/tsconfig.json

@@ -1,5 +1,4 @@
 {
-    "extends": "../../../tsconfig.paths.json",
     "compilerOptions": {
         "target": "ES2020",
         "module": "esnext",
@@ -27,4 +26,4 @@
     "exclude": [
         "node_modules"
     ]
-}
+}