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

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".
 
@@ -263,6 +276,7 @@ All value types accept a `value` in their definition. `undefined` means "no defa
 | `Function` | `api.name(...args)` | `function(this, ...args)` | Callable method. Bound to self proxy. |
 | `GetterFunction` | `api.name` (no parens) | `function(this)` | Lazy getter. Evaluated on each access (unless memoized). |
 | `SetterFunction` | `api.name = value` | `function(this, value)` | Triggered on assignment. Enables validation/transformation logic. |
+| `ProxyFunction` | `api.name(...args)` | `{ target(this), invoke(this, ...args) }` | Wraps a target function with argument transformation. See below. |
 
 All function types are bound to a **self proxy** where:
 - `this.<prop>` resolves through: self → encapsulatedApi → extendedCapsuleApi
@@ -290,6 +304,60 @@ Applies to `Function` and `GetterFunction`. Added as a sibling to `type` and `va
 
 Memoize caches are scoped per spine contract capsule instance and cleared automatically when `run()` completes.
 
+#### ProxyFunction
+
+`ProxyFunction` wraps calling a target function with argument transformation. Its `value` is an object with two methods:
+
+- **`target(this)`** — resolves the function to call (bound to self proxy)
+- **`invoke(this, ...args)`** — transforms the caller's arguments before passing to target (bound to self proxy, may be async)
+
+```ts
+{
+    type: CapsulePropertyTypes.ProxyFunction,
+    value: {
+        target() { return this.service.fetchData },           // resolve target fn
+        async invoke(pathname: string) {                      // transform args
+            const origin = this.origin
+            return { url: `http://${origin}${pathname}`, headers: { Host: origin } }
+        }
+    }
+}
+```
+
+When `api.name(...args)` is called:
+1. `invoke(...args)` runs with self proxy as `this`, returning transformed args
+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.
@@ -307,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.
@@ -382,13 +450,13 @@ A capsule can inherit properties from a parent capsule:
 - `this.self` in a parent function returns the parent's own values (`ownSelf`), not the merged context.
 - Multiple capsules can extend the same parent — each gets a separate parent instance with its own `self`.
 
-### Spine Contracts: Static.v0 vs Membrane.v0
+### Spine Contracts: Static vs Membrane
 
 Both implement the same property mapping logic. The difference is observability.
 
-**Static.v0** — direct property assignment. No interception. Minimal overhead.
+**Static** — direct property assignment. No interception. Minimal overhead.
 
-**Membrane.v0** — wraps the API in proxies that emit events for every property access:
+**Membrane** — wraps the API in proxies that emit events for every property access:
 
 | Event | Emitted When | Payload |
 |---|---|---|

package/src/spine-contracts/CapsuleSpineContract.v0/{Static.v0.ts → 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) {
@@ -107,6 +112,8 @@ export class ContractCapsuleInstanceFactory {
             this.mapDisposeProperty({ property })
         } else if (property.definition.type === CapsulePropertyTypes.OnFreeze) {
             this.mapOnFreezeProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.ProxyFunction) {
+            this.mapProxyFunctionProperty({ property })
         }
     }
 
@@ -134,11 +141,77 @@ export class ContractCapsuleInstanceFactory {
 
             // Use cst.source.moduleFilepath (always filesystem-relative) for path resolution.
             // encapsulateOptions.moduleFilepath may be an npm URI when loaded from projected files.
-            const moduleFilepath = this.capsule.cst?.source?.moduleFilepath || this.capsule.encapsulateOptions?.moduleFilepath
+            // However, cst.source.moduleFilepath may be relative to a different package root than
+            // the current spineFilesystemRoot (e.g. cross-package capsule references). In that case,
+            // fall back to encapsulateOptions.moduleFilepath which is always relative to current spine root.
+            let moduleFilepath = this.capsule.cst?.source?.moduleFilepath || this.capsule.encapsulateOptions?.moduleFilepath
             if (!moduleFilepath) throw new Error(`'moduleFilepath' not available on capsule!`)
 
-            const parentPath = join(this.spineFilesystemRoot, moduleFilepath)
-            const filepath = await this.resolve(property.definition.value, parentPath)
+            // moduleFilepath may be a relative filesystem path (e.g. "../../../caps/Foo.ts")
+            // or an npm-style URI (e.g. "@stream44.studio/t44-docker.com/caps/Project")
+            // after freeze/hoist cycles. join(spineRoot, npmUri) produces a bogus path when
+            // the URI is npm-style and spineRoot is narrow. Detect this by checking if the
+            // moduleFilepath looks like an npm URI (starts with @, or doesn't start with / or .),
+            // and resolve it to get the actual filesystem path.
+            let parentPath = join(this.spineFilesystemRoot, moduleFilepath)
+            if (!moduleFilepath.startsWith('/') && !moduleFilepath.startsWith('.')) {
+                // Looks like an npm-style URI or filesystem-convention path — resolve it
+                try {
+                    // Try with @ prefix first (npm URI convention)
+                    if (moduleFilepath.startsWith('@')) {
+                        parentPath = await this.resolve(moduleFilepath, this.spineFilesystemRoot)
+                    } else {
+                        // May be a filesystem-convention path like "scope/packages/pkg/path"
+                        // Try resolving as @scope/pkg/path by extracting scope and package name
+                        const parts = moduleFilepath.split('/')
+                        if (parts.length >= 3 && parts[1] === 'packages') {
+                            const scope = parts[0]
+                            const pkg = parts[2]
+                            const subpath = parts.slice(3).join('/')
+                            const npmUri = subpath ? `@${scope}/${pkg}/${subpath}` : `@${scope}/${pkg}`
+                            parentPath = await this.resolve(npmUri, this.spineFilesystemRoot)
+                        }
+                    }
+                } catch {
+                    // Fall back to the joined path if resolution fails
+                }
+            }
+            let filepath: string
+            try {
+                filepath = await this.resolve(property.definition.value, parentPath)
+            } catch (resolveError) {
+                // cst.source.moduleFilepath may be relative to a different package root than spineFilesystemRoot
+                // (e.g. cross-package capsule references). Fall back to encapsulateOptions.moduleFilepath
+                // which is always relative to the current spine root.
+                const fallbackModuleFilepath = this.capsule.encapsulateOptions?.moduleFilepath
+                if (fallbackModuleFilepath && fallbackModuleFilepath !== moduleFilepath) {
+                    // The fallback moduleFilepath may be a relative path or an npm URI.
+                    // Apply the same resolution logic as the primary path.
+                    let fallbackParentPath = join(this.spineFilesystemRoot, fallbackModuleFilepath)
+                    if (!fallbackModuleFilepath.startsWith('/') && !fallbackModuleFilepath.startsWith('.')) {
+                        try {
+                            if (fallbackModuleFilepath.startsWith('@')) {
+                                fallbackParentPath = await this.resolve!(fallbackModuleFilepath, this.spineFilesystemRoot)
+                            } else {
+                                const parts = fallbackModuleFilepath.split('/')
+                                if (parts.length >= 3 && parts[1] === 'packages') {
+                                    const scope = parts[0]
+                                    const pkg = parts[2]
+                                    const subpath = parts.slice(3).join('/')
+                                    const npmUri = subpath ? `@${scope}/${pkg}/${subpath}` : `@${scope}/${pkg}`
+                                    fallbackParentPath = await this.resolve!(npmUri, this.spineFilesystemRoot)
+                                }
+                            }
+                        } catch {
+                            // Fall back to the joined path
+                        }
+                    }
+                    filepath = await this.resolve(property.definition.value, fallbackParentPath)
+                } else {
+                    throw resolveError
+                }
+            }
+            this.timing?.record(`resolveMappedCapsule: importCapsule(${filepath.replace(/^.*\/genesis\//, '')})`)
             mappedCapsule = await this.importCapsule(filepath)
         } else if (
             typeof property.definition.value === 'object' &&
@@ -152,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]
 
@@ -172,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 {
@@ -185,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 })
 
@@ -208,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
@@ -228,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 })
@@ -310,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
                 }
             }
