Published using @Stream44 Studio

Signed-off-by: Christoph <christoph@christoph.diy>

Author: cadorn

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-encapsulate: Object encapsulation & mapping system with runtime kernel for TypeScript
+encapsulate: Object encapsulation & mapping library with runtime kernel for TypeScript
 
 Copyright 2026 Christoph Dorn - https://Christoph.diy
 

package.json

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

src/encapsulate.ts

@@ -55,7 +55,8 @@ type TCapsuleMakeInstanceOptions = {
         moduleFilepath: string
     },
     parentCapsuleSourceUriLineRefInstanceId?: string,
-    sit?: { capsuleInstances: Record<string, { capsuleName: string, capsuleSourceUriLineRef: string, parentCapsuleSourceUriLineRefInstanceId: string }> }
+    sit?: { capsuleInstances: Record<string, { capsuleName: string, capsuleSourceUriLineRef: string, parentCapsuleSourceUriLineRefInstanceId: string }> },
+    skipCache?: boolean
 }
 
 type TCapsule = {
@@ -554,13 +555,15 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
         encapsulateOptions,
         cst,
         crt: crts?.[capsuleSourceLineRef],
-        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts, sharedSelf, rootCapsule, parentCapsuleSourceUriLineRefInstanceId, sit }: TCapsuleMakeInstanceOptions = {}) => {
+        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts, sharedSelf, rootCapsule, parentCapsuleSourceUriLineRefInstanceId, sit, skipCache }: TCapsuleMakeInstanceOptions = {}) => {
 
             // Create cache key based on parameters
             // When sharedSelf is provided, we must NOT cache because each extending capsule
             // needs its own instance with its own 'this' context (sharedSelf).
             // This is critical for the pattern where multiple structs extend the same parent.
-            const cacheKey = sharedSelf ? null : JSON.stringify({
+            // When skipCache is true (property contract delegates like structs/Capsule),
+            // each parent capsule must get its own unique instance.
+            const cacheKey = (sharedSelf || skipCache) ? null : JSON.stringify({
                 overrides,
                 options,
                 hasRuntimeContracts: !!runtimeSpineContracts

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

@@ -149,9 +149,11 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
 
         // Check for existing instance in registry - reuse if available (regardless of options)
         // Pre-registration with null allows parent capsules to "claim" a slot before child capsules process
+        // Property contract delegates (structs) always get a fresh instance per parent capsule
         const capsuleName = mappedCapsule.encapsulateOptions?.capsuleName
+        const isCapsuleStruct = property.definition.propertyContractDelegate === '#@stream44.studio/encapsulate/structs/Capsule'
 
-        if (capsuleName && this.instanceRegistry) {
+        if (capsuleName && this.instanceRegistry && !isCapsuleStruct) {
             if (this.instanceRegistry.has(capsuleName)) {
                 const existingEntry = this.instanceRegistry.get(capsuleName)
 
@@ -275,12 +277,16 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
             overrides: mappedOverrides,
             options: ownMappingOptions,
             runtimeSpineContracts: this.runtimeSpineContracts,
-            rootCapsule: this.capsuleInstance?.rootCapsule
+            rootCapsule: this.capsuleInstance?.rootCapsule,
+            parentCapsuleSourceUriLineRefInstanceId: this.capsuleInstance?.capsuleSourceUriLineRefInstanceId,
+            sit: this.capsuleInstance?.sit,
+            skipCache: isCapsuleStruct
         })
 
         // Register the instance (replaces null pre-registration marker)
         // Always register to make instance available for child capsules with deferred proxies
-        if (capsuleName && this.instanceRegistry) {
+        // Property contract delegates skip registry (each parent gets its own instance)
+        if (capsuleName && this.instanceRegistry && !isCapsuleStruct) {
             this.instanceRegistry.set(capsuleName, mappedCapsuleInstance)
         }
 

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

@@ -206,9 +206,11 @@ export class ContractCapsuleInstanceFactory {
 
         // 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
+        // Property contract delegates (structs) always get a fresh instance per parent capsule
         const capsuleName = mappedCapsule.encapsulateOptions?.capsuleName
+        const isCapsuleStruct = property.definition.propertyContractDelegate === '#@stream44.studio/encapsulate/structs/Capsule'
 
-        if (capsuleName && this.instanceRegistry) {
+        if (capsuleName && this.instanceRegistry && !isCapsuleStruct) {
             if (this.instanceRegistry.has(capsuleName)) {
                 const existingEntry = this.instanceRegistry.get(capsuleName)
 
@@ -315,12 +317,14 @@ export class ContractCapsuleInstanceFactory {
             runtimeSpineContracts: this.runtimeSpineContracts,
             rootCapsule: this.capsuleInstance?.rootCapsule,
             parentCapsuleSourceUriLineRefInstanceId: this.capsuleInstance?.capsuleSourceUriLineRefInstanceId,
-            sit: this.capsuleInstance?.sit
+            sit: this.capsuleInstance?.sit,
+            skipCache: isCapsuleStruct
         })
 
         // Register the instance (replaces null pre-registration marker)
         // Always register to make instance available for child capsules with deferred proxies
-        if (capsuleName && this.instanceRegistry) {
+        // Property contract delegates skip registry (each parent gets its own instance)
+        if (capsuleName && this.instanceRegistry && !isCapsuleStruct) {
             this.instanceRegistry.set(capsuleName, mappedInstance)
         }
 

src/spine-factories/CapsuleSpineFactory.v0.ts

@@ -642,33 +642,28 @@ export async function CapsuleSpineFactory({
                     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
-                            }
+                    // 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 })
-                                }
+                        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 })
                             }
                         }
                     }

tests/10-CapsuleSpines/main.test.ts

@@ -190,6 +190,25 @@ describe('CapsuleSpine Linking Features', () => {
         // from capsules without options (service1, service2 reuse Service)
         expect(instanceIds.length).toBeGreaterThanOrEqual(expectedCapsules.length)
 
+        // Every capsule instance that declares structs/Capsule should get its own
+        // structs/Capsule instance (just like a property contract mapping).
+        // The structs/Capsule instance should NOT be shared across parents.
+        const structsCapsuleInstances = instanceEntries.filter(
+            ([, e]) => (e as any).capsuleName === '@stream44.studio/encapsulate/structs/Capsule'
+        )
+        // Count non-structs/Capsule instances — each one declares structs/Capsule,
+        // so there should be one structs/Capsule instance per parent capsule instance
+        const nonStructInstances = instanceEntries.filter(
+            ([, e]) => (e as any).capsuleName !== '@stream44.studio/encapsulate/structs/Capsule'
+        )
+        expect(structsCapsuleInstances.length).toBe(nonStructInstances.length)
+
+        // Each structs/Capsule instance must have a unique parent
+        const structsCapsuleParents = structsCapsuleInstances.map(
+            ([, e]) => (e as any).parentCapsuleSourceUriLineRefInstanceId
+        )
+        expect(new Set(structsCapsuleParents).size).toBe(structsCapsuleParents.length)
+
         // Verify membrane events contain expected properties
         expect(membraneEvents.length).toBeGreaterThan(0)