@stream44.studio/encapsulate 0.4.0-rc.38 → 0.4.0-rc.42

package/README.md

@@ -1,7 +1,7 @@
 <table>
   <tr>
-    <td><a href="https://Stream44.Studio"><img src=".o/stream44.studio/assets/Icon-v1.svg" width="42" height="42"></a></td>
-    <td><strong><a href="https://Stream44.Studio">Stream44 Studio</a></strong><br/>Open Development Project</td>
+    <td><a href="https://Stream44.Systems"><img src=".o/stream44.studio/assets/Icon-v1.svg" width="42" height="42"></a></td>
+    <td><strong><a href="https://Stream44.Systems">Stream44 Systems</a></strong><br/>Open Development Project</td>
     <td>Preview release for community feedback.<br/>Get in touch on <a href="https://discord.gg/9eBcQXEJAN">discord</a>.</td>
     <td>Designed by Hand<br/><b>AI assisted Code</a></td>
   </tr>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stream44.studio/encapsulate",
-    "version": "0.4.0-rc.38",
+    "version": "0.4.0-rc.42",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -10,9 +10,9 @@
     "type": "module",
     "exports": {
         "./encapsulate": "./src/encapsulate.ts",
-        "./spine-contracts/CapsuleSpineContract.v0/Static.v0": "./src/spine-contracts/CapsuleSpineContract.v0/Static.v0.ts",
-        "./spine-contracts/CapsuleSpineContract.v0/Membrane.v0": "./src/spine-contracts/CapsuleSpineContract.v0/Membrane.v0.ts",
-        "./spine-factories/CapsuleSpineFactory.v0": "./src/spine-factories/CapsuleSpineFactory.v0.ts",
+        "./spine-contracts/CapsuleSpineContract.v0/Static": "./src/spine-contracts/CapsuleSpineContract.v0/Static.ts",
+        "./spine-contracts/CapsuleSpineContract.v0/Membrane": "./src/spine-contracts/CapsuleSpineContract.v0/Membrane.ts",
+        "./spine-factories/CapsuleSpineFactory": "./src/spine-factories/CapsuleSpineFactory.ts",
         "./spine-factories/TimingObserver": "./src/spine-factories/TimingObserver.ts",
         "./structs/Capsule": "./structs/Capsule.ts",
         "./structs/CapsuleProjectionContext": "./structs/CapsuleProjectionContext.ts"

package/src/capsule-projectors/{CapsuleModuleProjector.v0.ts → CapsuleModuleProjector.ts}

@@ -50,7 +50,7 @@ async function constructCacheFilePath(moduleFilepath: string, importStackLine: n
  * Finds the nearest package.json and constructs an npm URI for cache files.
  * First checks if the path contains /node_modules/ and if so, extracts the portion
  * after the last /node_modules/ occurrence for consistent paths in dev and installed mode.
- * This matches the logic from static-analyzer.v0.ts
+ * This matches the logic from static-analyzer.ts
  */
 async function constructNpmUriForCache(absoluteFilepath: string, spineRoot: string): Promise<string | null> {
     // Check for /node_modules/ in the path — use the last occurrence to handle nested node_modules
@@ -742,7 +742,7 @@ export function CapsuleModuleProjector({
         const hasStandalone = hasStandaloneProperty(capsule, spineContractUri)
 
         // Add runtime imports for standalone functions
-        const runtimeImport = hasStandalone ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane.v0'\n` : ''
+        const runtimeImport = hasStandalone ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane'\n` : ''
 
         // Generate default export based on capsule type
         let defaultExport = ''
@@ -1072,7 +1072,7 @@ ${defaultExport}
             const mappedCapsuleExpression = rewriteCapsuleExpressionWithCST(mappedCapsule)
 
             // Add runtime imports for standalone functions
-            const mappedRuntimeImport = mappedHasStandalone ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane.v0'\n` : ''
+            const mappedRuntimeImport = mappedHasStandalone ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane'\n` : ''
 
             let mappedDefaultExport = ''
             if (mappedHasStandalone) {

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,
@@ -125,6 +132,7 @@ export const CapsulePropertyTypes = {
     Init: 'Init' as const,
     Dispose: 'Dispose' as const,
     OnFreeze: 'OnFreeze' as const,
+    ProxyFunction: 'ProxyFunction' as const,
 }
 
 // ##################################################
@@ -198,8 +206,8 @@ export async function SpineRuntime(options: TSpineRuntimeOptions): Promise<TSpin
 
                             // If the value is a raw capsule instance (has spineContractCapsuleInstances
                             // but is NOT a Proxy that handles API access), unwrap it
-                            // Static.v0 sets apiTarget[property.name] = mappedInstance (raw)
-                            // Membrane.v0 sets apiTarget[property.name] = new Proxy(...) which handles API access
+                            // Static sets apiTarget[property.name] = mappedInstance (raw)
+                            // Membrane sets apiTarget[property.name] = new Proxy(...) which handles API access
                             if (value && typeof value === 'object' && value.spineContractCapsuleInstances) {
                                 // Check if this is a raw capsule instance by seeing if it has .api
                                 // and the .api doesn't have the same spineContractCapsuleInstances
@@ -459,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
@@ -531,7 +539,7 @@ export async function Spine(options: TSpineOptions): Promise<TSpine> {
                             const mappedProjectionPath = mappedInstance.mappedPropertyName?.startsWith('/') ? mappedInstance.mappedPropertyName : projectionPath
                             // For regular mapped capsules (non-struct delegates), use their own CST as
                             // parentCapsuleCst so nested property contract delegates see the correct parent.
-                            // Property contract delegates (flagged by Static.v0) pass through the current
+                            // Property contract delegates (flagged by Static) pass through the current
                             // parentCapsuleCst so their OnFreeze sees the declaring capsule's CST.
                             const mappedCapsule = (!mappedInstance.isPropertyContractDelegate && mappedInstance.capsuleName) ? capsules[mappedInstance.capsuleName] : undefined
                             const childParentCst = mappedCapsule?.cst || parentCapsuleCst
@@ -665,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
@@ -673,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)!
             }
 
@@ -723,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]['#']) {
@@ -738,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
                                 }
@@ -774,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
@@ -789,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
                                 }
@@ -846,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,
@@ -925,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 || {
@@ -936,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
@@ -974,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) {
@@ -1000,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
@@ -1011,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
 
@@ -1055,6 +1089,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                             await spineContractCapsuleInstance.mapProperty({
                                 overrides,
                                 options,
+                                transitiveOverrides,
                                 property: {
                                     name: propertyName,
                                     definition: propertyDefinition,
@@ -1229,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.v0.ts → Membrane.ts}

@@ -1,5 +1,6 @@
 import { CapsulePropertyTypes } from "../../encapsulate"
-import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static.v0"
+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)
@@ -620,6 +685,86 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         })
     }
 
+    protected override mapProxyFunctionProperty({ property }: { property: any }) {
+        const selfProxy = this.createSelfProxy()
+
+        const childTargetFn = property.definition.value.target
+        const childInvokeFn = property.definition.value.invoke
+
+        // Inherit missing parts from parent's ProxyFunction (if extending)
+        const parentParts = this.self[`__proxyFn_${property.name}`]
+        const targetFn = childTargetFn ?? parentParts?.target
+        const invokeFn = childInvokeFn ?? parentParts?.invoke
+
+        if (!targetFn) throw new Error(`ProxyFunction '${property.name}': target() is required`)
+        if (!invokeFn) throw new Error(`ProxyFunction '${property.name}': invoke() is required`)
+
+        // Store parts for potential child override
+        this.self[`__proxyFn_${property.name}`] = { target: targetFn, invoke: invokeFn }
+
+        const boundProxyFn = (...args: any[]) => {
+            const transformedArgs = invokeFn.call(selfProxy, ...args)
+            const target = targetFn.call(selfProxy)
+            if (transformedArgs && typeof transformedArgs.then === 'function') {
+                return transformedArgs.then((resolved: any) => target(resolved))
+            }
+            return target(transformedArgs)
+        }
+
+        Object.defineProperty(this.encapsulatedApi, property.name, {
+            get: () => {
+                return (...args: any[]) => {
+                    const callEvent: any = {
+                        event: 'call',
+                        eventIndex: this.incrementEventIndex(),
+                        membrane: 'external',
+                        target: {
+                            capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
+                            spineContractCapsuleInstanceId: this.id,
+                            prop: property.name,
+                        },
+                        args
+                    }
+
+                    if (this.capsuleSourceNameRef) {
+                        callEvent.target.capsuleSourceNameRef = this.capsuleSourceNameRef
+                    }
+                    if (this.capsuleSourceNameRefHash) {
+                        callEvent.target.capsuleSourceNameRefHash = this.capsuleSourceNameRefHash
+                    }
+                    if (this.capsuleInstance?.capsuleSourceUriLineRefInstanceId) {
+                        callEvent.target.capsuleSourceUriLineRefInstanceId = this.capsuleInstance.capsuleSourceUriLineRefInstanceId
+                    }
+
+                    this.addCallerContextToEvent(callEvent)
+                    this.onMembraneEvent?.(callEvent)
+
+                    const previousCallerContext = this.getCurrentCallerContext()
+                    this.setCurrentCallerContext(this.buildCallerContext(property.name))
+                    const result = boundProxyFn(...args)
+                    this.setCurrentCallerContext(previousCallerContext)
+
+                    const resultEvent: any = {
+                        event: 'call-result',
+                        eventIndex: this.incrementEventIndex(),
+                        membrane: 'external',
+                        callEventIndex: callEvent.eventIndex,
+                        target: {
+                            spineContractCapsuleInstanceId: this.id,
+                        },
+                        result
+                    }
+
+                    this.onMembraneEvent?.(resultEvent)
+
+                    return result
+                }
+            },
+            enumerable: true,
+            configurable: true
+        })
+    }
+
     protected mapGetterFunctionProperty({ property }: { property: any }) {
         const getterFn = property.definition.value
         const selfProxy = this.createSelfProxy()
@@ -749,16 +894,13 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                 }
 
                 // Determine the value source and get the value
+                // Virtual dispatch: child overrides take precedence over both
+                // self and own encapsulatedApi, matching class-inheritance semantics
                 let value: any
                 let source: 'self' | 'encapsulatedApi' | 'childApi' | 'extendedApi' | undefined
 
-                if (prop in target) {
-                    value = target[prop]
-                    source = 'self'
-                } else if (prop in factory.encapsulatedApi) {
-                    value = factory.encapsulatedApi[prop]
-                    source = 'encapsulatedApi'
-                } else if (factory.childEncapsulatedApis) {
+                // Check child capsule APIs first for virtual dispatch
+                if (factory.childEncapsulatedApis) {
                     for (const childApi of factory.childEncapsulatedApis) {
                         if (prop in childApi) {
                             value = childApi[prop]
@@ -768,6 +910,16 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                     }
                 }
 
+                if (source === undefined) {
+                    if (prop in target) {
+                        value = target[prop]
+                        source = 'self'
+                    } else if (prop in factory.encapsulatedApi) {
+                        value = factory.encapsulatedApi[prop]
+                        source = 'encapsulatedApi'
+                    }
+                }
+
                 if (source === undefined && extendedApi && prop in extendedApi) {
                     value = extendedApi[prop]
                     source = 'extendedApi'
@@ -914,7 +1066,8 @@ export function CapsuleSpineContract({
     spineFilesystemRoot,
     resolve,
     importCapsule,
-    npmUriForFilepath
+    npmUriForFilepath,
+    timing
 }: {
     onMembraneEvent?: (event: any) => void
     freezeCapsule?: (capsule: any) => Promise<any>
@@ -923,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
@@ -983,7 +1137,8 @@ export function CapsuleSpineContract({
                 runtimeSpineContracts,
                 instanceRegistry,
                 extendedCapsuleInstance,
-                capsuleInstance
+                capsuleInstance,
+                timing
             })
         },
         hydrate: ({ capsuleSnapshot }: { capsuleSnapshot: any }): any => {