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

package/package.json

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

package/src/encapsulate.ts

@@ -1,4 +1,6 @@
 
+import type { TimingObserverInterface } from './spine-factories/TimingObserver'
+
 // 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 = 22
@@ -7,7 +9,7 @@ type TSpineOptions = {
     spineFilesystemRoot?: string,
     spineContracts: Record<string, any>,
     staticAnalyzer?: any,
-    timing?: { record: (step: string) => void, chalk?: any },
+    timing?: TimingObserverInterface,
     projectionContext?: {
         capsuleModuleProjectionPackage?: string,
         capsuleModuleProjectionRoot?: string,
@@ -56,6 +58,9 @@ type TCapsuleSnapshot = {
 type TCapsuleMakeInstanceOptions = {
     overrides?: Record<string, any>,
     options?: Record<string, any>,
+    /** Nested capsule-name-targeted options from a parent mapping.
+     *  Merged AFTER options so they take precedence over intermediate defaults. */
+    transitiveOverrides?: Record<string, any>,
     runtimeSpineContracts?: Record<string, any>,
     sharedSelf?: Record<string, any>,
     rootCapsule?: {
@@ -65,7 +70,8 @@ type TCapsuleMakeInstanceOptions = {
     },
     parentCapsuleSourceUriLineRefInstanceId?: string,
     sit?: { capsuleInstances: Record<string, { capsuleName: string, capsuleSourceUriLineRef: string, parentCapsuleSourceUriLineRefInstanceId: string }> },
-    skipCache?: boolean
+    skipCache?: boolean,
+    freezePhase?: boolean
 }
 
 type TCapsule = {
@@ -115,6 +121,7 @@ type TSpineContext = {
 export const CapsulePropertyTypes = {
     Function: 'Function' as const,
     GetterFunction: 'GetterFunction' as const,
+    ConstantGetterFunction: 'ConstantGetterFunction' as const,
     SetterFunction: 'SetterFunction' as const,
     String: 'String' as const,
     Mapping: 'Mapping' as const,
@@ -460,7 +467,7 @@ export async function Spine(options: TSpineOptions): Promise<TSpine> {
                     snapshot.capsules[capsule.cst.source.capsuleName] = snapshot.capsules[capsuleSourceLineRef]
                 }
 
-                const capsuleInstance = await capsule.makeInstance()
+                const capsuleInstance = await capsule.makeInstance({ freezePhase: true })
 
                 // Run OnFreeze functions so capsules can perform side effects
                 // (e.g. file projection) at build/freeze time
@@ -666,7 +673,9 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
         encapsulateOptions,
         cst,
         crt: crts?.[capsuleSourceLineRef],
-        makeInstance: async ({ overrides = {}, options = {}, runtimeSpineContracts, sharedSelf, rootCapsule, parentCapsuleSourceUriLineRefInstanceId, sit, skipCache }: TCapsuleMakeInstanceOptions = {}) => {
+        makeInstance: async ({ overrides = {}, options = {}, transitiveOverrides, runtimeSpineContracts, sharedSelf, rootCapsule, parentCapsuleSourceUriLineRefInstanceId, sit, skipCache, freezePhase }: TCapsuleMakeInstanceOptions = {}) => {
+
+            spine.spineOptions.timing?.record(`makeInstance: ${capsuleName || capsuleSourceLineRef}${freezePhase ? ' [freeze]' : ''}${sharedSelf ? ' [extends]' : ''}`)
 
             // Create cache key based on parameters
             // When sharedSelf is provided, we must NOT cache because each extending capsule
@@ -674,15 +683,14 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
             // This is critical for the pattern where multiple structs extend the same parent.
             // 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
-            })
+            const cacheKey = (sharedSelf || skipCache) ? null : computeCacheKey(
+                overrides, options, transitiveOverrides, !!runtimeSpineContracts
+            )
 
             // Check if we already have a pending or completed instance creation
             // Skip cache when sharedSelf is provided (cacheKey is null)
             if (cacheKey && instanceCache.has(cacheKey)) {
+                spine.spineOptions.timing?.record(`makeInstance: CACHE HIT ${capsuleName || capsuleSourceLineRef}`)
                 return instanceCache.get(cacheKey)!
             }
 
@@ -724,6 +732,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                                 const propDefTyped = propDef as Record<string, any>
                                 const aliasName = propDefTyped.as
                                 let delegateOptions = propDefTyped.options
+                                const delegateDepends = propDefTyped.depends
                                 const contractKey = aliasName || ('#' + propContractUri.substring(1))
 
                                 if (!propertyContractDefinitions[spineContractUri]['#']) {
@@ -739,6 +748,9 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                                     value: delegateCapsuleObj || delegateUri,
                                     propertyContractDelegate: propContractUri,
                                     as: aliasName,
+                                    // Forward depends from the struct declaration so the delegate
+                                    // options function can access the required parent properties
+                                    depends: delegateDepends,
                                     // Pass options from the property contract delegate to the mapped capsule
                                     delegateOptions
                                 }
@@ -775,12 +787,19 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     }
                 }
 
-                // Merge in order: overrides by lineRef, overrides by name, options
+                // Merge in order: overrides, options, then transitive overrides.
+                // - Overrides (from run()) are general defaults — options are more specific.
+                // - Transitive overrides (nested capsule-name-targeted options from a parent)
+                //   are the most specific and win over intermediate capsule options.
                 mergeByContract(overrides?.[encapsulateOptions.capsuleSourceLineRef], 'Overrides')
                 if (encapsulateOptions.capsuleName) {
                     mergeByContract(overrides?.[encapsulateOptions.capsuleName], 'Overrides')
                 }
                 mergeByContract(options, 'Options')
+                mergeByContract(transitiveOverrides?.[encapsulateOptions.capsuleSourceLineRef], 'TransitiveOverrides')
+                if (encapsulateOptions.capsuleName) {
+                    mergeByContract(transitiveOverrides?.[encapsulateOptions.capsuleName], 'TransitiveOverrides')
+                }
 
                 // Extract default values from property definitions (Literal/String types)
                 // This ensures child capsule's default values are available before parent is instantiated
@@ -790,7 +809,8 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                         if (propertyContractUri !== '#') continue
                         for (const [propertyName, propertyDef] of Object.entries(properties as Record<string, any>)) {
                             if (propertyDef.type === CapsulePropertyTypes.Literal ||
-                                propertyDef.type === CapsulePropertyTypes.String) {
+                                propertyDef.type === CapsulePropertyTypes.String ||
+                                propertyDef.type === CapsulePropertyTypes.Constant) {
                                 if (propertyDef.value !== undefined) {
                                     defaultPropertyValues[propertyName] = propertyDef.value
                                 }
@@ -847,6 +867,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
                     capsuleSourceNameRefHash: cst?.capsuleSourceNameRefHash,
                     moduleFilepath: originalAbsoluteModuleFilepath,
+                    spineFilesystemRoot: spine.spineOptions.spineFilesystemRoot,
                     // Root capsule metadata will be populated after extends chain is resolved
                     rootCapsule: {
                         capsuleName: undefined as string | undefined,
@@ -926,9 +947,11 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                         })
                     }
 
+                    spine.spineOptions.timing?.record(`makeInstance: extends → ${extendsCapsule.encapsulateOptions?.capsuleName || '?'}`)
                     extendedCapsuleInstance = await extendsCapsule.makeInstance({
                         overrides,
                         options,
+                        transitiveOverrides,
                         runtimeSpineContracts,
                         sharedSelf: self,
                         rootCapsule: rootCapsule || {
@@ -937,9 +960,10 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                             moduleFilepath: absoluteModuleFilepath
                         },
                         parentCapsuleSourceUriLineRefInstanceId: parentCapsuleSourceUriLineRefInstanceId
-                            ? await sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + (cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef))
-                            : await sha256(cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef),
-                        sit
+                            ? sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + (cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef))
+                            : sha256(cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef),
+                        sit,
+                        freezePhase
                     })
 
                     // Propagate this (child) capsule's encapsulatedApi to all parent spine contract
@@ -975,8 +999,8 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 //   child: sha256(parentCapsuleSourceUriLineRefInstanceId + ":" + capsuleSourceUriLineRef)
                 const capsuleSourceUriLineRef = cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef
                 const capsuleSourceUriLineRefInstanceId = parentCapsuleSourceUriLineRefInstanceId
-                    ? await sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + capsuleSourceUriLineRef)
-                    : await sha256(capsuleSourceUriLineRef)
+                    ? sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + capsuleSourceUriLineRef)
+                    : sha256(capsuleSourceUriLineRef)
 
                 // Register this instance in the sit structure if provided
                 if (sit) {
@@ -1001,7 +1025,8 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     capsuleSourceUriLineRefInstanceId,
                     capsuleName: encapsulateOptions.capsuleName,
                     capsuleSourceUriLineRef,
-                    sit
+                    sit,
+                    freezePhase
                 }
 
                 // Set capsule metadata struct on self early so it's available in options() callbacks during mapping
@@ -1012,6 +1037,14 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 }
                 ownSelf['#@stream44.studio/encapsulate/structs/Capsule'] = capsuleMetadataStruct
 
