@stream44.studio/encapsulate 0.2.0-rc.2 → 0.2.0-rc.4

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

@@ -1,5 +1,8 @@
 import { CapsulePropertyTypes, join } from "../../encapsulate"
 
+// Type for capsule instance registry - scoped per spine contract instance
+export type CapsuleInstanceRegistry = Map<string, any>
+
 export class ContractCapsuleInstanceFactory {
 
     protected spineContractUri: string
@@ -10,16 +13,24 @@ export class ContractCapsuleInstanceFactory {
     protected importCapsule?: (filepath: string) => Promise<any>
     protected spineFilesystemRoot?: string
     protected freezeCapsule?: (capsule: any) => Promise<any>
+    protected instanceRegistry?: CapsuleInstanceRegistry
+    protected extendedCapsuleInstance?: any
+    protected ownSelf?: any
+    protected runtimeSpineContracts?: Record<string, any>
 
-    constructor({ spineContractUri, capsule, self, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule }: { spineContractUri: string, capsule: any, self: any, encapsulatedApi: Record<string, any>, resolve?: (uri: string, parentFilepath: string) => Promise<string>, importCapsule?: (filepath: string) => Promise<any>, spineFilesystemRoot?: string, freezeCapsule?: (capsule: any) => Promise<any> }) {
+    constructor({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance, runtimeSpineContracts }: { spineContractUri: string, capsule: any, self: any, ownSelf?: any, encapsulatedApi: Record<string, any>, resolve?: (uri: string, parentFilepath: string) => Promise<string>, importCapsule?: (filepath: string) => Promise<any>, spineFilesystemRoot?: string, freezeCapsule?: (capsule: any) => Promise<any>, instanceRegistry?: CapsuleInstanceRegistry, extendedCapsuleInstance?: any, runtimeSpineContracts?: Record<string, any> }) {
         this.spineContractUri = spineContractUri
         this.capsule = capsule
         this.self = self
+        this.ownSelf = ownSelf
         this.encapsulatedApi = encapsulatedApi
         this.resolve = resolve
         this.importCapsule = importCapsule
         this.spineFilesystemRoot = spineFilesystemRoot
         this.freezeCapsule = freezeCapsule
+        this.instanceRegistry = instanceRegistry
+        this.extendedCapsuleInstance = extendedCapsuleInstance
+        this.runtimeSpineContracts = runtimeSpineContracts
     }
 
     async mapProperty({ overrides, options, property }: { overrides: any, options: any, property: any }) {
@@ -59,7 +70,11 @@ export class ContractCapsuleInstanceFactory {
             if (!this.spineFilesystemRoot) throw new Error(`'spineFilesystemRoot' not set!`)
             if (!this.importCapsule) throw new Error(`'importCapsule' not set!`)
 
-            const parentPath = join(this.spineFilesystemRoot, this.capsule.cst.source.moduleFilepath)
+            // Use encapsulateOptions.moduleFilepath (always available) instead of cst.source.moduleFilepath
+            const moduleFilepath = this.capsule.encapsulateOptions?.moduleFilepath || this.capsule.cst?.source?.moduleFilepath
+            if (!moduleFilepath) throw new Error(`'moduleFilepath' not available on capsule!`)
+
+            const parentPath = join(this.spineFilesystemRoot, moduleFilepath)
             const filepath = await this.resolve(property.definition.value, parentPath)
             mappedCapsule = await this.importCapsule(filepath)
         } else if (
@@ -121,9 +136,63 @@ export class ContractCapsuleInstanceFactory {
         const mappedCapsule = await this.resolveMappedCapsule({ property })
         const constants = await this.extractConstants({ mappedCapsule })
 
-        const mappingOptions = await property.definition.options?.({
-            constants
-        })
+        // delegateOptions is set by encapsulate.ts for property contract delegates
+        // options can be a function or an object for regular mappings
+        const mappingOptions = property.definition.delegateOptions
+            || (typeof property.definition.options === 'function'
+                ? await property.definition.options({ constants })
+                : property.definition.options)
+
+        // Check for existing instance in registry - reuse if available when no options
+        // Pre-registration with null allows parent capsules to "claim" a slot before child capsules process
+        const capsuleName = mappedCapsule.encapsulateOptions?.capsuleName
+
+        if (capsuleName && this.instanceRegistry) {
+            if (this.instanceRegistry.has(capsuleName)) {
+                const existingEntry = this.instanceRegistry.get(capsuleName)
+
+                // Only reuse if current mapping has no options
+                if (!mappingOptions) {
+                    // Use deferred proxy that resolves from registry when accessed
+                    // Works for both null (pre-registered) and actual instances
+                    const apiTarget = this.getApiTarget({ property })
+                    const registry = this.instanceRegistry
+                    apiTarget[property.name] = new Proxy({} as any, {
+                        get: (_target: any, apiProp: string | symbol) => {
+                            if (typeof apiProp === 'symbol') return undefined
+                            const resolvedInstance = registry.get(capsuleName)
+                            if (!resolvedInstance) {
+                                throw new Error(`Capsule instance not yet resolved: ${capsuleName}`)
+                            }
+                            // Access through .api if it exists (for capsule instances with getters)
+                            if (resolvedInstance.api && apiProp in resolvedInstance.api) {
+                                return resolvedInstance.api[apiProp]
+                            }
+                            return resolvedInstance[apiProp]
+                        }
+                    })
+                    this.self[property.name] = new Proxy({} as any, {
+                        get: (_target, prop) => {
+                            if (typeof prop === 'symbol') return undefined
+                            const resolvedInstance = registry.get(capsuleName)
+                            if (!resolvedInstance) {
+                                throw new Error(`Capsule instance not yet resolved: ${capsuleName}`)
+                            }
+                            const value = resolvedInstance.api?.[prop] ?? resolvedInstance[prop]
+                            if (value && typeof value === 'object' && value.api) {
+                                return value.api
+                            }
+                            return value
+                        }
+                    })
+                    return
+                }
+                // If current mapping has options, fall through to create new instance
+            } else {
+                // Pre-register as null to claim the slot for this capsule
+                this.instanceRegistry.set(capsuleName, null)
+            }
+        }
 
         // Transform overrides if this mapping has a propertyContractDelegate
         let mappedOverrides = overrides
@@ -152,9 +221,16 @@ export class ContractCapsuleInstanceFactory {
         const apiTarget = this.getApiTarget({ property })
         const mappedInstance = await mappedCapsule.makeInstance({
             overrides: mappedOverrides,
-            options: mappingOptions
+            options: mappingOptions,
+            runtimeSpineContracts: this.runtimeSpineContracts
         })
 
+        // Register the instance (replaces null pre-registration marker)
+        // Always register to make instance available for child capsules with deferred proxies
+        if (capsuleName && this.instanceRegistry) {
+            this.instanceRegistry.set(capsuleName, mappedInstance)
+        }
+
         apiTarget[property.name] = mappedInstance
         // Use proxy to unwrap .api for this.self so internal references work
         this.self[property.name] = mappedInstance.api ? new Proxy(mappedInstance.api, {
@@ -186,24 +262,33 @@ export class ContractCapsuleInstanceFactory {
 
     protected mapLiteralProperty({ property }: { property: any }) {
         const apiTarget = this.getApiTarget({ property })
-        const value = typeof this.self[property.name] !== 'undefined'
-            ? this.self[property.name]
+        // Use existing value from self if defined, otherwise use property definition
+        // This preserves values set by child capsules in the extends chain
+        const existingValue = this.self[property.name]
+        const value = existingValue !== undefined
+            ? existingValue
             : property.definition.value
 
         // Assign to both apiTarget and self so getter functions can access via this
         apiTarget[property.name] = value
-        this.self[property.name] = value
+        // Only update self if it wasn't already set (preserve child values)
+        if (existingValue === undefined) {
+            this.self[property.name] = value
+        }
     }
 
-    protected mapFunctionProperty({ property }: { property: any }) {
-        const apiTarget = this.getApiTarget({ property })
-
-        // Create a proxy for this.self that intercepts property access
-        // Prefer this.self (which has unwrapped APIs) over encapsulatedApi
-        const selfProxy = new Proxy(this.self, {
+    protected createSelfProxy() {
+        const extendedApi = this.extendedCapsuleInstance?.api
+        const ownSelf = this.ownSelf
+        return new Proxy(this.self, {
             get: (target: any, prop: string | symbol) => {
                 if (typeof prop === 'symbol') return target[prop]
 
+                // 'self' property returns ownSelf (only this capsule's own properties)
+                if (prop === 'self' && ownSelf) {
+                    return ownSelf
+                }
+
                 // First check if the property exists in target (this.self)
                 if (prop in target) {
                     return target[prop]
@@ -214,36 +299,26 @@ export class ContractCapsuleInstanceFactory {
                     return this.encapsulatedApi[prop]
                 }
 
+                // Fall back to extended capsule's API
+                if (extendedApi && prop in extendedApi) {
+                    return extendedApi[prop]
+                }
+
                 return undefined
             }
         })
+    }
 
+    protected mapFunctionProperty({ property }: { property: any }) {
+        const apiTarget = this.getApiTarget({ property })
+        const selfProxy = this.createSelfProxy()
         apiTarget[property.name] = property.definition.value.bind(selfProxy)
     }
 
     protected mapGetterFunctionProperty({ property }: { property: any }) {
         const apiTarget = this.getApiTarget({ property })
         const getterFn = property.definition.value
-
-        // Create a proxy for this.self that intercepts property access
-        // Prefer this.self (which has unwrapped APIs) over encapsulatedApi
-        const selfProxy = new Proxy(this.self, {
-            get: (target: any, prop: string | symbol) => {
-                if (typeof prop === 'symbol') return target[prop]
-
-                // First check if the property exists in target (this.self)
-                if (prop in target) {
-                    return target[prop]
-                }
-
-                // Fall back to encapsulatedApi
-                if (prop in this.encapsulatedApi) {
-                    return this.encapsulatedApi[prop]
-                }
-
-                return undefined
-            }
-        })
+        const selfProxy = this.createSelfProxy()
 
         // Define a lazy getter that calls the function only when accessed with proper this context
         Object.defineProperty(apiTarget, property.name, {
@@ -253,6 +328,18 @@ export class ContractCapsuleInstanceFactory {
             enumerable: true,
             configurable: true
         })
+
+        // Also define the getter on ownSelf so this.self.propertyName works for getter functions
+        // This ensures this.self accesses the getter, not a raw value
+        if (this.ownSelf) {
+            Object.defineProperty(this.ownSelf, property.name, {
+                get: () => {
+                    return getterFn.call(selfProxy)
+                },
+                enumerable: true,
+                configurable: true
+            })
+        }
     }
 
     async freeze(options: any): Promise<any> {
@@ -266,18 +353,25 @@ export class ContractCapsuleInstanceFactory {
 
 export function CapsuleSpineContract({ freezeCapsule, resolve, importCapsule, spineFilesystemRoot }: { freezeCapsule?: (capsule: any) => Promise<any>, resolve?: (uri: string, parentFilepath: string) => Promise<string>, importCapsule?: (filepath: string) => Promise<any>, spineFilesystemRoot?: string } = {}) {
 
+    const instanceRegistry: CapsuleInstanceRegistry = new Map()
+
     return {
         '#': CapsuleSpineContract['#'],
-        makeContractCapsuleInstance: ({ spineContractUri, capsule, self, encapsulatedApi }: { spineContractUri: string, capsule: any, self: any, encapsulatedApi: Record<string, any> }) => {
+        instanceRegistry,
+        makeContractCapsuleInstance: ({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, extendedCapsuleInstance, runtimeSpineContracts }: { spineContractUri: string, capsule: any, self: any, ownSelf?: any, encapsulatedApi: Record<string, any>, extendedCapsuleInstance?: any, runtimeSpineContracts?: Record<string, any> }) => {
             return new ContractCapsuleInstanceFactory({
                 spineContractUri,
                 capsule,
                 self,
+                ownSelf,
                 encapsulatedApi,
                 resolve,
                 importCapsule,
                 spineFilesystemRoot,
-                freezeCapsule
+                freezeCapsule,
+                instanceRegistry,
+                extendedCapsuleInstance,
+                runtimeSpineContracts
             })
         },
         hydrate: ({ capsuleSnapshot }: { capsuleSnapshot: any }): any => {

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

@@ -1,5 +1,6 @@
 import { join, dirname } from 'path'
 import { writeFile, mkdir, readFile, stat } from 'fs/promises'
+import { createRequire } from 'module'
 import { Spine, SpineRuntime, CapsulePropertyTypes, makeImportStack, merge } from "../encapsulate"
 import { StaticAnalyzer } from "../../src/static-analyzer.v0"
 import { CapsuleModuleProjector } from "../../src/capsule-projectors/CapsuleModuleProjector.v0"
@@ -7,8 +8,49 @@ import { CapsuleModuleProjector } from "../../src/capsule-projectors/CapsuleModu
 
 export { merge }
 
-// TODO: Make portable so we can run on other runtimes
-const resolve = Bun.resolve
+// Custom resolve function that uses createRequire for proper package resolution
+async function resolve(uri: string, fromPath: string, spineRoot?: string): Promise<string> {
+    try {
+        // Create a require function from the parent file's directory
+        const require = createRequire(fromPath)
+        const result = require.resolve(uri)
+        return result
+    } catch (error: any) {
+        // If standard resolution fails and uri is a scoped package, try resolving
+        // the package root first, then append the subpath relative to it.
+        if (uri.startsWith('@')) {
+            const match = uri.match(/^(@[^/]+\/[^/]+)\/(.+)$/)
+            if (match) {
+                const [, packageName, subpath] = match
+                try {
+                    const require = createRequire(fromPath)
+                    const packageJsonPath = require.resolve(join(packageName, 'package.json'))
+                    const packageRoot = dirname(packageJsonPath)
+                    const fsPath = join(packageRoot, subpath + '.ts')
+                    await stat(fsPath)
+                    return fsPath
+                } catch {
+                    // Fall through
+                }
+            }
+
+            // Fallback: transform @scope/package/path to scope/packages/package/path relative to spineRoot
+            if (spineRoot) {
+                const transformed = uri.replace(/^@([^/]+)\/([^/]+)\/(.+)$/, '$1/packages/$2/$3')
+                const fsPath = join(spineRoot, transformed + '.ts')
+                try {
+                    await stat(fsPath)
+                    return fsPath
+                } catch {
+                    // File doesn't exist, fall through to Bun.resolve
+                }
+            }
+        }
+
+        // Final fallback to Bun.resolve
+        return await Bun.resolve(uri, fromPath)
+    }
+}
 
 
 export async function CapsuleSpineFactory({
@@ -67,10 +109,10 @@ export async function CapsuleSpineFactory({
         resolve: async (uri: string, parentFilepath: string) => {
             // For relative paths, join with parent directory first
             if (/^\.\.?\//.test(uri)) {
-                return await resolve(join(parentFilepath, '..', uri), spineFilesystemRoot)
+                return await resolve(join(parentFilepath, '..', uri), spineFilesystemRoot, spineFilesystemRoot)
             }
-            // For absolute/package paths, use Bun.resolve directly
-            return await resolve(uri, parentFilepath)
+            // For absolute/package paths, use custom resolve with spine root
+            return await resolve(uri, parentFilepath, spineFilesystemRoot)
         },
         importCapsule: async (filepath: string) => {
             const shortPath = filepath.replace(/^.*\/genesis\//, '')
@@ -126,11 +168,15 @@ export async function CapsuleSpineFactory({
 
                 let snapshotValues = {}
 
+                // Create a new set per freezeCapsule call to track circular dependencies within this projection tree
+                const projectingCapsules = new Set<string>()
+
                 const projected = await projector.projectCapsule({
                     capsule,
                     capsules,
                     snapshotValues,
-                    spineContractUri
+                    spineContractUri,
+                    projectingCapsules
                 })
 
                 return snapshotValues
@@ -281,6 +327,7 @@ export async function CapsuleSpineFactory({
         run,
         freeze,
         loadCapsule,
+        spineContractInstances, // Expose for testing
         hoistSnapshot: async ({ snapshot }: { snapshot: any }) => {
 
             timing?.recordMajor('HOIST SNAPSHOT: START')