@@ -326,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)
@@ -390,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
@@ -405,21 +571,29 @@ export class ContractCapsuleInstanceFactory {
 
                 // First check if the property exists in target (this.self)
                 if (prop in target) {
+                    // Virtual dispatch: if child has an override for this property,
+                    // prefer the child's version over self (which may hold the parent's bound fn)
+                    if (factory.childEncapsulatedApis) {
+                        for (const childApi of factory.childEncapsulatedApis) {
+                            if (prop in childApi) return childApi[prop]
+                        }
+                    }
                     return target[prop]
                 }
 
-                // Fall back to encapsulatedApi
-                if (prop in factory.encapsulatedApi) {
-                    return factory.encapsulatedApi[prop]
-                }
-
-                // Fall back to child capsule APIs (for parent→child function delegation)
+                // Check child capsule APIs (virtual dispatch —
+                // child overrides take precedence over parent's own API)
                 if (factory.childEncapsulatedApis) {
                     for (const childApi of factory.childEncapsulatedApis) {
                         if (prop in childApi) return childApi[prop]
                     }
                 }
 
+                // Fall back to own encapsulatedApi
+                if (prop in factory.encapsulatedApi) {
+                    return factory.encapsulatedApi[prop]
+                }
+
                 // Fall back to extended capsule's API
                 if (extendedApi && prop in extendedApi) {
                     return extendedApi[prop]
@@ -447,12 +621,12 @@ export class ContractCapsuleInstanceFactory {
             getOwnPropertyDescriptor: (target: any, prop: string | symbol) => {
                 if (typeof prop === 'symbol') return Object.getOwnPropertyDescriptor(target, prop)
                 if (prop in target) return Object.getOwnPropertyDescriptor(target, prop)
-                if (prop in factory.encapsulatedApi) return { configurable: true, enumerable: true, writable: true, value: factory.encapsulatedApi[prop as string] }
                 if (factory.childEncapsulatedApis) {
                     for (const childApi of factory.childEncapsulatedApis) {
                         if (prop in childApi) return { configurable: true, enumerable: true, writable: true, value: childApi[prop as string] }
                     }
                 }
+                if (prop in factory.encapsulatedApi) return { configurable: true, enumerable: true, writable: true, value: factory.encapsulatedApi[prop as string] }
                 if (extendedApi && prop in extendedApi) return { configurable: true, enumerable: true, writable: true, value: extendedApi[prop as string] }
                 return undefined
             }
@@ -565,6 +739,38 @@ export class ContractCapsuleInstanceFactory {
         }
     }
 
+    protected mapProxyFunctionProperty({ property }: { property: any }) {
+        const apiTarget = this.getApiTarget({ property })
+        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 }
+
+        apiTarget[property.name] = (...args: any[]) => {
+            // 1. Call invoke() bound to selfProxy to transform args
+            const transformedArgs = invokeFn.call(selfProxy, ...args)
+            // 2. Call target() bound to selfProxy to get the function to call
+            const target = targetFn.call(selfProxy)
+            // 3. If invoke returned a promise, await it then call target
+            if (transformedArgs && typeof transformedArgs.then === 'function') {
+                return transformedArgs.then((resolved: any) => target(resolved))
+            }
+            // 4. Call target with the transformed args
+            return target(transformedArgs)
+        }
+    }
+
     protected mapSetterFunctionProperty({ property }: { property: any }) {
         const apiTarget = this.getApiTarget({ property })
         const setterFn = property.definition.value
@@ -637,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()
 
@@ -658,7 +864,8 @@ export function CapsuleSpineContract({ freezeCapsule, resolve, importCapsule, sp
                 instanceRegistry,
                 extendedCapsuleInstance,
                 runtimeSpineContracts,
-                capsuleInstance
+                capsuleInstance,
+                timing
             })
         },
         hydrate: ({ capsuleSnapshot }: { capsuleSnapshot: any }): any => {