+                // Promote metadata values to top-level self properties so struct delegate
+                // proxies (which read from the capsule instance's own self/api) can access them.
+                for (const [metaKey, metaValue] of Object.entries(capsuleMetadataStruct)) {
+                    if (metaKey !== 'rootCapsule' && metaValue !== undefined && self[metaKey] === undefined) {
+                        self[metaKey] = metaValue
+                    }
+                }
+
                 // Use runtime spine contracts if provided, otherwise fall back to encapsulation spine contracts
                 const activeSpineContracts = runtimeSpineContracts || spine.spineContracts
 
@@ -1056,6 +1089,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                             await spineContractCapsuleInstance.mapProperty({
                                 overrides,
                                 options,
+                                transitiveOverrides,
                                 property: {
                                     name: propertyName,
                                     definition: propertyDefinition,
@@ -1230,15 +1264,41 @@ function relative(from: string, to: string): string {
     return result || '.'
 }
 
-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')
+// Fast cache key computation for makeInstance — avoids JSON.stringify for the common empty case
+const _emptyObj = {}
+const _cacheKeyEmpty = '{"overrides":{},"options":{},"hasRuntimeContracts":false}'
+const _cacheKeyEmptyWithRuntime = '{"overrides":{},"options":{},"hasRuntimeContracts":true}'
+function _isEmptyObj(obj: any): boolean { for (const _ in obj) return false; return true }
+const _cacheKeyLastRef = { overrides: _emptyObj as any, options: _emptyObj as any, transitiveOverrides: undefined as any, hasRuntime: false, key: _cacheKeyEmpty }
+function computeCacheKey(overrides: any, options: any, transitiveOverrides: any, hasRuntimeContracts: boolean): string {
+    // Reference-equality shortcut: if same objects as last call, reuse key
+    if (overrides === _cacheKeyLastRef.overrides && options === _cacheKeyLastRef.options
+        && transitiveOverrides === _cacheKeyLastRef.transitiveOverrides && hasRuntimeContracts === _cacheKeyLastRef.hasRuntime) {
+        return _cacheKeyLastRef.key
     }
-    return hex
+    // Fast-path: empty overrides + empty options + no transitive = constant string
+    if (!transitiveOverrides && _isEmptyObj(overrides) && _isEmptyObj(options)) {
+        const key = hasRuntimeContracts ? _cacheKeyEmptyWithRuntime : _cacheKeyEmpty
+        _cacheKeyLastRef.overrides = overrides; _cacheKeyLastRef.options = options
+        _cacheKeyLastRef.transitiveOverrides = transitiveOverrides; _cacheKeyLastRef.hasRuntime = hasRuntimeContracts
+        _cacheKeyLastRef.key = key
+        return key
+    }
+    const key = JSON.stringify({ overrides, options, transitiveOverrides, hasRuntimeContracts })
+    _cacheKeyLastRef.overrides = overrides; _cacheKeyLastRef.options = options
+    _cacheKeyLastRef.transitiveOverrides = transitiveOverrides; _cacheKeyLastRef.hasRuntime = hasRuntimeContracts
+    _cacheKeyLastRef.key = key
+    return key
+}
+
+const _sha256Cache = new Map<string, string>()
+const _createHash = require('crypto').createHash
+function sha256(input: string): string {
+    let result = _sha256Cache.get(input)
+    if (result !== undefined) return result
+    result = _createHash('sha256').update(input).digest('hex') as string
+    _sha256Cache.set(input, result)
+    return result
 }
 
 function isObject(item: any): boolean {

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

@@ -1,5 +1,6 @@
 import { CapsulePropertyTypes } from "../../encapsulate"
 import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static"
+import type { TimingObserverInterface } from "../../spine-factories/TimingObserver"
 
 type CallerContext = {
     capsuleSourceLineRef: string
@@ -86,7 +87,8 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         runtimeSpineContracts,
         instanceRegistry,
         extendedCapsuleInstance,
-        capsuleInstance
+        capsuleInstance,
+        timing
     }: {
         spineContractUri: string
         capsule: any
@@ -109,8 +111,9 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         instanceRegistry?: CapsuleInstanceRegistry
         extendedCapsuleInstance?: any
         capsuleInstance?: any
+        timing?: TimingObserverInterface
     }) {
-        super({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance, capsuleInstance })
+        super({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance, capsuleInstance, timing })
         this.getEventIndex = getEventIndex
         this.incrementEventIndex = incrementEventIndex
         this.getCurrentCallerContext = getCurrentCallerContext
@@ -137,7 +140,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         return ctx
     }
 
-    protected async mapMappingProperty({ overrides, options, property }: { overrides: any, options: any, property: any }) {
+    protected async mapMappingProperty({ overrides, options, transitiveOverrides, property }: { overrides: any, options: any, transitiveOverrides?: any, property: any }) {
 
         const mappedCapsule = await this.resolveMappedCapsule({ property })
         const constants = await this.extractConstants({ mappedCapsule })
@@ -151,9 +154,23 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         const minimalSelf = this.self[capsuleStructKey]
             ? { [capsuleStructKey]: this.self[capsuleStructKey] }
             : {}
-        const mappingOptions = property.definition.delegateOptions
-            || (typeof optionsFn === 'function'
-                ? await optionsFn({ self: property.definition.depends ? this.self : minimalSelf, constants })
+        // During freeze phase, skip calling function-based options callbacks — runtime
+        // overrides haven't been applied so self.* references may be incomplete.
+        // Use a truthy placeholder so the instance registry still creates a fresh instance.
+        const isFreezePhase = !!this.capsuleInstance?.freezePhase
+        const hasFunctionOptions = typeof optionsFn === 'function'
+        const selfArg = { self: property.definition.depends ? this.self : minimalSelf, constants }
+        const delegateOpts = property.definition.delegateOptions
+        const resolvedDelegateOptions = delegateOpts
+            ? (typeof delegateOpts === 'function'
+                ? (isFreezePhase ? {} : await delegateOpts(selfArg))
+                : delegateOpts)
+            : undefined
+        const mappingOptions = resolvedDelegateOptions
+            || (hasFunctionOptions
+                ? (isFreezePhase
+                    ? {}  // truthy placeholder
+                    : await optionsFn(selfArg))
                 : optionsFn)
 
         // Check for existing instance in registry - reuse if available (regardless of options)
@@ -270,13 +287,14 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
             }
         }
 
-        // Merge nested capsule-name-targeted options into overrides
-        // These will be picked up when child capsules with matching names are instantiated
+        // Build transitive overrides for the child: merge any inherited transitive
+        // overrides with this mapping's nested capsule-name-targeted options.
+        let mappedTransitiveOverrides: Record<string, any> | undefined = transitiveOverrides
         if (nestedCapsuleOptions) {
-            mappedOverrides = { ...mappedOverrides }
+            mappedTransitiveOverrides = { ...(mappedTransitiveOverrides || {}) }
             for (const [capsuleNameKey, capsuleOptions] of Object.entries(nestedCapsuleOptions)) {
-                mappedOverrides[capsuleNameKey] = {
-                    ...(mappedOverrides[capsuleNameKey] || {}),
+                mappedTransitiveOverrides[capsuleNameKey] = {
+                    ...(mappedTransitiveOverrides[capsuleNameKey] || {}),
                     ...capsuleOptions
                 }
             }
@@ -285,11 +303,13 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         const mappedCapsuleInstance = await mappedCapsule.makeInstance({
             overrides: mappedOverrides,
             options: ownMappingOptions,
+            transitiveOverrides: mappedTransitiveOverrides,
             runtimeSpineContracts: this.runtimeSpineContracts,
             rootCapsule: this.capsuleInstance?.rootCapsule,
             parentCapsuleSourceUriLineRefInstanceId: this.capsuleInstance?.capsuleSourceUriLineRefInstanceId,
             sit: this.capsuleInstance?.sit,
-            skipCache: isCapsuleStruct
+            skipCache: isCapsuleStruct,
+            freezePhase: this.capsuleInstance?.freezePhase || undefined
         })
 
         // Register the instance (replaces null pre-registration marker)
@@ -481,6 +501,51 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         })
     }
 
+    protected override mapConstantGetterFunctionProperty({ property }: { property: any }) {
+        const value = property.definition.value({ constants: this.self })
+
+        // Store eagerly on self like a Constant
+        this.self[property.name] = value
+        if (this.ownSelf) {
+            this.ownSelf[property.name] = value
+        }
+
+        // Wrap with membrane event tracking (read-only like Constant)
+        Object.defineProperty(this.encapsulatedApi, property.name, {
+            get: () => {
+                const currentValue = this.self[property.name]
+
+                const event: any = {
+                    event: 'get',
+                    eventIndex: this.incrementEventIndex(),
+                    membrane: 'external',
+                    target: {
+                        capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
+                        spineContractCapsuleInstanceId: this.id,
+                        prop: property.name,
+                    },
+                    value: currentValue
+                }
+
+                if (this.capsuleSourceNameRef) {
+                    event.target.capsuleSourceNameRef = this.capsuleSourceNameRef
+                }
+                if (this.capsuleSourceNameRefHash) {
+                    event.target.capsuleSourceNameRefHash = this.capsuleSourceNameRefHash
+                }
+
+                this.addCallerContextToEvent(event)
+                this.onMembraneEvent?.(event)
+                return currentValue
+            },
+            set: () => {
+                throw new Error(`Cannot set ConstantGetterFunction property '${property.name}'`)
+            },
+            enumerable: true,
+            configurable: true
+        })
+    }
+
     protected mapFunctionProperty({ property }: { property: any }) {
         const selfProxy = this.createSelfProxy()
         const boundFunction = property.definition.value.bind(selfProxy)
@@ -1001,7 +1066,8 @@ export function CapsuleSpineContract({
     spineFilesystemRoot,
     resolve,
     importCapsule,
-    npmUriForFilepath
+    npmUriForFilepath,
+    timing
 }: {
     onMembraneEvent?: (event: any) => void
     freezeCapsule?: (capsule: any) => Promise<any>
@@ -1010,6 +1076,7 @@ export function CapsuleSpineContract({
     resolve?: (uri: string, parentFilepath: string) => Promise<string>
     importCapsule?: (filepath: string) => Promise<any>
     npmUriForFilepath?: (filepath: string) => Promise<string | null>
+    timing?: TimingObserverInterface
 } = {}) {
 
     let eventIndex = 0
@@ -1070,7 +1137,8 @@ export function CapsuleSpineContract({
                 runtimeSpineContracts,
                 instanceRegistry,
                 extendedCapsuleInstance,
-                capsuleInstance
+                capsuleInstance,
+                timing
             })
         },
         hydrate: ({ capsuleSnapshot }: { capsuleSnapshot: any }): any => {

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

@@ -65,6 +65,18 @@ const userService = await encapsulate({
                 value: '1.0.0'
             },
 
+            // ConstantGetterFunction: eagerly evaluated during property mapping.
+            // Receives { constants } (not this) — constants contains all Literal/String/Constant
+            // values from the same capsule, resolved Mapping constants, and capsule metadata.
+            // The computed result is stored on self like a Constant and included in extractConstants.
+            derivedPath: {
+                type: CapsulePropertyTypes.ConstantGetterFunction,
+                value: function ({ constants }: { constants: any }): string {
+                    const meta = constants['#@stream44.studio/encapsulate/structs/Capsule']
+                    return `/workbench/${meta.capsuleName}`
+                }
+            },
+
             // --- Function Properties ---
 
             // Function: bound to a self proxy. Receives arguments. Callable on the API.
@@ -253,6 +265,7 @@ Reference
 | `Literal` | read/write | read/write | yes | General-purpose value. Supports any JS type including `Map`, `Set`, etc. |
 | `String` | read/write | read/write | yes | Alias for `Literal`. Semantic hint for string values. |
 | `Constant` | read-only | read | no | Immutable value. Membrane contract throws on assignment. |
+| `ConstantGetterFunction` | read-only | read | no | Eagerly evaluated computed constant. See below. |
 
 All value types accept a `value` in their definition. `undefined` means "no default — must be supplied via overrides/options".
 
@@ -316,6 +329,35 @@ When `api.name(...args)` is called:
 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)
 
+#### ConstantGetterFunction
+
+`ConstantGetterFunction` is a computed constant — eagerly evaluated during property mapping, with its result stored on `self` like a `Constant`. Unlike `GetterFunction` (bound to `this`, evaluated lazily on each access), `ConstantGetterFunction` receives an explicit `{ constants }` parameter and is evaluated once.
+
+```ts
+workbenchDir: {
+    type: CapsulePropertyTypes.ConstantGetterFunction,
+    value: function ({ constants }: { constants: any }): string {
+        const meta = constants['#@stream44.studio/encapsulate/structs/Capsule']
+        const capsuleDir = constants.lib.path.dirname(meta.rootCapsule.moduleFilepath)
+        const testName = constants.lib.path.basename(meta.rootCapsule.moduleFilepath).replace(/\.[^.]+$/, '')
+        return constants.lib.path.join(capsuleDir, '.~o/workbenches', testName)
+    }
+}
+```
+
+**What `constants` contains:**
+
+| Context | Contents |
+|---|---|
+| During `extractConstants` (parent Mapping) | `Literal`/`String`/`Constant` values from the capsule definition, resolved `Mapping` constants (nested), and capsule metadata including `rootCapsule` |
+| During `mapProperty` (instance creation) | `self` — all previously-processed properties, capsule metadata, resolved Mappings |
+
+**Key properties:**
+- **No `this` binding** — receives `{ constants }` as a plain function argument, making dependencies explicit
+- **Available in parent's `constants`** — when a parent maps this capsule, the computed value is included in the `constants` parameter passed to the parent's `options` callback
+- **Mapping constants are nested** — `constants.lib.path` accesses the `path` Constant from a mapped `lib` capsule
+- **Capsule metadata** — `constants['#@stream44.studio/encapsulate/structs/Capsule']` includes `capsuleName`, `moduleFilepath`, and `rootCapsule` (the top-level capsule in the spine)
+
 ### Mapping
 
 `Mapping` composes another capsule as a sub-component.
@@ -333,7 +375,7 @@ prop: {
 - **`value`** — a capsule reference (from `encapsulate()`) or a string URI resolved relative to the current module.
 - **`options`** — forwarded to the mapped capsule. Keys starting with `'#'` target the mapped capsule's own property contracts. Keys without `'#'` are matched against capsule names deeper in the mapping tree (nested capsule-name-targeted options).
 - **`options({ self, constants })`** — when `options` is a function, it receives `{ self, constants }`.
-  - `constants` — all `Literal`/`String` values from the mapped capsule's definition.
+  - `constants` — all `Literal`/`String`/`Constant` values from the mapped capsule's definition, computed `ConstantGetterFunction` results, resolved `Mapping` constants (nested by property name), and capsule metadata (`constants['#@stream44.studio/encapsulate/structs/Capsule']` with `rootCapsule`).
   - `self` — always contains the Capsule metadata struct (`self['#@stream44.studio/encapsulate/structs/Capsule']` with `moduleFilepath`, `capsuleName`, etc.). When `depends` is specified, `self` also contains the full parent capsule's resolved sibling mappings.
 - **`depends`** — array of sibling property names that must be resolved before this mapping's `options` function runs. Enables `options({ self })` to access already-resolved siblings (e.g. `self.$auth.realm`). Can be declared explicitly or auto-injected by the static analyzer when it detects `self.<name>` references in the options function body.
 - **Instance reuse** — named capsules are registered in an instance registry. If a capsule with the same name is mapped multiple times without options, the existing instance is reused via a deferred proxy.

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

@@ -1,4 +1,5 @@
 import { CapsulePropertyTypes, join } from "../../encapsulate"
+import type { TimingObserverInterface } from "../../spine-factories/TimingObserver"
 
 // Type for capsule instance registry - scoped per spine contract instance
 export type CapsuleInstanceRegistry = Map<string, any>
@@ -19,6 +20,7 @@ export class ContractCapsuleInstanceFactory {
     public childEncapsulatedApis?: Record<string, any>[]
     protected runtimeSpineContracts?: Record<string, any>
     protected capsuleInstance?: any
+    protected timing?: TimingObserverInterface
     public structInitFunctions: Array<() => any> = []
     public structDisposeFunctions: Array<() => any> = []
     public initFunctions: Array<() => any> = []
@@ -28,7 +30,7 @@ export class ContractCapsuleInstanceFactory {
     protected memoizeCache: Map<string, any> = new Map()
     protected memoizeTimeouts: Map<string, ReturnType<typeof setTimeout>> = new Map()
 
-    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 }) {
+    constructor({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance, runtimeSpineContracts, capsuleInstance, timing }: { 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, timing?: TimingObserverInterface }) {
         this.spineContractUri = spineContractUri
         this.capsule = capsule
         this.self = self
@@ -42,6 +44,7 @@ export class ContractCapsuleInstanceFactory {
         this.extendedCapsuleInstance = extendedCapsuleInstance
         this.runtimeSpineContracts = runtimeSpineContracts
         this.capsuleInstance = capsuleInstance
+        this.timing = timing
 
         // Inject importCapsule onto ownSelf so capsule functions can call this.self.importCapsule()
         if (ownSelf && !ownSelf.importCapsule) {
@@ -82,9 +85,9 @@ export class ContractCapsuleInstanceFactory {
         }
     }
 
-    async mapProperty({ overrides, options, property }: { overrides: any, options: any, property: any }) {
+    async mapProperty({ overrides, options, transitiveOverrides, property }: { overrides: any, options: any, transitiveOverrides?: any, property: any }) {
         if (property.definition.type === CapsulePropertyTypes.Mapping) {
-            await this.mapMappingProperty({ overrides, options, property })
+            await this.mapMappingProperty({ overrides, options, transitiveOverrides, property })
         } else if (
             property.definition.type === CapsulePropertyTypes.String ||
             property.definition.type === CapsulePropertyTypes.Literal ||
@@ -93,6 +96,8 @@ export class ContractCapsuleInstanceFactory {
             this.mapLiteralProperty({ property })
         } else if (property.definition.type === CapsulePropertyTypes.Function) {
             this.mapFunctionProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.ConstantGetterFunction) {
+            this.mapConstantGetterFunctionProperty({ property })
         } else if (property.definition.type === CapsulePropertyTypes.GetterFunction) {
             this.mapGetterFunctionProperty({ property })
         } else if (property.definition.type === CapsulePropertyTypes.SetterFunction) {
@@ -206,6 +211,7 @@ export class ContractCapsuleInstanceFactory {
                     throw resolveError
                 }
             }
+            this.timing?.record(`resolveMappedCapsule: importCapsule(${filepath.replace(/^.*\/genesis\//, '')})`)
             mappedCapsule = await this.importCapsule(filepath)
         } else if (
             typeof property.definition.value === 'object' &&
@@ -219,8 +225,10 @@ export class ContractCapsuleInstanceFactory {
         return mappedCapsule
     }
 
-    protected async extractConstants({ mappedCapsule }: { mappedCapsule: any }) {
+    protected async extractConstants({ mappedCapsule, _visited }: { mappedCapsule: any, _visited?: Set<string> }) {
         const constants: Record<string, any> = {}
+        const constantGetterFunctions: Array<{ key: string; fn: Function }> = []
+        const mappingProperties: Array<{ key: string; def: any }> = []
 
         const spineContractDef = mappedCapsule.definition[this.spineContractUri]
 
@@ -239,9 +247,14 @@ export class ContractCapsuleInstanceFactory {
 
                     if (
                         type === CapsulePropertyTypes.String ||
-                        type === CapsulePropertyTypes.Literal
+                        type === CapsulePropertyTypes.Literal ||
+                        type === CapsulePropertyTypes.Constant
                     ) {
                         constants[prop] = propValue
+                    } else if (type === CapsulePropertyTypes.ConstantGetterFunction) {
+                        constantGetterFunctions.push({ key: prop, fn: propValue })
+                    } else if (type === CapsulePropertyTypes.Mapping) {
+                        mappingProperties.push({ key: prop, def: propDef })
                     }
                 }
             } else {
@@ -252,17 +265,67 @@ export class ContractCapsuleInstanceFactory {
 
                 if (
                     type === CapsulePropertyTypes.String ||
-                    type === CapsulePropertyTypes.Literal
+                    type === CapsulePropertyTypes.Literal ||
+                    type === CapsulePropertyTypes.Constant
                 ) {
                     constants[key] = propValue
+                } else if (type === CapsulePropertyTypes.ConstantGetterFunction) {
+                    constantGetterFunctions.push({ key, fn: propValue })
+                } else if (type === CapsulePropertyTypes.Mapping) {
+                    mappingProperties.push({ key, def: value })
                 }
             }
         }
 
+        // Resolve Mapping properties and extract their constants recursively.
+        // Track visited capsules to prevent infinite recursion on circular refs.
+        const visited = _visited || new Set<string>()
+        const thisCapsuleName = mappedCapsule.encapsulateOptions?.capsuleName
+        if (thisCapsuleName) visited.add(thisCapsuleName)
+        for (const { key, def } of mappingProperties) {
+            try {
+                const nestedCapsule = await this.resolveMappedCapsule({
+                    property: { definition: def, name: key }
+                })
+                const nestedName = nestedCapsule.encapsulateOptions?.capsuleName
+                if (nestedName && visited.has(nestedName)) continue
+                constants[key] = await this.extractConstants({ mappedCapsule: nestedCapsule, _visited: visited })
+            } catch {
+                // Skip mappings that cannot be resolved (e.g. missing dependencies)
+            }
+        }
+
+        // Build capsule metadata so ConstantGetterFunctions can access it.
+        // rootCapsule is inherited from the parent (same as what makeInstance would receive).
+        const capsuleStructKey = '#@stream44.studio/encapsulate/structs/Capsule'
+        const relModuleFilepath = mappedCapsule.cst?.source?.moduleFilepath
+            || mappedCapsule.encapsulateOptions?.moduleFilepath
+        const moduleFilepath = relModuleFilepath
+            ? (relModuleFilepath.startsWith('/')
+                ? relModuleFilepath
+                : join(this.spineFilesystemRoot || '', relModuleFilepath))
+            : undefined
+        constants[capsuleStructKey] = {
+            capsuleName: mappedCapsule.encapsulateOptions?.capsuleName,
+            moduleFilepath,
+            rootCapsule: this.capsuleInstance?.rootCapsule || {
+                capsuleName: this.capsule?.encapsulateOptions?.capsuleName,
+                moduleFilepath: this.self?.[capsuleStructKey]?.moduleFilepath,
+            },
+        }
+
+        // Evaluate ConstantGetterFunction values with the accumulated constants
+        // (including resolved Mapping constants). These receive { constants }
+        // (not this) — only static values and nested Mapping constants are available.
+        for (const { key, fn } of constantGetterFunctions) {
+            constants[key] = fn({ constants })
+        }
+
         return constants
     }
 
-    protected async mapMappingProperty({ overrides, options, property }: { overrides: any, options: any, property: any }) {
+    protected async mapMappingProperty({ overrides, options, transitiveOverrides, property }: { overrides: any, options: any, transitiveOverrides?: any, property: any }) {
+        this.timing?.record(`mapMappingProperty: ${property.name} → ${typeof property.definition.value === 'string' ? property.definition.value : (property.definition.value?.encapsulateOptions?.capsuleName || 'obj')}`)
         const mappedCapsule = await this.resolveMappedCapsule({ property })
         const constants = await this.extractConstants({ mappedCapsule })
 
@@ -275,9 +338,25 @@ export class ContractCapsuleInstanceFactory {
         const minimalSelf = this.self[capsuleStructKey]
             ? { [capsuleStructKey]: this.self[capsuleStructKey] }
             : {}
-        const mappingOptions = property.definition.delegateOptions
-            || (typeof optionsFn === 'function'
-                ? await optionsFn({ self: property.definition.depends ? this.self : minimalSelf, constants })
+        // During freeze phase, skip calling function-based options callbacks — runtime
+        // overrides haven't been applied so self.* references may be incomplete.
+        // Use a truthy placeholder so the instance registry still creates a fresh instance
+        // (preserving the instance tree for OnFreeze traversal and .sit.json generation).
+        // Object-based options and delegateOptions are always applied (they are static).
+        const isFreezePhase = !!this.capsuleInstance?.freezePhase
+        const hasFunctionOptions = typeof optionsFn === 'function'
+        const selfArg = { self: property.definition.depends ? this.self : minimalSelf, constants }
+        const delegateOpts = property.definition.delegateOptions
+        const resolvedDelegateOptions = delegateOpts
+            ? (typeof delegateOpts === 'function'
+                ? (isFreezePhase ? {} : await delegateOpts(selfArg))
+                : delegateOpts)
+            : undefined
+        const mappingOptions = resolvedDelegateOptions
+            || (hasFunctionOptions
+                ? (isFreezePhase
+                    ? {}  // truthy placeholder — signals "has options" without calling the function
+                    : await optionsFn(selfArg))
                 : optionsFn)
 
         // Check for existing instance in registry - reuse if available when no options
@@ -295,6 +374,7 @@ export class ContractCapsuleInstanceFactory {
 
                 // Only reuse if current mapping has no options
                 if (!mappingOptions) {
+                    this.timing?.record(`mapMappingProperty: REGISTRY REUSE ${capsuleName} (deferred proxy)`)
                     // Use deferred proxy that resolves from registry when accessed
                     // Works for both null (pre-registered) and actual instances
                     const apiTarget = this.getApiTarget({ property })
@@ -377,13 +457,16 @@ export class ContractCapsuleInstanceFactory {
             }
         }
 
-        // Merge nested capsule-name-targeted options into overrides
-        // These will be picked up when child capsules with matching names are instantiated
+        // Build transitive overrides for the child: merge any inherited transitive
+        // overrides with this mapping's nested capsule-name-targeted options.
+        // These flow as transitiveOverrides (not overrides) so they take precedence
+        // over the child's own Mapping options but runtime overrides remain less specific.
+        let mappedTransitiveOverrides: Record<string, any> | undefined = transitiveOverrides
         if (nestedCapsuleOptions) {
-            mappedOverrides = { ...mappedOverrides }
+            mappedTransitiveOverrides = { ...(mappedTransitiveOverrides || {}) }
             for (const [capsuleNameKey, capsuleOptions] of Object.entries(nestedCapsuleOptions)) {
-                mappedOverrides[capsuleNameKey] = {
-                    ...(mappedOverrides[capsuleNameKey] || {}),
+                mappedTransitiveOverrides[capsuleNameKey] = {
+                    ...(mappedTransitiveOverrides[capsuleNameKey] || {}),
                     ...capsuleOptions
                 }
             }
@@ -393,11 +476,13 @@ export class ContractCapsuleInstanceFactory {
         const mappedInstance = await mappedCapsule.makeInstance({
             overrides: mappedOverrides,
             options: ownMappingOptions,
+            transitiveOverrides: mappedTransitiveOverrides,
             runtimeSpineContracts: this.runtimeSpineContracts,
             rootCapsule: this.capsuleInstance?.rootCapsule,
             parentCapsuleSourceUriLineRefInstanceId: this.capsuleInstance?.capsuleSourceUriLineRefInstanceId,
             sit: this.capsuleInstance?.sit,
-            skipCache: isCapsuleStruct
+            skipCache: isCapsuleStruct,
+            freezePhase: this.capsuleInstance?.freezePhase || undefined
         })
 
         // Register the instance (replaces null pre-registration marker)
@@ -457,6 +542,20 @@ export class ContractCapsuleInstanceFactory {
         }
     }
 
+    protected mapConstantGetterFunctionProperty({ property }: { property: any }) {
+        const apiTarget = this.getApiTarget({ property })
+        // Pass self as constants — at instance creation time self contains capsule
+        // metadata, resolved Mappings, and all previously-processed properties.
+        const value = property.definition.value({ constants: this.self })
+
+        // Store eagerly like a Constant — available on self for subsequent properties
+        apiTarget[property.name] = value
+        this.self[property.name] = value
+        if (this.ownSelf) {
+            this.ownSelf[property.name] = value
+        }
+    }
+
     protected createSelfProxy() {
         const extendedApi = this.extendedCapsuleInstance?.api
         const ownSelf = this.ownSelf
@@ -744,7 +843,7 @@ 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 } = {}) {
+export function CapsuleSpineContract({ freezeCapsule, resolve, importCapsule, spineFilesystemRoot, timing }: { freezeCapsule?: (capsule: any) => Promise<any>, resolve?: (uri: string, parentFilepath: string) => Promise<string>, importCapsule?: (filepath: string) => Promise<any>, spineFilesystemRoot?: string, timing?: TimingObserverInterface } = {}) {
 
     const instanceRegistry: CapsuleInstanceRegistry = new Map()
 
@@ -765,7 +864,8 @@ export function CapsuleSpineContract({ freezeCapsule, resolve, importCapsule, sp
                 instanceRegistry,
                 extendedCapsuleInstance,
                 runtimeSpineContracts,
-                capsuleInstance
+                capsuleInstance,
+                timing
             })
         },
         hydrate: ({ capsuleSnapshot }: { capsuleSnapshot: any }): any => {

package/src/spine-factories/CapsuleSpineFactory.ts

@@ -1,8 +1,10 @@
 import { join, dirname, relative, resolve as pathResolve } from 'path'
-import { writeFile, mkdir, readFile, stat } from 'fs/promises'
+import { writeFile, mkdir, readFile, stat, access } from 'fs/promises'
+import { createHash } from 'crypto'
 import { Spine, SpineRuntime, CapsulePropertyTypes, makeImportStack, merge } from "../encapsulate"
 import { StaticAnalyzer } from "../../src/static-analyzer"
 import { CapsuleModuleProjector } from "../../src/capsule-projectors/CapsuleModuleProjector"
+import { TimingObserver, type TimingObserverInterface } from "./TimingObserver"
 
 
 export { merge }
@@ -366,6 +368,31 @@ function createNpmUriForFilepath(): (filepath: string) => Promise<string | null>
     }
 }
 
+// Cross-factory cache for module imports — avoids re-importing the same file
+// across factory instances. The capsule() call still runs per-factory (spine-specific),
+// but the import() is only done once per filepath globally.
+const _moduleImportCache = new Map<string, Promise<any>>()
+
+// Cross-factory stat cache — avoids redundant filesystem stat() calls for the same
+// file across factory instances within a single process. Source file stats are cached
+// permanently (source files don't change within a single build). Cache file stats are
+// invalidated on write.
+const _statCache = new Map<string, Promise<{ mtime: Date } | null>>()
+function cachedStat(filepath: string): Promise<{ mtime: Date } | null> {
+    let cached = _statCache.get(filepath)
+    if (!cached) {
+        cached = stat(filepath).then(
+            s => ({ mtime: s.mtime }),
+            () => null
+        )
+        _statCache.set(filepath, cached)
+    }
+    return cached
+}
+function invalidateStatCache(filepath: string) {
+    _statCache.delete(filepath)
+}
+
 export async function CapsuleSpineFactory({
     spineFilesystemRoot,
     capsuleModuleProjectionRoot,
@@ -383,13 +410,16 @@ export async function CapsuleSpineFactory({
     onMembraneEvent?: (event: any) => void,
     enableCallerStackInference?: boolean,
     spineContracts: Record<string, any>,
-    timing?: { record: (step: string) => void, recordMajor: (step: string) => void, chalk?: any }
+    timing?: TimingObserverInterface | null
 }) {
 
     if (capsuleModuleProjectionRoot) capsuleModuleProjectionRoot = capsuleModuleProjectionRoot.replace(/^file:\/\//, '')
     if (spineFilesystemRoot) spineFilesystemRoot = spineFilesystemRoot.replace(/^file:\/\//, '')
 
-    const timing = timingParam
+    // Auto-create timing when ENCAPSULATE_TRACE env var is set
+    const timing: TimingObserverInterface | undefined = timingParam || (
+        process.env.ENCAPSULATE_TRACE ? TimingObserver() : undefined
+    )
 
     timing?.recordMajor('CAPSULE SPINE FACTORY: INITIALIZATION')
 
@@ -397,6 +427,7 @@ export async function CapsuleSpineFactory({
         const registry = new Map<string, Promise<any>>()
 
         return {
+            has(id: string) { return registry.has(id) },
             async ensure(id: string, createHandler: () => Promise<any>) {
                 if (!registry.has(id)) {
                     registry.set(id, createHandler())
@@ -419,6 +450,7 @@ export async function CapsuleSpineFactory({
     const sourceSpine: { encapsulate?: any } = {}
     const npmUriForFilepath = createNpmUriForFilepath()
     const commonSpineContractOpts = {
+        timing,
         spineFilesystemRoot,
         npmUriForFilepath,
         resolve: async (uri: string, parentFilepath: string) => {
@@ -430,24 +462,25 @@ export async function CapsuleSpineFactory({
             return await resolve(uri, parentFilepath, spineFilesystemRoot)
         },
         importCapsule: (() => {
-            return async (filepath: string) => {
+            const importFn = async (filepath: string) => {
                 const shortPath = filepath.replace(/^.*\/genesis\//, '')
 
                 timing?.record(`importCapsule: Called for ${shortPath}`)
                 const result = await registry.ensure(filepath, async () => {
                     timing?.recordMajor(`importCapsule: Starting import for ${shortPath}`)
                     const importStart = Date.now()
-                    const exports = await import(filepath)
+                    if (!_moduleImportCache.has(filepath)) {
+                        _moduleImportCache.set(filepath, import(filepath))
+                    }
+                    const exports = await _moduleImportCache.get(filepath)!
                     const importDuration = Date.now() - importStart
                     timing?.recordMajor(`importCapsule: import() took ${importDuration}ms for ${shortPath}`)
 
-                    if (importDuration > 10) {
-                        if (timing) {
-                            console.log(timing.chalk.red(`\n⚠️  WARNING: Slow module load detected!`))
-                            console.log(timing.chalk.red(`   Module: ${filepath}`))
-                            console.log(timing.chalk.red(`   Load time: ${importDuration}ms`))
-                            console.log(timing.chalk.red(`   Consider using dynamic imports to load heavy dependencies only when needed.\n`))
-                        }
+                    if (importDuration > 10 && timing) {
+                        console.log(timing.chalk.red(`\n⚠️  WARNING: Slow module load detected!`))
+                        console.log(timing.chalk.red(`   Module: ${filepath}`))
+                        console.log(timing.chalk.red(`   Load time: ${importDuration}ms`))
+                        console.log(timing.chalk.red(`   Consider using dynamic imports to load heavy dependencies only when needed.\n`))
                     }
 
                     if (typeof exports.capsule !== 'function') throw new Error(`Module at '${filepath}' does not export 'capsule'!`)
@@ -467,6 +500,7 @@ export async function CapsuleSpineFactory({
                 })
                 return result
             }
+            return importFn
         })(),
         encapsulateOpts: {
             CapsulePropertyTypes
@@ -570,10 +604,7 @@ export async function CapsuleSpineFactory({
 
     timing?.recordMajor('SPINE: INITIALIZATION')
 
-    let { encapsulate, freeze, capsules } = await Spine({
-        spineFilesystemRoot,
-        timing,
-        staticAnalyzer: staticAnalysisEnabled ? StaticAnalyzer({
+    const staticAnalyzer = staticAnalysisEnabled ? StaticAnalyzer({
             timing,
             cacheStore: {
                 writeFile: async (filepath: string, content: string) => {
@@ -581,6 +612,7 @@ export async function CapsuleSpineFactory({
                     const centralPath = join(spineFilesystemRoot, '.~o/encapsulate.dev/static-analysis', filepath)
                     await mkdir(dirname(centralPath), { recursive: true })
                     await writeFile(centralPath, content, 'utf-8')
+                    invalidateStatCache(centralPath)
                     // Also write to local project cache if available
                     if (capsuleModuleProjectionRoot) {
                         try {
@@ -604,29 +636,20 @@ export async function CapsuleSpineFactory({
                     return content
                 },
                 getStats: async (filepath: string) => {
-                    filepath = join(spineFilesystemRoot, '.~o/encapsulate.dev/static-analysis', filepath)
-                    try {
-                        const stats = await stat(filepath)
-                        return { mtime: stats.mtime }
-                    } catch (error) {
-                        // File doesn't exist
-                        return null
-                    }
+                    return cachedStat(join(spineFilesystemRoot, '.~o/encapsulate.dev/static-analysis', filepath))
                 },
             },
             spineStore: {
                 getStats: async (filepath: string) => {
-                    filepath = join(spineFilesystemRoot, filepath)
-                    try {
-                        const stats = await stat(filepath)
-                        return { mtime: stats.mtime }
-                    } catch (error) {
-                        // File doesn't exist
-                        return null
-                    }
+                    return cachedStat(join(spineFilesystemRoot, filepath))
                 },
             },
-        }) : undefined,
+        }) : undefined
+
+    let { encapsulate, freeze, capsules } = await Spine({
+        spineFilesystemRoot,
+        timing,
+        staticAnalyzer,
         spineContracts: spineContractInstances.encapsulation,
         projectionContext: capsuleModuleProjectionRoot ? {
             capsuleModuleProjectionPackage,
@@ -682,10 +705,16 @@ export async function CapsuleSpineFactory({
         return capsule
     }
 
+    // Track capsule refs known at freeze time so we can identify dynamic imports later
+    let frozenCapsuleRefs: Set<string> | null = null
+
     // Wrap freeze to also write spine instance (.sit.json) files
     const wrappedFreeze = async function () {
         const snapshot = await freeze()
 
+        // Record capsule refs at freeze time (before any dynamic imports)
+        frozenCapsuleRefs = new Set(Object.keys(capsules))
+
         // Write spine instance files if capsuleModuleProjectionRoot is available
         if (capsuleModuleProjectionRoot) {
             try {
@@ -722,6 +751,10 @@ export async function CapsuleSpineFactory({
                     }
                 }
 
+                // Check if any CSTs were regenerated — if not, we can skip SIT writes
+                // when existing files are still valid
+                const cstsChanged = !staticAnalyzer || staticAnalyzer.hasCacheMisses()
+
                 for (const [, capsule] of Object.entries(uniqueCapsules)) {
                     const cst = capsule.cst
                     const rootCapsuleName = cst?.source?.capsuleName
@@ -737,6 +770,16 @@ export async function CapsuleSpineFactory({
                     const sitDir = join(capsuleModuleProjectionRoot, '.~o/encapsulate.dev/spine-instances', dirName)
                     const sitFilePath = join(sitDir, `root-capsule.sit.json`)
 
+                    // Skip SIT generation if CSTs are unchanged and the file already exists
+                    if (!cstsChanged) {
+                        try {
+                            await access(sitFilePath)
+                            continue // File exists and no CSTs changed — skip
+                        } catch {
+                            // File doesn't exist — need to generate even though CSTs are cached
+                        }
+                    }
+
                     // Build the capsules map
                     const capsuleEntries: Record<string, { capsuleSourceUriLineRef: string }> = {}
                     for (const [, cap] of Object.entries(uniqueCapsules)) {
@@ -750,7 +793,7 @@ export async function CapsuleSpineFactory({
 
                     // Collect capsuleInstances from the cached root instance using an
                     // iterative stack — each instance stores its ID and parent ID from init
-                    const rootInstance = await capsule.makeInstance()
+                    const rootInstance = await capsule.makeInstance({ freezePhase: true })
                     const capsuleInstances: Record<string, { capsuleName: string, capsuleSourceUriLineRef: string, parentCapsuleSourceUriLineRefInstanceId: string }> = {}
 
                     // Iterative stack-based collection from instance tree
@@ -790,8 +833,18 @@ export async function CapsuleSpineFactory({
                         capsuleInstances
                     }
 
+                    const sitContent = JSON.stringify(sitData, null, 2)
+
+                    // Compare-before-write: skip disk write if content is identical
+                    try {
+                        const existing = await readFile(sitFilePath, 'utf-8')
+                        if (existing === sitContent) continue
+                    } catch {
+                        // File doesn't exist — write it
+                    }
+
                     await mkdir(sitDir, { recursive: true })
-                    await writeFile(sitFilePath, JSON.stringify(sitData, null, 2), 'utf-8')
+                    await writeFile(sitFilePath, sitContent, 'utf-8')
                 }
             } catch (error) {
                 // Spine instance file writing is best-effort
@@ -802,6 +855,55 @@ export async function CapsuleSpineFactory({
         return snapshot
     }
 
+    /**
+     * Write a dynamic SIT file capturing capsules that were loaded at runtime
+     * via importCapsule (not part of the static capsule tree).
+     * Call this after run() to record which dynamic capsules were used.
+     * The filename includes a content hash so unchanged combos produce the same file.
+     */
+    const writeDynamicSit = async function () {
+        if (!capsuleModuleProjectionRoot || !frozenCapsuleRefs) return
+
+        // Find capsules that were added after freeze (dynamic imports)
+        const dynamicCapsuleRefs: string[] = []
+        for (const key of Object.keys(capsules)) {
+            if (!frozenCapsuleRefs.has(key) && key.includes(':') && /:\d+$/.test(key)) {
+                dynamicCapsuleRefs.push(key)
+            }
+        }
+
+        if (dynamicCapsuleRefs.length === 0) return
+
+        // Build a sorted list of dynamic capsule entries for deterministic output
+        const dynamicEntries: Record<string, { capsuleSourceUriLineRef: string, capsuleName?: string }> = {}
+        for (const ref of dynamicCapsuleRefs.sort()) {
+            const cap = capsules[ref]
+            dynamicEntries[ref] = {
+                capsuleSourceUriLineRef: ref,
+                capsuleName: cap?.cst?.source?.capsuleName
+            }
+        }
+
+        const sitData = { dynamicCapsules: dynamicEntries }
+        const sitContent = JSON.stringify(sitData, null, 2)
+
+        // Content hash for the filename — same dynamic import combo = same file
+        const contentHash = createHash('sha256').update(sitContent).digest('hex').slice(0, 16)
+        const sitDir = join(capsuleModuleProjectionRoot, '.~o/encapsulate.dev/spine-instances')
+        const sitFilePath = join(sitDir, `dynamic-imports.${contentHash}.sit.json`)
+
+        // Skip write if file already exists (hash match = identical content)
+        try {
+            await access(sitFilePath)
+            return // Already exists with same content
+        } catch {
+            // File doesn't exist — write it
+        }
+
+        await mkdir(sitDir, { recursive: true })
+        await writeFile(sitFilePath, sitContent, 'utf-8')
+    }
+
     return {
         commonSpineContractOpts,
         CapsulePropertyTypes,
@@ -809,7 +911,9 @@ export async function CapsuleSpineFactory({
         encapsulate,
         run,
         freeze: wrappedFreeze,
+        writeDynamicSit,
         loadCapsule,
+        staticAnalyzer,
         spineContractInstances, // Expose for testing
         hoistSnapshot: async ({ snapshot }: { snapshot: any }) => {
 

package/src/spine-factories/TimingObserver.ts

@@ -1,26 +1,36 @@
 
 import chalk from 'chalk';
 
-export function TimingObserver({ startTime }: { startTime: number }) {
-    let lastTime = startTime
+export type TimingOptions = { color?: 'red' | 'green' | 'yellow' | 'cyan' | 'gray' }
+
+export type TimingObserverInterface = {
+    record: (step: string, opts?: TimingOptions) => void,
+    recordMajor: (step: string, opts?: TimingOptions) => void,
+    chalk: typeof chalk,
+}
+
+export function TimingObserver(): TimingObserverInterface {
+    let lastTime = performance.now()
+
+    function format(msg: string, diff: string, opts?: TimingOptions): string {
+        const line = `[+${diff}ms] ${msg}`
+        if (opts?.color) return (chalk as any)[opts.color](line)
+        return line
+    }
 
     return {
         chalk,
-        record: (step: string) => {
-            const now = Date.now()
-            const diff = now - lastTime
+        record: (step: string, opts?: TimingOptions) => {
+            const now = performance.now()
+            const diff = (now - lastTime).toFixed(1)
             lastTime = now
-
-            const line = `[+${diff}ms]   ${step}`
-            console.log(diff > 10 ? chalk.red(line) : line)
+            console.log(format(`  ${step}`, diff, opts))
         },
-        recordMajor: (step: string) => {
-            const now = Date.now()
-            const diff = now - lastTime
+        recordMajor: (step: string, opts?: TimingOptions) => {
+            const now = performance.now()
+            const diff = (now - lastTime).toFixed(1)
             lastTime = now
-
-            const line = `[+${diff}ms] ${step}`
-            console.log(diff > 10 ? chalk.red(line) : chalk.cyan(line))
+            console.log(format(`★ ${step}`, diff, opts))
         }
     }
 }

package/src/static-analyzer.ts

@@ -3,6 +3,7 @@ import { join, normalize, dirname, resolve, relative } from 'path'
 import { readFile, stat } from 'fs/promises'
 import * as ts from 'typescript'
 import { createHash } from 'crypto'
+import type { TimingObserverInterface } from './spine-factories/TimingObserver'
 
 // Known exports from @stream44.studio/encapsulate/encapsulate that can be imported
 const ENCAPSULATE_MODULE_EXPORTS = new Set([
@@ -227,7 +228,7 @@ export function StaticAnalyzer({
     cacheStore,
     spineStore
 }: {
-    timing?: { record: (step: string) => void, chalk?: any },
+    timing?: TimingObserverInterface,
     cacheStore?: {
         writeFile?: (filepath: string, content: string) => Promise<void>,
         readFile?: (filepath: string) => Promise<string | undefined>,
@@ -240,8 +241,16 @@ export function StaticAnalyzer({
 
     timing?.record('StaticAnalyzer: Initialized')
 
+    let _cacheMissCount = 0
+
     return {
 
+        /** Returns true if any parseModule call resulted in a cache miss (CST regeneration) */
+        hasCacheMisses: () => _cacheMissCount > 0,
+
+        /** Reset the cache miss counter (call before a new freeze cycle) */
+        resetCacheMisses: () => { _cacheMissCount = 0 },
+
         parseModule: async ({ spineOptions, encapsulateOptions }: { spineOptions: any, encapsulateOptions: any }) => {
 
             const moduleFilepath = join(spineOptions.spineFilesystemRoot, encapsulateOptions.moduleFilepath)
@@ -282,7 +291,8 @@ export function StaticAnalyzer({
                             // 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}`))
+                                _cacheMissCount++
+                                timing?.record(`StaticAnalyzer: Cache BUST (version mismatch: ${cachedVersion} !== ${encapsulateOptions.cacheBustVersion}) for ${encapsulateOptions.moduleFilepath}`, { color: 'red' })
                             } else {
                                 timing?.record(`StaticAnalyzer: Cache HIT for ${encapsulateOptions.moduleFilepath}`)
                                 return {
@@ -293,10 +303,12 @@ export function StaticAnalyzer({
                             }
                         }
                     }
-                    timing?.record(timing?.chalk?.red?.(`StaticAnalyzer: Cache MISS for ${encapsulateOptions.moduleFilepath}`))
+                    _cacheMissCount++
+                    timing?.record(`StaticAnalyzer: Cache MISS for ${encapsulateOptions.moduleFilepath}`, { color: 'red' })
                 } catch (error) {
                     // Cache miss or error, continue with normal parsing
-                    timing?.record(timing?.chalk?.red?.(`StaticAnalyzer: Cache error for ${encapsulateOptions.moduleFilepath}`))
+                    _cacheMissCount++
+                    timing?.record(`StaticAnalyzer: Cache error for ${encapsulateOptions.moduleFilepath}`, { color: 'red' })
                 }
             }
 

package/structs/Capsule.ts

@@ -11,6 +11,11 @@ export async function capsule({
                     type: CapsulePropertyTypes.Literal,
                     value: undefined
                 },
+
+                spineFilesystemRoot: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined as string | undefined
+                },
             }
         }
     }, {