@stream44.studio/encapsulate 0.4.0-rc.11 → 0.4.0-rc.12

package/.dockerignore

@@ -0,0 +1,3 @@
+node_modules
+.o
+.DS_Store

package/.github/workflows/test.yaml

@@ -1,4 +1,4 @@
-name: Run Tests
+name: Tests
 
 on:
   push:

package/Dockerfile

@@ -0,0 +1,15 @@
+FROM oven/bun:1
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json bun.lock* ./
+
+# Install dependencies
+RUN bun install
+
+# Copy source code
+COPY . .
+
+# Run tests
+CMD ["bun", "test"]

package/README.md

@@ -4,6 +4,8 @@
 
 ⚠️ **Disclaimer:** Under active development. Code has not been audited, APIs and interfaces are subject to change.
 
+[![Tests](https://github.com/Stream44/encapsulate/actions/workflows/tests.yaml/badge.svg)](https://github.com/Stream44/encapsulate/actions/workflows/tests.yaml?query=branch%3Amain)
+
 encapsulate
 ===
 
@@ -27,6 +29,12 @@ Notes
 - The first spine contract is defined and implemented here: [src/spine-contracts/CapsuleSpineContract.v0/](src/spine-contracts/CapsuleSpineContract.v0/)
 - Projector reference implementations are here: [github.com/Stream44/ink-component-projector](https://github.com/Stream44/ink-component-projector)
 
+Roadmap
+---
+
+- [ ] Document [src/spine-contracts/CapsuleSpineContract.v0/](src/spine-contracts/CapsuleSpineContract.v0/)
+- [ ] Private properties
+
 
 Provenance
 ===
@@ -45,4 +53,4 @@ Repository DID: `did:repo:412cd408c657737343a6089ed6d5f0668a8bfb05`
   </tr>
 </table>
 
-(c) 2026 [Christoph.diy](https://christoph.diy) • Code: `MIT` • Text: `CC-BY` • Created with [Stream44.Studio](https://Stream44.Studio)
+(c) 2026 [Christoph.diy](https://christoph.diy) • Code: `BSD-2-Clause-Patent` • Text: `CC-BY` • Created with [Stream44.Studio](https://Stream44.Studio)

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@stream44.studio/encapsulate",
-    "version": "0.4.0-rc.11",
-    "license": "MIT",
+    "version": "0.4.0-rc.12",
+    "license": "BSD-2-Clause-Patent",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/Stream44/encapsulate.git"
@@ -17,7 +17,8 @@
         "./structs/Capsule": "./structs/Capsule.ts"
     },
     "scripts": {
-        "test": "bun test"
+        "test": "bun test",
+        "test:docker": "./scripts/test-docker.sh"
     },
     "dependencies": {
         "typescript": "^5.9.3",

package/scripts/test-docker.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_DIR="$(dirname "$SCRIPT_DIR")"
+
+cd "$PACKAGE_DIR"
+
+IMAGE_NAME="encapsulate-test"
+
+echo "Building Docker image..."
+docker build -t "$IMAGE_NAME" .
+
+echo "Running tests in Docker..."
+docker run --rm "$IMAGE_NAME"
+
+echo "Tests completed successfully!"

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

@@ -457,24 +457,22 @@ export function CapsuleModuleProjector({
         if (capsule.cst.source.capsuleName) {
             // Use capsuleName as the path - NO line number
             let capsuleNamePath = capsule.cst.source.capsuleName
-            // Strip @ prefix
             if (capsuleNamePath.startsWith('@')) {
                 capsuleNamePath = capsuleNamePath.substring(1)
             }
             // Just capsuleName + extension, NO line number
-            projectedPath = `.~caps/${capsuleNamePath}${sourceExtension}`
+            projectedPath = `.~o/encapsulate.dev/caps/${capsuleNamePath}${sourceExtension}`
         } else if (capsule.cst.capsuleSourceUriLineRef) {
             // Use capsuleSourceUriLineRef which already has format: uri:line
             let uriPath = capsule.cst.capsuleSourceUriLineRef
-            // Strip @ prefix
             if (uriPath.startsWith('@')) {
                 uriPath = uriPath.substring(1)
             }
             // Add extension after the line number: uri:line.ext
-            projectedPath = `.~caps/${uriPath}${sourceExtension}`
+            projectedPath = `.~o/encapsulate.dev/caps/${uriPath}${sourceExtension}`
         } else {
             // Fallback to hash if neither exists
-            projectedPath = `.~caps/${capsule.cst.capsuleSourceNameRefHash.substring(0, 8)}${sourceExtension}`
+            projectedPath = `.~o/encapsulate.dev/caps/${capsule.cst.capsuleSourceNameRefHash.substring(0, 8)}${sourceExtension}`
         }
 
         return {
@@ -826,16 +824,20 @@ export function CapsuleModuleProjector({
                     const refTyped = ref as any
                     if (refTyped.type === 'capsule') {
                         const snapshot = await buildCapsuleSnapshotForReference(refTyped, capsules, spineContractUri)
-                        const capsuleName = snapshot.spineContracts?.['#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0']?.['#@stream44.studio/encapsulate/structs/Capsule']?.capsuleName
-                        const projectedFilepath = snapshot.spineContracts?.['#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0']?.['#@stream44.studio/encapsulate/structs/Capsule']?.projectedCapsuleFilepath
+
+                        // Use dynamic spineContractUri instead of hardcoded URI
+                        const contractData = snapshot.spineContracts?.[spineContractUri]
+                        const structKey = Object.keys(contractData || {}).find(k => k.includes('/structs/Capsule'))
+                        const capsuleName = structKey ? contractData[structKey]?.capsuleName : undefined
+                        const projectedFilepath = structKey ? contractData[structKey]?.projectedCapsuleFilepath : undefined
 
                         if (capsuleName && projectedFilepath) {
                             allCapsuleUris.add(capsuleName)
 
                             // Build import path from projected filepath
                             const importName = `_capsule_${capsuleName.replace(/[^a-zA-Z0-9]/g, '_')}`
-                            // Remove .~caps/ prefix and strip extension
-                            const importPath = projectedFilepath.replace(/^\.~caps\//, '').replace(/\.(ts|tsx)$/, '')
+                            // Remove .~o/encapsulate.dev/caps/ prefix and strip extension
+                            const importPath = projectedFilepath.replace(/^\.~o\/encapsulate\.dev\/caps\//, '').replace(/\.(ts|tsx)$/, '')
 
                             capsuleDeps.push({ uri: capsuleName, importName, importPath })
                         }
@@ -843,13 +845,13 @@ export function CapsuleModuleProjector({
                 }
 
                 // Generate static imports for all capsule dependencies
-                // Compute relative path from projected file to .~caps directory
+                // Compute relative path from projected file to caps directory
                 let importPrefix: string
                 if (capsuleModuleProjectionPackage) {
                     importPrefix = capsuleModuleProjectionPackage
                 } else {
                     const projectedFileDir = dirname(filepath)
-                    const capsDir = '.~caps'
+                    const capsDir = '.~o/encapsulate.dev/caps'
                     const relativePathToCaps = relative(projectedFileDir, capsDir)
                     importPrefix = relativePathToCaps.startsWith('.') ? relativePathToCaps : './' + relativePathToCaps
                 }
@@ -983,7 +985,9 @@ export default function({ onMembraneEvent }: { onMembraneEvent?: (event: any) =>
                 const refTyped = ref as any
                 if (refTyped.type === 'capsule') {
                     const snapshot = await buildCapsuleSnapshotForReference(refTyped, capsules, spineContractUri)
-                    const capsuleName = snapshot.spineContracts?.['#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0']?.['#@stream44.studio/encapsulate/structs/Capsule']?.capsuleName
+                    const contractData = snapshot.spineContracts?.[spineContractUri]
+                    const structKey = Object.keys(contractData || {}).find(k => k.includes('/structs/Capsule'))
+                    const capsuleName = structKey ? contractData[structKey]?.capsuleName : undefined
                     if (capsuleName) {
                         allCapsuleUris.add(capsuleName)
                     }
@@ -1007,13 +1011,15 @@ export default function({ onMembraneEvent }: { onMembraneEvent?: (event: any) =>
 
                 if (capsuleRef) {
                     const snapshot = await buildCapsuleSnapshotForReference(capsuleRef, capsules, spineContractUri)
-                    const projectedFilepath = snapshot.spineContracts?.['#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0']?.['#@stream44.studio/encapsulate/structs/Capsule']?.projectedCapsuleFilepath
+                    const contractData = snapshot.spineContracts?.[spineContractUri]
+                    const structKey = Object.keys(contractData || {}).find(k => k.includes('/structs/Capsule'))
+                    const projectedFilepath = structKey ? contractData[structKey]?.projectedCapsuleFilepath : undefined
 
                     if (projectedFilepath) {
                         // Build import path from projected filepath
                         const importName = `_capsule_${uri.replace(/[^a-zA-Z0-9]/g, '_')}`
-                        // Remove .~caps/ prefix and strip extension
-                        const importPath = projectedFilepath.replace(/^\.~caps\//, '').replace(/\.(ts|tsx)$/, '')
+                        // Remove .~o/encapsulate.dev/caps/ prefix and strip extension
+                        const importPath = projectedFilepath.replace(/^\.~o\/encapsulate\.dev\/caps\//, '').replace(/\.(ts|tsx)$/, '')
 
                         capsuleDeps.push({ uri, importName, importPath })
                     }
@@ -1021,13 +1027,13 @@ export default function({ onMembraneEvent }: { onMembraneEvent?: (event: any) =>
             }
 
             // Generate static imports for all capsule dependencies
-            // Compute relative path from projected file to .~caps directory
+            // Compute relative path from projected file to caps directory
             let importPrefix: string
             if (capsuleModuleProjectionPackage) {
                 importPrefix = capsuleModuleProjectionPackage
             } else {
                 const projectedFileDir = dirname(filepath)
-                const capsDir = '.~caps'
+                const capsDir = '.~o/encapsulate.dev/caps'
                 const relativePathToCaps = relative(projectedFileDir, capsDir)
                 importPrefix = relativePathToCaps.startsWith('.') ? relativePathToCaps : './' + relativePathToCaps
             }
@@ -1321,7 +1327,9 @@ ${defaultExport}
                         const refTyped = ref as any
                         if (refTyped.type === 'capsule') {
                             const snapshot = await buildCapsuleSnapshotForReference(refTyped, capsules, spineContractUri)
-                            const capsuleName = snapshot.spineContracts?.['#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0']?.['#@stream44.studio/encapsulate/structs/Capsule']?.capsuleName
+                            const contractData = snapshot.spineContracts?.[spineContractUri]
+                            const structKey = Object.keys(contractData || {}).find(k => k.includes('/structs/Capsule'))
+                            const capsuleName = structKey ? contractData[structKey]?.capsuleName : undefined
                             if (capsuleName) {
                                 allMappedCapsuleUris.add(capsuleName)
                             }
@@ -1332,19 +1340,19 @@ ${defaultExport}
                     const mappedCapsuleDeps: Array<{ uri: string, importName: string, importPath: string }> = []
                     for (const uri of allMappedCapsuleUris) {
                         const importName = `_capsule_${uri.replace(/[^a-zA-Z0-9]/g, '_')}`
-                        // Strip leading @ from URI to avoid double @ in import paths
+                        // Strip leading @ to match caps filesystem paths
                         const importPath = uri.startsWith('@') ? uri.substring(1) : uri
                         mappedCapsuleDeps.push({ uri, importName, importPath })
                     }
 
                     // Generate static imports for all capsule dependencies
-                    // Compute relative path from projected file to .~caps directory
+                    // Compute relative path from projected file to caps directory
                     let importPrefix: string
                     if (capsuleModuleProjectionPackage) {
                         importPrefix = capsuleModuleProjectionPackage
                     } else {
                         const projectedFileDir = dirname(mapped.projectionPath)
-                        const capsDir = '.~caps'
+                        const capsDir = '.~o/encapsulate.dev/caps'
                         const relativePathToCaps = relative(projectedFileDir, capsDir)
                         importPrefix = relativePathToCaps.startsWith('.') ? relativePathToCaps : './' + relativePathToCaps
                     }
@@ -1475,7 +1483,9 @@ export default function({ onMembraneEvent }: { onMembraneEvent?: (event: any) =>
                     const refTyped = ref as any
                     if (refTyped.type === 'capsule') {
                         const snapshot = await buildCapsuleSnapshotForReference(refTyped, capsules, spineContractUri)
-                        const capsuleName = snapshot.spineContracts?.['#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0']?.['#@stream44.studio/encapsulate/structs/Capsule']?.capsuleName
+                        const contractData = snapshot.spineContracts?.[spineContractUri]
+                        const structKey = Object.keys(contractData || {}).find(k => k.includes('/structs/Capsule'))
+                        const capsuleName = structKey ? contractData[structKey]?.capsuleName : undefined
                         if (capsuleName) {
                             allMappedCapsuleUris.add(capsuleName)
                         }
@@ -1486,19 +1496,19 @@ export default function({ onMembraneEvent }: { onMembraneEvent?: (event: any) =>
                 const mappedCapsuleDeps: Array<{ uri: string, importName: string, importPath: string }> = []
                 for (const uri of allMappedCapsuleUris) {
                     const importName = `_capsule_${uri.replace(/[^a-zA-Z0-9]/g, '_')}`
-                    // Strip leading @ from URI to avoid double @ in import paths
+                    // Strip leading @ to match caps filesystem paths
                     const importPath = uri.startsWith('@') ? uri.substring(1) : uri
                     mappedCapsuleDeps.push({ uri, importName, importPath })
                 }
 
                 // Generate static imports for all capsule dependencies
-                // Compute relative path from projected file to .~caps directory
+                // Compute relative path from projected file to caps directory
                 let importPrefix: string
                 if (capsuleModuleProjectionPackage) {
                     importPrefix = capsuleModuleProjectionPackage
                 } else {
                     const projectedFileDir = dirname(mapped.projectionPath)
-                    const capsDir = '.~caps'
+                    const capsDir = '.~o/encapsulate.dev/caps'
                     const relativePathToCaps = relative(projectedFileDir, capsDir)
                     importPrefix = relativePathToCaps.startsWith('.') ? relativePathToCaps : './' + relativePathToCaps
                 }
@@ -1628,7 +1638,7 @@ ${mappedDefaultExport}
             }
         }
 
-        // Write projection cache AND project ALL capsules in the registry to .~caps
+        // Write projection cache AND project ALL capsules in the registry to .~o/encapsulate.dev/caps
         // This includes struct definitions, property contract capsules, and any other capsules
         if (projectionCacheStore?.writeFile && capsules) {
             for (const [capsuleKey, registryCapsule] of Object.entries(capsules)) {
@@ -1655,7 +1665,7 @@ ${mappedDefaultExport}
                     }
                     await projectionCacheStore.writeFile(capsuleCacheFilename, JSON.stringify(capsuleCacheData, null, 2))
 
-                    // Also project the capsule to .~caps
+                    // Also project the capsule to .~o/encapsulate.dev/caps
                     const projectedPath = capsuleCacheData.snapshotData.spineContracts[spineContractUri]['#@stream44.studio/encapsulate/structs/Capsule'].projectedCapsuleFilepath
 
                     // Generate the capsule file content with proper imports and ambient reference loading

package/src/encapsulate.ts

@@ -1,4 +1,8 @@
 
+// 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 = 9
+
 type TSpineOptions = {
     spineFilesystemRoot?: string,
     spineContracts: Record<string, any>,
@@ -32,7 +36,7 @@ type TSpineRuntimeOptions = {
     spineContracts?: Record<string, any>,
     snapshot?: TSpineSnapshot,
     capsules?: Record<string, any>,
-    loadCapsule?: (options: { capsuleSourceLineRef: string, capsuleSnapshot: any, capsuleName?: string }) => Promise<any>
+    loadCapsule?: (options: { capsuleSourceLineRef: string, capsuleSnapshot: any, capsuleName?: string, cacheBustVersion?: number }) => Promise<any>
 }
 
 type TCapsuleSnapshot = {
@@ -44,7 +48,12 @@ type TCapsuleMakeInstanceOptions = {
     overrides?: Record<string, any>,
     options?: Record<string, any>,
     runtimeSpineContracts?: Record<string, any>,
-    sharedSelf?: Record<string, any>
+    sharedSelf?: Record<string, any>,
+    rootCapsule?: {
+        capsuleName: string,
+        capsuleSourceLineRef: string,
+        moduleFilepath: string
+    }
 }
 
 type TCapsule = {
@@ -97,6 +106,7 @@ export const CapsulePropertyTypes = {
     String: 'String' as const,
     Mapping: 'Mapping' as const,
     Literal: 'Literal' as const,
+    Constant: 'Constant' as const,
     StructInit: 'StructInit' as const,
 }
 
@@ -299,9 +309,19 @@ export async function SpineRuntime(options: TSpineRuntimeOptions): Promise<TSpin
             const capsule = await options.loadCapsule!({
                 capsuleSourceLineRef,
                 capsuleSnapshot,
-                capsuleName
+                capsuleName,
+                cacheBustVersion: CACHE_BUST_VERSION
             })
 
+            // If loadCapsule returns null, it means cache bust version mismatch - regenerate the capsule
+            if (capsule === null) {
+                throw new Error(
+                    `Cache bust version mismatch for capsule '${capsuleSourceLineRef}'. ` +
+                    `Expected version ${CACHE_BUST_VERSION} but found ${(capsuleSnapshot as any).cst?.cacheBustVersion}. ` +
+                    `Please delete the cache directory and regenerate capsules.`
+                )
+            }
+
             loadedCapsules[capsuleSourceLineRef] = await capsule({
                 encapsulate: spine.encapsulate,
                 CapsulePropertyTypes,
@@ -392,28 +412,59 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
     if (!options.importMeta && !options.moduleFilepath) throw new Error(`'options.importMeta' nor 'options.moduleFilepath' not specified!`)
     if (!options.importStack && !options.importStackLine) throw new Error(`'options.importStack' nor 'options.importStackLine' specified!`)
 
-    const moduleFilepath = options.moduleFilepath || relative(spine.spineOptions.spineFilesystemRoot || '', options.importMeta!.url.replace(/^file:\/\//, ''))
+    // Use relative path for internal processing, but store absolute path for metadata
+    const providedPath = options.moduleFilepath || options.importMeta!.url.replace(/^file:\/\//, '')
+    const spineRoot = spine.spineOptions.spineFilesystemRoot || ''
+
+    // Determine if we need to make the path absolute
+    let absoluteModuleFilepath: string
+    if (providedPath.startsWith('/')) {
+        // Already an absolute path (starts with /)
+        absoluteModuleFilepath = providedPath
+    } else if (spineRoot) {
+        // Relative path - make it absolute by joining with spine root
+        absoluteModuleFilepath = join(spineRoot, providedPath)
+    } else {
+        // No spine root and path is relative - use as-is (will remain relative)
+        // Note: This happens when SpineRuntime doesn't pass spineFilesystemRoot through
+        absoluteModuleFilepath = providedPath
+    }
+
+    const moduleFilepath = relative(spineRoot, absoluteModuleFilepath)
     const importStackLine = options.importStackLine || formatImportStackFrame(options.importStack!)
 
     if (typeof importStackLine !== 'number') throw new Error(`Could not determine importStackLine from options`)
 
-    const encapsulateOptions: TEncapsulateOptions = {
-        moduleFilepath,
-        importStackLine,
-        capsuleName: options.capsuleName,
-        ambientReferences: options.ambientReferences,
-        extendsCapsule: options.extendsCapsule,
-        capsuleSourceLineRef: `${moduleFilepath}:${importStackLine}`
-    }
+    const capsuleSourceLineRef = `${moduleFilepath}:${importStackLine}`
 
     spine.spineOptions.timing?.record(`Encapsulate: Start for ${moduleFilepath}`)
 
     const { csts, crts } = await spine.spineOptions.staticAnalyzer?.parseModule({
         spineOptions: spine.spineOptions,
-        encapsulateOptions
+        encapsulateOptions: {
+            moduleFilepath,
+            importStackLine,
+            capsuleSourceLineRef,
+            capsuleName: options.capsuleName,
+            ambientReferences: options.ambientReferences,
+            cacheBustVersion: CACHE_BUST_VERSION
+        }
     }) || {
-        csts: options.cst ? { [encapsulateOptions.capsuleSourceLineRef]: options.cst } : undefined,
-        crts: options.crt ? { [encapsulateOptions.capsuleSourceLineRef]: options.crt } : undefined
+        csts: options.cst ? { [capsuleSourceLineRef]: options.cst } : undefined,
+        crts: options.crt ? { [capsuleSourceLineRef]: options.crt } : undefined
+    }
+
+    // Get capsuleName from options first, then fall back to CST if available
+    const cst = csts?.[capsuleSourceLineRef]
+    const capsuleName = options.capsuleName || cst?.source?.capsuleName
+
+    const encapsulateOptions: TEncapsulateOptions = {
+        moduleFilepath,
+        importStackLine,
+        capsuleName,
+        ambientReferences: options.ambientReferences,
+        extendsCapsule: options.extendsCapsule,
+        capsuleSourceLineRef
     }
 
     const defaultInstance: Record<string, any> = {}
@@ -431,9 +482,9 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
         capsuleSourceLineRef: encapsulateOptions.capsuleSourceLineRef,
         definition,
         encapsulateOptions,
-        cst: csts?.[encapsulateOptions.capsuleSourceLineRef],
-        crt: crts?.[encapsulateOptions.capsuleSourceLineRef],
-        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts, sharedSelf }: TCapsuleMakeInstanceOptions = {}) => {
+        cst,
+        crt: crts?.[capsuleSourceLineRef],
+        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts, sharedSelf, rootCapsule }: TCapsuleMakeInstanceOptions = {}) => {
 
             // Create cache key based on parameters
             // When sharedSelf is provided, we must NOT cache because each extending capsule
@@ -593,6 +644,22 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 // The selfProxy in spine contracts will expose this as 'self' property
                 const ownSelf = merge({}, defaultInstance, defaultPropertyValues, ...Object.values(mergedValuesByContract))
 
+                // Capsule metadata struct will be set on self/ownSelf AFTER spine contract processing
+                // to avoid being overwritten by the empty struct marker in the definition
+                // Convert relative paths to absolute for metadata exposure
+                const absoluteCapsuleSourceLineRef = `${absoluteModuleFilepath}:${importStackLine}`
+                const capsuleMetadataStruct = {
+                    capsuleName: encapsulateOptions.capsuleName,
+                    capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
+                    moduleFilepath: absoluteModuleFilepath,
+                    // Root capsule metadata will be populated after extends chain is resolved
+                    rootCapsule: {
+                        capsuleName: undefined as string | undefined,
+                        capsuleSourceLineRef: undefined as string | undefined,
+                        moduleFilepath: undefined as string | undefined
+                    }
+                }
+
                 // Initialize extended capsule instance if this capsule extends another
                 // Pass our self so extended capsule's functions bind to the same context
                 let extendedCapsuleInstance: any = undefined
@@ -657,16 +724,34 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                         overrides,
                         options,
                         runtimeSpineContracts,
-                        sharedSelf: self
+                        sharedSelf: self,
+                        rootCapsule: rootCapsule || {
+                            capsuleName: encapsulateOptions.capsuleName!,
+                            capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
+                            moduleFilepath: absoluteModuleFilepath
+                        }
                     })
                 }
 
+                // Resolve the root capsule for this instance:
+                // If rootCapsule was passed down from a parent, use it (preserves the first capsule in the chain).
+                // Otherwise this capsule IS the root.
+                const resolvedRootCapsule = rootCapsule || {
+                    capsuleName: encapsulateOptions.capsuleName!,
+                    capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
+                    moduleFilepath: absoluteModuleFilepath
+                }
+                capsuleMetadataStruct.rootCapsule.capsuleName = resolvedRootCapsule.capsuleName
+                capsuleMetadataStruct.rootCapsule.capsuleSourceLineRef = resolvedRootCapsule.capsuleSourceLineRef
+                capsuleMetadataStruct.rootCapsule.moduleFilepath = resolvedRootCapsule.moduleFilepath
+
                 const capsuleInstance: any = {
                     api: encapsulatedApi,
                     spineContractCapsuleInstances,
                     extendedCapsuleInstance,
                     structInitFunctions: [] as Array<() => any>,
-                    mappedCapsuleInstances: [] as Array<any>
+                    mappedCapsuleInstances: [] as Array<any>,
+                    rootCapsule: resolvedRootCapsule
                 }
 
                 // Use runtime spine contracts if provided, otherwise fall back to encapsulation spine contracts
@@ -715,6 +800,15 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     }
                 }
 
+                // Set capsule metadata struct on self/ownSelf AFTER spine contract processing
+                // to avoid being overwritten by the empty struct marker in the definition
+                if (!self['#@stream44.studio/encapsulate/structs/Capsule'] ||
+                    typeof self['#@stream44.studio/encapsulate/structs/Capsule'] !== 'object' ||
+                    !self['#@stream44.studio/encapsulate/structs/Capsule'].capsuleName) {
+                    self['#@stream44.studio/encapsulate/structs/Capsule'] = capsuleMetadataStruct
+                }
+                ownSelf['#@stream44.studio/encapsulate/structs/Capsule'] = capsuleMetadataStruct
+
                 // Collect StructInit functions and mapped capsule instances from all spine contract capsule instances
                 for (const spineContractCapsuleInstance of Object.values(spineContractCapsuleInstances)) {
                     const sci = spineContractCapsuleInstance as any

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

@@ -80,7 +80,8 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         currentCallerContext,
         runtimeSpineContracts,
         instanceRegistry,
-        extendedCapsuleInstance
+        extendedCapsuleInstance,
+        capsuleInstance
     }: {
         spineContractUri: string
         capsule: any
@@ -100,8 +101,9 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         runtimeSpineContracts?: Record<string, any>
         instanceRegistry?: CapsuleInstanceRegistry
         extendedCapsuleInstance?: any
+        capsuleInstance?: any
     }) {
-        super({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance })
+        super({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance, capsuleInstance })
         this.getEventIndex = getEventIndex
         this.incrementEventIndex = incrementEventIndex
         this.currentCallerContext = currentCallerContext
@@ -230,7 +232,8 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         const mappedCapsuleInstance = await mappedCapsule.makeInstance({
             overrides: mappedOverrides,
             options: mappingOptions,
-            runtimeSpineContracts: this.runtimeSpineContracts
+            runtimeSpineContracts: this.runtimeSpineContracts,
+            rootCapsule: this.capsuleInstance?.rootCapsule
         })
 
         // Register the instance (replaces null pre-registration marker)
@@ -344,6 +347,8 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
     }
 
     protected mapLiteralProperty({ property }: { property: any }) {
+        // Constant properties are read-only and throw on set
+        const isConstant = property.definition.type === CapsulePropertyTypes.Constant
 
         const value = typeof this.self[property.name] !== 'undefined'
             ? this.self[property.name]
@@ -388,6 +393,11 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                 return currentValue
             },
             set: (newValue) => {
+                // Constant properties cannot be set
+                if (isConstant) {
+                    throw new Error(`Cannot set constant property '${property.name}'`)
+                }
+
                 const event: any = {
                     event: 'set',
                     eventIndex: this.incrementEventIndex(),
@@ -585,7 +595,7 @@ export function CapsuleSpineContract({
     return {
         '#': CapsuleSpineContract['#'],
         instanceRegistry,
-        makeContractCapsuleInstance: ({ encapsulateOptions, spineContractUri, self, ownSelf, capsule, encapsulatedApi, runtimeSpineContracts, extendedCapsuleInstance }: { encapsulateOptions: any, spineContractUri: string, self: any, ownSelf?: any, capsule?: any, encapsulatedApi: Record<string, any>, runtimeSpineContracts?: Record<string, any>, extendedCapsuleInstance?: any }) => {
+        makeContractCapsuleInstance: ({ encapsulateOptions, spineContractUri, self, ownSelf, capsule, encapsulatedApi, runtimeSpineContracts, extendedCapsuleInstance, capsuleInstance }: { encapsulateOptions: any, spineContractUri: string, self: any, ownSelf?: any, capsule?: any, encapsulatedApi: Record<string, any>, runtimeSpineContracts?: Record<string, any>, extendedCapsuleInstance?: any, capsuleInstance?: any }) => {
             return new MembraneContractCapsuleInstanceFactory({
                 spineContractUri,
                 capsule,
@@ -604,7 +614,8 @@ export function CapsuleSpineContract({
                 currentCallerContext,
                 runtimeSpineContracts,
                 instanceRegistry,
-                extendedCapsuleInstance
+                extendedCapsuleInstance,
+                capsuleInstance
             })
         },
         hydrate: ({ capsuleSnapshot }: { capsuleSnapshot: any }): any => {

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

@@ -17,10 +17,11 @@ export class ContractCapsuleInstanceFactory {
     protected extendedCapsuleInstance?: any
     protected ownSelf?: any
     protected runtimeSpineContracts?: Record<string, any>
+    protected capsuleInstance?: any
     public structInitFunctions: Array<() => any> = []
     public mappedCapsuleInstances: Array<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> }) {
+    constructor({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance, runtimeSpineContracts, capsuleInstance }: { 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>, capsuleInstance?: any }) {
         this.spineContractUri = spineContractUri
         this.capsule = capsule
         this.self = self
@@ -33,6 +34,7 @@ export class ContractCapsuleInstanceFactory {
         this.instanceRegistry = instanceRegistry
         this.extendedCapsuleInstance = extendedCapsuleInstance
         this.runtimeSpineContracts = runtimeSpineContracts
+        this.capsuleInstance = capsuleInstance
     }
 
     async mapProperty({ overrides, options, property }: { overrides: any, options: any, property: any }) {
@@ -40,7 +42,8 @@ export class ContractCapsuleInstanceFactory {
             await this.mapMappingProperty({ overrides, options, property })
         } else if (
             property.definition.type === CapsulePropertyTypes.String ||
-            property.definition.type === CapsulePropertyTypes.Literal
+            property.definition.type === CapsulePropertyTypes.Literal ||
+            property.definition.type === CapsulePropertyTypes.Constant
         ) {
             this.mapLiteralProperty({ property })
         } else if (property.definition.type === CapsulePropertyTypes.Function) {
@@ -226,7 +229,8 @@ export class ContractCapsuleInstanceFactory {
         const mappedInstance = await mappedCapsule.makeInstance({
             overrides: mappedOverrides,
             options: mappingOptions,
-            runtimeSpineContracts: this.runtimeSpineContracts
+            runtimeSpineContracts: this.runtimeSpineContracts,
+            rootCapsule: this.capsuleInstance?.rootCapsule
         })
 
         // Register the instance (replaces null pre-registration marker)
@@ -369,7 +373,7 @@ export function CapsuleSpineContract({ freezeCapsule, resolve, importCapsule, sp
     return {
         '#': CapsuleSpineContract['#'],
         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> }) => {
+        makeContractCapsuleInstance: ({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, extendedCapsuleInstance, runtimeSpineContracts, capsuleInstance }: { spineContractUri: string, capsule: any, self: any, ownSelf?: any, encapsulatedApi: Record<string, any>, extendedCapsuleInstance?: any, runtimeSpineContracts?: Record<string, any>, capsuleInstance?: any }) => {
             return new ContractCapsuleInstanceFactory({
                 spineContractUri,
                 capsule,
@@ -382,7 +386,8 @@ export function CapsuleSpineContract({ freezeCapsule, resolve, importCapsule, sp
                 freezeCapsule,
                 instanceRegistry,
                 extendedCapsuleInstance,
-                runtimeSpineContracts
+                runtimeSpineContracts,
+                capsuleInstance
             })
         },
         hydrate: ({ capsuleSnapshot }: { capsuleSnapshot: any }): any => {

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

@@ -499,7 +499,7 @@ export async function CapsuleSpineFactory({
 
     timing?.recordMajor('CAPSULE SPINE FACTORY: READY')
 
-    const loadCapsule = async ({ capsuleSnapshot }: { capsuleSourceLineRef: string, capsuleSnapshot: any }) => {
+    const loadCapsule = async ({ capsuleSnapshot, cacheBustVersion }: { capsuleSourceLineRef: string, capsuleSnapshot: any, cacheBustVersion?: number }) => {
 
         if (!capsuleModuleProjectionRoot) {
             throw new Error('capsuleModuleProjectionRoot must be provided to enable dynamic loading of capsules')
@@ -509,6 +509,11 @@ export async function CapsuleSpineFactory({
 
         if (!filepath) throw new Error(`Cannot load capsule. No 'filepath' found at 'spineContracts["#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0"]["#@stream44.studio/encapsulate/structs/Capsule"].projectedCapsuleFilepath'!`)
 
+        // Check cache bust version - if it doesn't match, return null to trigger regeneration
+        if (cacheBustVersion !== undefined && capsuleSnapshot.cst?.cacheBustVersion !== cacheBustVersion) {
+            return null
+        }
+
         const { capsule } = await import(join(capsuleModuleProjectionRoot, filepath))
 
         return capsule
@@ -529,6 +534,7 @@ export async function CapsuleSpineFactory({
 
             const result = await SpineRuntime({
                 snapshot,
+                spineFilesystemRoot,
                 spineContracts: spineContractInstances.runtime,
                 loadCapsule
             })

package/src/static-analyzer.v0.ts

@@ -235,10 +235,18 @@ export function StaticAnalyzer({
                         ])
 
                         if (cstsContent && crtsContent) {
-                            timing?.record(`StaticAnalyzer: Cache HIT for ${encapsulateOptions.moduleFilepath}`)
-                            return {
-                                csts: JSON.parse(cstsContent),
-                                crts: JSON.parse(crtsContent)
+                            const cachedCsts = JSON.parse(cstsContent)
+
+                            // Check cache bust version - if mismatch, regenerate
+                            const cachedVersion = cachedCsts?.[capsuleSourceLineRef]?.cacheBustVersion
+                            if (encapsulateOptions.cacheBustVersion !== undefined && cachedVersion !== encapsulateOptions.cacheBustVersion) {
+                                timing?.record(timing?.chalk?.red?.(`StaticAnalyzer: Cache BUST (version mismatch: ${cachedVersion} !== ${encapsulateOptions.cacheBustVersion}) for ${encapsulateOptions.moduleFilepath}`))
+                            } else {
+                                timing?.record(`StaticAnalyzer: Cache HIT for ${encapsulateOptions.moduleFilepath}`)
+                                return {
+                                    csts: cachedCsts,
+                                    crts: JSON.parse(crtsContent)
+                                }
                             }
                         }
                     }
@@ -340,6 +348,7 @@ export function StaticAnalyzer({
                     )
 
                     const cst: any = {
+                        cacheBustVersion: encapsulateOptions.cacheBustVersion || 1,
                         capsuleSourceLineRef,
                         capsuleSourceNameRef,
                         capsuleSourceNameRefHash,