@stream44.studio/encapsulate 0.4.0-rc.34 → 0.4.0-rc.39

package/src/encapsulate.ts

@@ -7,7 +7,16 @@ type TSpineOptions = {
     spineFilesystemRoot?: string,
     spineContracts: Record<string, any>,
     staticAnalyzer?: any,
-    timing?: { record: (step: string) => void, chalk?: any }
+    timing?: { record: (step: string) => void, chalk?: any },
+    projectionContext?: {
+        capsuleModuleProjectionPackage?: string,
+        capsuleModuleProjectionRoot?: string,
+        projectionStore?: {
+            writeFile: (filepath: string, content: string) => Promise<void>,
+            getStats?: (filepath: string) => Promise<{ mtime: Date } | null>
+        } | null,
+        capsules?: Record<string, any>
+    }
 }
 
 type TSpineRunOptions = {
@@ -115,6 +124,8 @@ export const CapsulePropertyTypes = {
     StructDispose: 'StructDispose' as const,
     Init: 'Init' as const,
     Dispose: 'Dispose' as const,
+    OnFreeze: 'OnFreeze' as const,
+    ProxyFunction: 'ProxyFunction' as const,
 }
 
 // ##################################################
@@ -188,8 +199,8 @@ export async function SpineRuntime(options: TSpineRuntimeOptions): Promise<TSpin
 
                             // If the value is a raw capsule instance (has spineContractCapsuleInstances
                             // but is NOT a Proxy that handles API access), unwrap it
-                            // Static.v0 sets apiTarget[property.name] = mappedInstance (raw)
-                            // Membrane.v0 sets apiTarget[property.name] = new Proxy(...) which handles API access
+                            // Static sets apiTarget[property.name] = mappedInstance (raw)
+                            // Membrane sets apiTarget[property.name] = new Proxy(...) which handles API access
                             if (value && typeof value === 'object' && value.spineContractCapsuleInstances) {
                                 // Check if this is a raw capsule instance by seeing if it has .api
                                 // and the .api doesn't have the same spineContractCapsuleInstances
@@ -430,7 +441,13 @@ export async function Spine(options: TSpineOptions): Promise<TSpine> {
 
             options.timing?.record(`Spine: Freezing ${Object.keys(capsules).length} capsules`)
 
-            await Promise.all(Object.entries(capsules).map(async ([capsuleSourceLineRef, capsule]) => {
+            const processedCapsules = new Set<any>()
+            const freezeVisited = new Set<any>()
+            for (const [capsuleSourceLineRef, capsule] of Object.entries(capsules)) {
+
+                // Skip capsuleName aliases — only process each capsule once via its capsuleSourceLineRef
+                if (processedCapsules.has(capsule)) continue
+                processedCapsules.add(capsule)
 
                 if (!capsule.cst.source.capsuleName) throw new Error(`'capsuleName' must be set for encapsulate options to enable freezing.`)
 
@@ -438,10 +455,95 @@ export async function Spine(options: TSpineOptions): Promise<TSpine> {
                     cst: capsule.cst,
                     spineContracts: {}
                 }
+                // Also register under capsuleName so SpineRuntime can resolve by name
+                if (capsule.cst.source.capsuleName && capsule.cst.source.capsuleName !== capsuleSourceLineRef) {
+                    snapshot.capsules[capsule.cst.source.capsuleName] = snapshot.capsules[capsuleSourceLineRef]
+                }
+
+                const capsuleInstance = await capsule.makeInstance()
+
+                // Run OnFreeze functions so capsules can perform side effects
+                // (e.g. file projection) at build/freeze time
+                async function runOnFreeze(instance: any, parentCapsuleCst?: any, parentCapsuleSourceLineRef?: string, projectionPath?: string, projectionSpineContractUri?: string) {
+                    if (!instance) return
+                    // Use capsuleSourceLineRef for deduplication — this is stable across different
+                    // instance objects of the same capsule (top-level vs mapped child).
+                    // Include projectionPath in the key so the same capsule can project to
+                    // multiple output paths (e.g. standalone delegate used by different parents).
+                    // Fall back to instance identity for internal capsules without a lineRef.
+                    // Use capsuleName as the base key when available (always a unique string),
+                    // otherwise fall back to capsuleSourceLineRef or instance identity.
+                    // This avoids collisions from object refs that all stringify to '[object Object]'.
+                    const baseKey = instance.capsuleName || instance.capsuleSourceLineRef || instance
+                    const freezeKey = projectionPath ? `${baseKey}::${projectionPath}` : baseKey
+                    if (freezeVisited.has(freezeKey)) return
+                    freezeVisited.add(freezeKey)
+
+                    // Inject projection context onto CapsuleProjectionContext instances
+                    // Set values on both the api (encapsulatedApi) and spine contract self
+                    // so they are visible through all proxy chains.
+                    // Scan recursively into mapped children since CapsuleProjectionContext
+                    // may be nested inside a property contract delegate (e.g. a projector capsule).
+                    const projectionCtx = options.projectionContext
+                    if (projectionCtx && instance.mappedCapsuleInstances?.length) {
+                        const injectCtx = (children: any[]) => {
+                            for (const mappedChild of children) {
+                                const childApi = mappedChild.api
+                                if (childApi && mappedChild.capsuleName === '@stream44.studio/encapsulate/structs/CapsuleProjectionContext') {
+                                    const ctx = {
+                                        parentCapsuleCst: parentCapsuleCst,
+                                        parentCapsuleSourceLineRef: parentCapsuleSourceLineRef,
+                                        capsuleModuleProjectionPackage: projectionCtx.capsuleModuleProjectionPackage,
+                                        projectionStore: projectionCtx.projectionStore,
+                                        capsuleSnapshots: projectionCtx.capsules,
+                                        projectionPath: projectionPath,
+                                        spineContractUri: projectionSpineContractUri,
+                                    }
+                                    Object.assign(childApi, ctx)
+                                    // Also update spine contract self for selfProxy access
+                                    for (const childSci of Object.values(mappedChild.spineContractCapsuleInstances || {})) {
+                                        const childSelf = (childSci as any).self
+                                        if (childSelf) Object.assign(childSelf, ctx)
+                                    }
+                                }
+                                // Recurse into delegate's mapped children
+                                if (mappedChild.mappedCapsuleInstances?.length) {
+                                    injectCtx(mappedChild.mappedCapsuleInstances)
+                                }
+                            }
+                        }
+                        injectCtx(instance.mappedCapsuleInstances)
+                    }
 
-                const { spineContractCapsuleInstances } = await capsule.makeInstance()
+                    if (instance.onFreezeFunctions?.length) {
+                        for (const fn of instance.onFreezeFunctions) {
+                            await fn()
+                        }
+                    }
 
-                await Promise.all(Object.entries(spineContractCapsuleInstances).map(async ([spineContractUri, spineContractCapsuleInstance]) => {
+                    if (instance.extendedCapsuleInstance) {
+                        await runOnFreeze(instance.extendedCapsuleInstance, parentCapsuleCst, parentCapsuleSourceLineRef, projectionPath, projectionSpineContractUri)
+                    }
+                    if (instance.mappedCapsuleInstances?.length) {
+                        for (const mappedInstance of instance.mappedCapsuleInstances) {
+                            // Determine projection path from the property name (alias) used for this mapping.
+                            // If the mapped child doesn't define its own path (no / prefix), inherit the parent's projectionPath
+                            // so it flows down to property contract delegates.
+                            const mappedProjectionPath = mappedInstance.mappedPropertyName?.startsWith('/') ? mappedInstance.mappedPropertyName : projectionPath
+                            // For regular mapped capsules (non-struct delegates), use their own CST as
+                            // parentCapsuleCst so nested property contract delegates see the correct parent.
+                            // Property contract delegates (flagged by Static) pass through the current
+                            // parentCapsuleCst so their OnFreeze sees the declaring capsule's CST.
+                            const mappedCapsule = (!mappedInstance.isPropertyContractDelegate && mappedInstance.capsuleName) ? capsules[mappedInstance.capsuleName] : undefined
+                            const childParentCst = mappedCapsule?.cst || parentCapsuleCst
+                            const instanceSourceLineRef = instance.capsuleSourceLineRef || parentCapsuleSourceLineRef
+                            await runOnFreeze(mappedInstance, childParentCst, instanceSourceLineRef, mappedProjectionPath, Object.keys(capsuleInstance.spineContractCapsuleInstances)?.[0])
+                        }
+                    }
+                }
+                await runOnFreeze(capsuleInstance, capsule.cst, capsule.capsuleSourceLineRef)
+
+                await Promise.all(Object.entries(capsuleInstance.spineContractCapsuleInstances).map(async ([spineContractUri, spineContractCapsuleInstance]) => {
 
                     snapshot.capsules[capsuleSourceLineRef] = merge(
                         snapshot.capsules[capsuleSourceLineRef],
@@ -451,7 +553,7 @@ export async function Spine(options: TSpineOptions): Promise<TSpine> {
                         })
                     )
                 }))
-            }))
+            }
 
             options.timing?.record('Spine: Freeze complete')
 
@@ -621,7 +723,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                                 // Check if 'as' is defined to use as the property name alias
                                 const propDefTyped = propDef as Record<string, any>
                                 const aliasName = propDefTyped.as
-                                const delegateOptions = propDefTyped.options
+                                let delegateOptions = propDefTyped.options
                                 const contractKey = aliasName || ('#' + propContractUri.substring(1))
 
                                 if (!propertyContractDefinitions[spineContractUri]['#']) {
@@ -835,8 +937,8 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                             moduleFilepath: absoluteModuleFilepath
                         },
                         parentCapsuleSourceUriLineRefInstanceId: parentCapsuleSourceUriLineRefInstanceId
-                            ? sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + (cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef))
-                            : sha256(cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef),
+                            ? await sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + (cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef))
+                            : await sha256(cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef),
                         sit
                     })
 
@@ -873,8 +975,8 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 //   child: sha256(parentCapsuleSourceUriLineRefInstanceId + ":" + capsuleSourceUriLineRef)
                 const capsuleSourceUriLineRef = cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef
                 const capsuleSourceUriLineRefInstanceId = parentCapsuleSourceUriLineRefInstanceId
-                    ? sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + capsuleSourceUriLineRef)
-                    : sha256(capsuleSourceUriLineRef)
+                    ? await sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + capsuleSourceUriLineRef)
+                    : await sha256(capsuleSourceUriLineRef)
 
                 // Register this instance in the sit structure if provided
                 if (sit) {
@@ -893,6 +995,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     structDisposeFunctions: [] as Array<() => any>,
                     initFunctions: [] as Array<() => any>,
                     disposeFunctions: [] as Array<() => any>,
+                    onFreezeFunctions: [] as Array<() => any>,
                     mappedCapsuleInstances: [] as Array<any>,
                     rootCapsule: resolvedRootCapsule,
                     capsuleSourceUriLineRefInstanceId,
@@ -987,6 +1090,9 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     if (sci.disposeFunctions?.length) {
                         capsuleInstance.disposeFunctions.push(...sci.disposeFunctions)
                     }
+                    if (sci.onFreezeFunctions?.length) {
+                        capsuleInstance.onFreezeFunctions.push(...sci.onFreezeFunctions)
+                    }
                     if (sci.mappedCapsuleInstances?.length) {
                         capsuleInstance.mappedCapsuleInstances.push(...sci.mappedCapsuleInstances)
                     }
@@ -1124,15 +1230,15 @@ 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
+async function sha256(input: string): Promise<string> {
+    const data = new TextEncoder().encode(input)
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+    const hashArray = new Uint8Array(hashBuffer)
+    let hex = ''
+    for (let i = 0; i < hashArray.length; i++) {
+        hex += hashArray[i].toString(16).padStart(2, '0')
     }
-    const { createHash } = require('crypto')
-    return createHash('sha256').update(input).digest('hex')
+    return hex
 }
 
 function isObject(item: any): boolean {

package/src/spine-contracts/CapsuleSpineContract.v0/{Membrane.v0.ts → Membrane.ts}

@@ -1,7 +1,5 @@
 import { CapsulePropertyTypes } from "../../encapsulate"
-import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static.v0"
-import { readFileSync, existsSync } from "node:fs"
-import { dirname, relative, join } from "node:path"
+import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static"
 
 type CallerContext = {
     capsuleSourceLineRef: string
@@ -60,6 +58,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
     private setCurrentCallerContext: (ctx: CallerContext | undefined) => void
     private onMembraneEvent?: (event: any) => void
     private enableCallerStackInference: boolean
+    private npmUriForFilepathSync?: (filepath: string) => string | null
     private encapsulateOptions: any
     private capsuleSourceNameRef?: string
     private capsuleSourceNameRefHash?: string
@@ -78,6 +77,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         freezeCapsule,
         onMembraneEvent,
         enableCallerStackInference,
+        npmUriForFilepathSync,
         encapsulateOptions,
         getEventIndex,
         incrementEventIndex,
@@ -99,6 +99,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         freezeCapsule?: (capsule: any) => Promise<any>
         onMembraneEvent?: (event: any) => void
         enableCallerStackInference: boolean
+        npmUriForFilepathSync?: (filepath: string) => string | null
         encapsulateOptions: any
         getEventIndex: () => number
         incrementEventIndex: () => number
@@ -116,6 +117,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         this.setCurrentCallerContext = setCurrentCallerContext
         this.onMembraneEvent = onMembraneEvent
         this.enableCallerStackInference = enableCallerStackInference
+        this.npmUriForFilepathSync = npmUriForFilepathSync
         this.encapsulateOptions = encapsulateOptions
         this.capsuleSourceNameRef = capsule?.cst?.capsuleSourceNameRef
         this.capsuleSourceNameRefHash = capsule?.cst?.capsuleSourceNameRefHash
@@ -184,7 +186,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                                 if (this.enableCallerStackInference) {
                                     const stackStr = new Error('[MAPPED_CAPSULE]').stack
                                     if (stackStr) {
-                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot, this.npmUriForFilepathSync)
                                         if (stackFrames.length > 0) {
                                             const callerInfo = extractCallerInfo(stackFrames, 3)
                                             callerCtx.fileUri = callerInfo.fileUri
@@ -311,7 +313,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                     if (this.enableCallerStackInference) {
                         const stackStr = new Error('[MAPPED_CAPSULE]').stack
                         if (stackStr) {
-                            const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                            const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot, this.npmUriForFilepathSync)
                             if (stackFrames.length > 0) {
                                 const callerInfo = extractCallerInfo(stackFrames, 3)
                                 callerCtx.fileUri = callerInfo.fileUri
@@ -374,7 +376,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                                 if (this.enableCallerStackInference) {
                                     const stackStr = new Error('[PROPERTY_CONTRACT_DELEGATE]').stack
                                     if (stackStr) {
-                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot, this.npmUriForFilepathSync)
                                         if (stackFrames.length > 0) {
                                             const callerInfo = extractCallerInfo(stackFrames, 3)
                                             callerCtx.fileUri = callerInfo.fileUri
@@ -618,6 +620,86 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         })
     }
 
+    protected override mapProxyFunctionProperty({ property }: { property: any }) {
+        const selfProxy = this.createSelfProxy()
+
+        const childTargetFn = property.definition.value.target
+        const childInvokeFn = property.definition.value.invoke
+
+        // Inherit missing parts from parent's ProxyFunction (if extending)
+        const parentParts = this.self[`__proxyFn_${property.name}`]
+        const targetFn = childTargetFn ?? parentParts?.target
+        const invokeFn = childInvokeFn ?? parentParts?.invoke
+
+        if (!targetFn) throw new Error(`ProxyFunction '${property.name}': target() is required`)
+        if (!invokeFn) throw new Error(`ProxyFunction '${property.name}': invoke() is required`)
+
+        // Store parts for potential child override
+        this.self[`__proxyFn_${property.name}`] = { target: targetFn, invoke: invokeFn }
+
+        const boundProxyFn = (...args: any[]) => {
+            const transformedArgs = invokeFn.call(selfProxy, ...args)
+            const target = targetFn.call(selfProxy)
+            if (transformedArgs && typeof transformedArgs.then === 'function') {
+                return transformedArgs.then((resolved: any) => target(resolved))
+            }
+            return target(transformedArgs)
+        }
+
+        Object.defineProperty(this.encapsulatedApi, property.name, {
+            get: () => {
+                return (...args: any[]) => {
+                    const callEvent: any = {
+                        event: 'call',
+                        eventIndex: this.incrementEventIndex(),
+                        membrane: 'external',
+                        target: {
+                            capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
+                            spineContractCapsuleInstanceId: this.id,
+                            prop: property.name,
+                        },
+                        args
+                    }
+
+                    if (this.capsuleSourceNameRef) {
+                        callEvent.target.capsuleSourceNameRef = this.capsuleSourceNameRef
+                    }
+                    if (this.capsuleSourceNameRefHash) {
+                        callEvent.target.capsuleSourceNameRefHash = this.capsuleSourceNameRefHash
+                    }
+                    if (this.capsuleInstance?.capsuleSourceUriLineRefInstanceId) {
+                        callEvent.target.capsuleSourceUriLineRefInstanceId = this.capsuleInstance.capsuleSourceUriLineRefInstanceId
+                    }
+
+                    this.addCallerContextToEvent(callEvent)
+                    this.onMembraneEvent?.(callEvent)
+
+                    const previousCallerContext = this.getCurrentCallerContext()
+                    this.setCurrentCallerContext(this.buildCallerContext(property.name))
+                    const result = boundProxyFn(...args)
+                    this.setCurrentCallerContext(previousCallerContext)
+
+                    const resultEvent: any = {
+                        event: 'call-result',
+                        eventIndex: this.incrementEventIndex(),
+                        membrane: 'external',
+                        callEventIndex: callEvent.eventIndex,
+                        target: {
+                            spineContractCapsuleInstanceId: this.id,
+                        },
+                        result
+                    }
+
+                    this.onMembraneEvent?.(resultEvent)
+
+                    return result
+                }
+            },
+            enumerable: true,
+            configurable: true
+        })
+    }
+
     protected mapGetterFunctionProperty({ property }: { property: any }) {
         const getterFn = property.definition.value
         const selfProxy = this.createSelfProxy()
@@ -747,16 +829,13 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                 }
 
                 // Determine the value source and get the value
+                // Virtual dispatch: child overrides take precedence over both
+                // self and own encapsulatedApi, matching class-inheritance semantics
                 let value: any
                 let source: 'self' | 'encapsulatedApi' | 'childApi' | 'extendedApi' | undefined
 
-                if (prop in target) {
-                    value = target[prop]
-                    source = 'self'
-                } else if (prop in factory.encapsulatedApi) {
-                    value = factory.encapsulatedApi[prop]
-                    source = 'encapsulatedApi'
-                } else if (factory.childEncapsulatedApis) {
+                // Check child capsule APIs first for virtual dispatch
+                if (factory.childEncapsulatedApis) {
                     for (const childApi of factory.childEncapsulatedApis) {
                         if (prop in childApi) {
                             value = childApi[prop]
@@ -766,6 +845,16 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                     }
                 }
 
+                if (source === undefined) {
+                    if (prop in target) {
+                        value = target[prop]
+                        source = 'self'
+                    } else if (prop in factory.encapsulatedApi) {
+                        value = factory.encapsulatedApi[prop]
+                        source = 'encapsulatedApi'
+                    }
+                }
+
                 if (source === undefined && extendedApi && prop in extendedApi) {
                     value = extendedApi[prop]
                     source = 'extendedApi'
@@ -892,7 +981,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         } else if (this.enableCallerStackInference) {
             const stackStr = new Error('[MEMBRANE_EVENT]').stack
             if (stackStr) {
-                const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot, this.npmUriForFilepathSync)
                 if (stackFrames.length > 0) {
                     const callerInfo = extractCallerInfo(stackFrames, 3)
                     event.caller = {
@@ -911,7 +1000,8 @@ export function CapsuleSpineContract({
     enableCallerStackInference = false,
     spineFilesystemRoot,
     resolve,
-    importCapsule
+    importCapsule,
+    npmUriForFilepath
 }: {
     onMembraneEvent?: (event: any) => void
     freezeCapsule?: (capsule: any) => Promise<any>
@@ -919,12 +1009,28 @@ export function CapsuleSpineContract({
     spineFilesystemRoot?: string
     resolve?: (uri: string, parentFilepath: string) => Promise<string>
     importCapsule?: (filepath: string) => Promise<any>
+    npmUriForFilepath?: (filepath: string) => Promise<string | null>
 } = {}) {
 
     let eventIndex = 0
     let currentCallerContext: CallerContext | undefined = undefined
     const instanceRegistry: CapsuleInstanceRegistry = new Map()
 
+    // Sync cache for npmUriForFilepath — async calls populate the cache,
+    // sync reads return cached values (raw filepath fallback on cache miss).
+    const npmUriCache = new Map<string, string | null>()
+    const npmUriForFilepathSync = npmUriForFilepath
+        ? (filepath: string): string | null => {
+            if (npmUriCache.has(filepath)) return npmUriCache.get(filepath)!
+            // Fire async resolution to populate cache for next access
+            npmUriForFilepath(filepath).then(
+                uri => npmUriCache.set(filepath, uri),
+                () => npmUriCache.set(filepath, null)
+            )
+            return null
+        }
+        : undefined
+
     // Re-entrancy guard: suppress event emission while inside an onMembraneEvent callback.
     // This prevents consumers (e.g. JSON.stringify on event.value) from triggering proxy getters
     // that would cause spurious recursive membrane events with wrong caller context and ordering.
@@ -955,6 +1061,7 @@ export function CapsuleSpineContract({
                 importCapsule,
                 onMembraneEvent: guardedOnMembraneEvent,
                 enableCallerStackInference,
+                npmUriForFilepathSync,
                 encapsulateOptions,
                 getEventIndex: () => eventIndex,
                 incrementEventIndex: () => eventIndex++,
@@ -975,67 +1082,7 @@ export function CapsuleSpineContract({
 CapsuleSpineContract['#'] = '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0'
 
 
-
-
-// Cache for synchronous npm URI lookups (directory -> package name or null)
-const npmUriCache = new Map<string, string | null>()
-
-function constructNpmUriSync(absoluteFilepath: string): string | null {
-    // Only process absolute paths — skip V8 internal markers like "native", "node:*", etc.
-    if (!absoluteFilepath.startsWith('/')) {
-        return 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 }> {
+function parseCallerFromStack(stack: string, spineFilesystemRoot?: string, npmUriForFilepathSync?: (filepath: string) => string | null): Array<{ function?: string, fileUri?: string, line?: number, column?: number }> {
     const lines = stack.split('\n')
     const result: Array<{ function?: string, fileUri?: string, line?: number, column?: number }> = []
 
@@ -1082,7 +1129,7 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
 
             // Convert absolute filepaths to npm URIs
             if (rawFilepath) {
-                const npmUri = constructNpmUriSync(rawFilepath)
+                const npmUri = npmUriForFilepathSync ? npmUriForFilepathSync(rawFilepath) : null
                 if (npmUri) {
                     // Strip file extension from URI for consistency
                     frame.fileUri = npmUri.replace(/\.(ts|tsx|js|jsx)$/, '')

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

@@ -263,6 +263,7 @@ All value types accept a `value` in their definition. `undefined` means "no defa
 | `Function` | `api.name(...args)` | `function(this, ...args)` | Callable method. Bound to self proxy. |
 | `GetterFunction` | `api.name` (no parens) | `function(this)` | Lazy getter. Evaluated on each access (unless memoized). |
 | `SetterFunction` | `api.name = value` | `function(this, value)` | Triggered on assignment. Enables validation/transformation logic. |
+| `ProxyFunction` | `api.name(...args)` | `{ target(this), invoke(this, ...args) }` | Wraps a target function with argument transformation. See below. |
 
 All function types are bound to a **self proxy** where:
 - `this.<prop>` resolves through: self → encapsulatedApi → extendedCapsuleApi
@@ -290,6 +291,31 @@ Applies to `Function` and `GetterFunction`. Added as a sibling to `type` and `va
 
 Memoize caches are scoped per spine contract capsule instance and cleared automatically when `run()` completes.
 
+#### ProxyFunction
+
+`ProxyFunction` wraps calling a target function with argument transformation. Its `value` is an object with two methods:
+
+- **`target(this)`** — resolves the function to call (bound to self proxy)
+- **`invoke(this, ...args)`** — transforms the caller's arguments before passing to target (bound to self proxy, may be async)
+
+```ts
+{
+    type: CapsulePropertyTypes.ProxyFunction,
+    value: {
+        target() { return this.service.fetchData },           // resolve target fn
+        async invoke(pathname: string) {                      // transform args
+            const origin = this.origin
+            return { url: `http://${origin}${pathname}`, headers: { Host: origin } }
+        }
+    }
+}
+```
+
+When `api.name(...args)` is called:
+1. `invoke(...args)` runs with self proxy as `this`, returning transformed args
+2. `target()` runs with self proxy as `this`, returning the function to call
+3. The target function is called with the transformed args (awaited if `invoke` returns a promise)
+
 ### Mapping
 
 `Mapping` composes another capsule as a sub-component.
@@ -382,13 +408,13 @@ A capsule can inherit properties from a parent capsule:
 - `this.self` in a parent function returns the parent's own values (`ownSelf`), not the merged context.
 - Multiple capsules can extend the same parent — each gets a separate parent instance with its own `self`.
 
-### Spine Contracts: Static.v0 vs Membrane.v0
+### Spine Contracts: Static vs Membrane
 
 Both implement the same property mapping logic. The difference is observability.
 
-**Static.v0** — direct property assignment. No interception. Minimal overhead.
+**Static** — direct property assignment. No interception. Minimal overhead.
 
-**Membrane.v0** — wraps the API in proxies that emit events for every property access:
+**Membrane** — wraps the API in proxies that emit events for every property access:
 
 | Event | Emitted When | Payload |
 |---|---|---|