@stream44.studio/encapsulate 0.4.0-rc.19 → 0.4.0-rc.21

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-encapsulate: An experimental implementation of the https://PrivateData.Space model in TypeScript.
+encapsulate: Object encapsulation & mapping system with runtime kernel for TypeScript
 
 Copyright 2026 Christoph Dorn - https://Christoph.diy
 

package/README.md

@@ -1,8 +1,12 @@
-⚠️ **WARNING:** This repository may get squashed and force-pushed if the [GordianOpenIntegrity](https://github.com/Stream44/t44-blockchaincommons.com) implementation must change in incompatible ways. Keep your diffs until the **GordianOpenIntegrity** system is stable.
-
-🔷 **Open Development Project:** The implementation is a preview release for community feedback.
+<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>Preview release for community feedback.<br/>Get in touch on <a href="https://discord.gg/9eBcQXEJAN">discord</a>.</td>
+  </tr>
+</table>
 
-⚠️ **Disclaimer:** Under active development. Code has not been audited, APIs and interfaces are subject to change.
+⚠️ **Disclaimer:** Under active development. Code has not been audited. APIs and interfaces are subject to change!
 
 encapsulate [![Tests](https://github.com/Stream44/encapsulate/actions/workflows/test.yaml/badge.svg)](https://github.com/Stream44/encapsulate/actions/workflows/test.yaml?query=branch%3Amain)
 ===
@@ -21,17 +25,24 @@ It is being used to underpin:
   <br/><br/>
 </p>
 
-Notes
+The CAPSULE Spine Contract
 ---
 
-- The first spine contract is defined and implemented here: [src/spine-contracts/CapsuleSpineContract.v0/](src/spine-contracts/CapsuleSpineContract.v0/)
-- Projector reference implementations are here: [github.com/Stream44/ink-component-projector](https://github.com/Stream44/ink-component-projector)
+The `encapsulate` library wraps TypeScript objects and binds reference trees for constructing executable component graphs.
 
-Roadmap
----
+The binding rules are defined by **Spine Contracts**. The first *experimental* spine contract is the **Capsule Spine Contract**. It builds a model
+around **Capsules** which have certain properties.
+
+The capsule spine contract is implemented here: [src/spine-contracts/CapsuleSpineContract.v0/](src/spine-contracts/CapsuleSpineContract.v0/)
+
+### Roadmap
+
+- [ ] Private/Projected properties
+- [ ] Property annotations
+- [ ] Capsule Projectors
+- [ ] Load capsules from packs
 
-- [ ] Document [src/spine-contracts/CapsuleSpineContract.v0/](src/spine-contracts/CapsuleSpineContract.v0/)
-- [ ] Private properties
+![Capsule Spine Contract Overview](./src/spine-contracts/CapsuleSpineContract.v0/Overview.svg)
 
 
 Provenance
@@ -51,4 +62,4 @@ Repository DID: `did:repo:65bf6c297919ca938c513cdb7517605d0d62cdbf`
   </tr>
 </table>
 
-(c) 2026 [Christoph.diy](https://christoph.diy) • Code: `MIT` • Text: [GNU Free Documentation License](https://www.gnu.org/licenses/fdl-1.3.txt) • Created with [Stream44.Studio](https://Stream44.Studio)
+(c) 2026 [Christoph.diy](https://christoph.diy) • Code: [MIT](./LICENSE.txt) • Text: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) • Created with [Stream44.Studio](https://Stream44.Studio)

package/package.json

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

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

@@ -116,8 +116,8 @@ export function CapsuleModuleProjector({
     // Helper: Find custom projection path from property names starting with '/'
     function findCustomProjectionPath(capsule: any, spineContractUri: string): string | null {
         const spineContract = capsule.cst.spineContracts[spineContractUri]
-        if (spineContract?.properties) {
-            for (const propName in spineContract.properties) {
+        if (spineContract?.propertyContracts) {
+            for (const propName in spineContract.propertyContracts) {
                 if (propName.startsWith('/')) {
                     return propName.substring(1) // Remove leading '/'
                 }
@@ -131,10 +131,10 @@ export function CapsuleModuleProjector({
         const mapped: Array<{ capsuleHash: string, projectionPath: string, capsule: any }> = []
         const spineContract = capsule.cst.spineContracts[spineContractUri]
 
-        if (spineContract?.properties) {
-            for (const propName in spineContract.properties) {
+        if (spineContract?.propertyContracts) {
+            for (const propName in spineContract.propertyContracts) {
                 if (propName.startsWith('/')) {
-                    const prop = spineContract.properties[propName]
+                    const prop = spineContract.propertyContracts[propName]
                     // Check if this is a Mapping type property
                     if (prop.type === 'CapsulePropertyTypes.Mapping') {
                         // First try to find the mapped capsule in ambient references
@@ -178,7 +178,7 @@ export function CapsuleModuleProjector({
                 }
                 // Also check nested property contracts that start with '#'
                 if (propName.startsWith('#')) {
-                    const propContract = spineContract.properties[propName] as any
+                    const propContract = spineContract.propertyContracts[propName] as any
                     if (propContract?.properties) {
                         for (const nestedPropName in propContract.properties) {
                             if (nestedPropName.startsWith('/')) {
@@ -264,8 +264,8 @@ export function CapsuleModuleProjector({
         }
 
         const spineContract = capsule.cst.spineContracts[spineContractUri]
-        if (spineContract?.properties) {
-            traverseProperties(spineContract.properties)
+        if (spineContract?.propertyContracts) {
+            traverseProperties(spineContract.propertyContracts)
         }
 
         return uris
@@ -275,8 +275,8 @@ export function CapsuleModuleProjector({
     function hasSolidJsProperty(capsule: any, spineContractUri: string): boolean {
         const spineContract = capsule.cst.spineContracts[spineContractUri]
         // Check both top-level and nested under '#' property contract
-        const topLevelProps = spineContract?.properties || {}
-        const nestedProps = spineContract?.properties?.['#']?.properties || {}
+        const topLevelProps = spineContract?.propertyContracts || {}
+        const nestedProps = spineContract?.propertyContracts?.['#']?.properties || {}
 
         // Check for solidjs.com/standalone specifically
         for (const key of Object.keys(topLevelProps)) {
@@ -292,8 +292,8 @@ export function CapsuleModuleProjector({
     function hasStandaloneProperty(capsule: any, spineContractUri: string): boolean {
         const spineContract = capsule.cst.spineContracts[spineContractUri]
         // Check both top-level and nested under '#' property contract
-        const topLevelProps = spineContract?.properties || {}
-        const nestedProps = spineContract?.properties?.['#']?.properties || {}
+        const topLevelProps = spineContract?.propertyContracts || {}
+        const nestedProps = spineContract?.propertyContracts?.['#']?.properties || {}
 
         // Check for exact match or with suffix
         for (const key of Object.keys(topLevelProps)) {
@@ -310,8 +310,8 @@ export function CapsuleModuleProjector({
         const spineContract = capsule.cst.spineContracts[spineContractUri]
 
         // Check nested under '#' property contract first, looking for solidjs.com/standalone
-        const nestedProps = spineContract?.properties?.['#']?.properties || {}
-        const topLevelProps = spineContract?.properties || {}
+        const nestedProps = spineContract?.propertyContracts?.['#']?.properties || {}
+        const topLevelProps = spineContract?.propertyContracts || {}
 
         let solidjsProp = null
         for (const key of Object.keys(nestedProps)) {
@@ -370,8 +370,8 @@ export function CapsuleModuleProjector({
         const spineContract = capsule.cst.spineContracts[spineContractUri]
 
         // Check nested under '#' property contract first, looking for encapsulate.dev/standalone or encapsulate.dev/standalone/*
-        const nestedProps = spineContract?.properties?.['#']?.properties || {}
-        const topLevelProps = spineContract?.properties || {}
+        const nestedProps = spineContract?.propertyContracts?.['#']?.properties || {}
+        const topLevelProps = spineContract?.propertyContracts || {}
 
         let standaloneProp = null
         for (const key of Object.keys(nestedProps)) {
@@ -503,7 +503,7 @@ export function CapsuleModuleProjector({
 
         // Only project capsules that have the Capsule struct property
         const spineContract = capsule.cst.spineContracts[spineContractUri]
-        if (!spineContract?.properties?.['#@stream44.studio/encapsulate/structs/Capsule']) {
+        if (!spineContract?.propertyContracts?.['#@stream44.studio/encapsulate/structs/Capsule']) {
             return false
         }
 
@@ -571,11 +571,11 @@ export function CapsuleModuleProjector({
                         if (potentialMappedCapsule === capsule) continue
 
                         // Check if this capsule has the Capsule struct (meaning it should be projected)
-                        if (potentialMappedCapsule.cst?.spineContracts?.[spineContractUri]?.properties?.['#@stream44.studio/encapsulate/structs/Capsule']) {
+                        if (potentialMappedCapsule.cst?.spineContracts?.[spineContractUri]?.propertyContracts?.['#@stream44.studio/encapsulate/structs/Capsule']) {
                             // Check if this capsule's moduleFilepath is referenced in any mapping property
                             const mappedModulePath = potentialMappedCapsule.cst.source.moduleFilepath
 
-                            for (const [propContractKey, propContract] of Object.entries(spineContract.properties)) {
+                            for (const [propContractKey, propContract] of Object.entries(spineContract.propertyContracts)) {
                                 if (propContractKey.startsWith('#') && (propContract as any).properties) {
                                     for (const [propName, propDef] of Object.entries((propContract as any).properties)) {
                                         const prop = propDef as any

package/src/encapsulate.ts

@@ -1,7 +1,7 @@
 
 // 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 = 11
+const CACHE_BUST_VERSION = 18
 
 type TSpineOptions = {
     spineFilesystemRoot?: string,
@@ -522,7 +522,8 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
     }
 
     // Get capsuleName from options first, then fall back to CST if available
-    const cst = csts?.[capsuleSourceLineRef]
+    // When parseModule returns CSTs without this capsule (e.g. projected files), fall back to options.cst
+    const cst = csts?.[capsuleSourceLineRef] || options.cst
     const capsuleName = options.capsuleName || cst?.source?.capsuleName
 
     const encapsulateOptions: TEncapsulateOptions = {
@@ -613,9 +614,13 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                                     propertyContractDefinitions[spineContractUri]['#'] = {}
                                 }
 
+                                // Look up capsule object from spine registry if available (for inline capsule refs)
+                                const delegateUri = propContractUri.substring(1)
+                                const delegateCapsuleObj = spine.capsules[delegateUri]
+
                                 propertyContractDefinitions[spineContractUri]['#'][contractKey] = {
                                     type: CapsulePropertyTypes.Mapping,
-                                    value: propContractUri.substring(1),
+                                    value: delegateCapsuleObj || delegateUri,
                                     propertyContractDelegate: propContractUri,
                                     as: aliasName,
                                     // Pass options from the property contract delegate to the mapped capsule
@@ -711,13 +716,12 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 // The selfProxy in spine contracts will expose this as 'self' property
                 const ownSelf = merge({}, defaultInstance, defaultPropertyValues, ...Object.values(mergedValuesByContract))
 
-                // Capsule metadata struct will be set on self/ownSelf AFTER spine contract processing
-                // to avoid being overwritten by the empty struct marker in the definition
                 // Convert relative paths to absolute for metadata exposure
                 const absoluteCapsuleSourceLineRef = `${absoluteModuleFilepath}:${importStackLine}`
-                const capsuleMetadataStruct = {
+                const capsuleMetadataStruct: Record<string, any> = {
                     capsuleName: encapsulateOptions.capsuleName,
                     capsuleSourceLineRef: absoluteCapsuleSourceLineRef,
+                    capsuleSourceNameRefHash: cst?.capsuleSourceNameRefHash,
                     moduleFilepath: absoluteModuleFilepath,
                     // Root capsule metadata will be populated after extends chain is resolved
                     rootCapsule: {
@@ -734,23 +738,34 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 // Check CST first, then fall back to encapsulateOptions for direct capsule references
                 let extendsCapsuleValue = capsule.cst?.source?.extendsCapsule || encapsulateOptions.extendsCapsule
 
-                // If extendsCapsule is a string identifier, check if it's in ambientReferences first
+                // If extendsCapsule is a string identifier, resolve from ambient references
                 if (typeof extendsCapsuleValue === 'string') {
                     const cstAmbientRefs = capsule.cst?.source?.ambientReferences || {}
                     const runtimeAmbientRefs = encapsulateOptions.ambientReferences || {}
-                    for (const [refName, ref] of Object.entries(cstAmbientRefs)) {
-                        const refTyped = ref as any
-                        if (refName === extendsCapsuleValue) {
-                            if (refTyped.type === 'capsule' && refTyped.value) {
-                                extendsCapsuleValue = refTyped.value
-                            } else if (refTyped.type === 'instance' && runtimeAmbientRefs[refName]) {
-                                // CST stores '[instance]' placeholder; resolve from runtime ambient refs
-                                const runtimeRef = runtimeAmbientRefs[refName]
-                                if (runtimeRef && typeof runtimeRef === 'object' && typeof runtimeRef.makeInstance === 'function') {
-                                    extendsCapsuleValue = runtimeRef
+
+                    // First: try runtime ambient refs directly (capsule objects with .makeInstance)
+                    if (runtimeAmbientRefs[extendsCapsuleValue]) {
+                        const runtimeRef = runtimeAmbientRefs[extendsCapsuleValue]
+                        if (runtimeRef && typeof runtimeRef === 'object' && typeof runtimeRef.makeInstance === 'function') {
+                            extendsCapsuleValue = runtimeRef
+                        }
+                    }
+
+                    // Second: try CST ambient refs if still a string
+                    if (typeof extendsCapsuleValue === 'string') {
+                        for (const [refName, ref] of Object.entries(cstAmbientRefs)) {
+                            const refTyped = ref as any
+                            if (refName === extendsCapsuleValue) {
+                                if (refTyped.type === 'capsule' && refTyped.value) {
+                                    extendsCapsuleValue = refTyped.value
+                                } else if (refTyped.type === 'instance' && runtimeAmbientRefs[refName]) {
+                                    const runtimeRef = runtimeAmbientRefs[refName]
+                                    if (runtimeRef && typeof runtimeRef === 'object' && typeof runtimeRef.makeInstance === 'function') {
+                                        extendsCapsuleValue = runtimeRef
+                                    }
                                 }
+                                break
                             }
-                            break
                         }
                     }
                 }
@@ -824,6 +839,14 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     rootCapsule: resolvedRootCapsule
                 }
 
+                // Set capsule metadata struct on self early so it's available in options() callbacks during mapping
+                if (!self['#@stream44.studio/encapsulate/structs/Capsule'] ||
+                    typeof self['#@stream44.studio/encapsulate/structs/Capsule'] !== 'object' ||
+                    !self['#@stream44.studio/encapsulate/structs/Capsule'].capsuleName) {
+                    self['#@stream44.studio/encapsulate/structs/Capsule'] = capsuleMetadataStruct
+                }
+                ownSelf['#@stream44.studio/encapsulate/structs/Capsule'] = capsuleMetadataStruct
+
                 // Use runtime spine contracts if provided, otherwise fall back to encapsulation spine contracts
                 const activeSpineContracts = runtimeSpineContracts || spine.spineContracts
 
@@ -853,10 +876,18 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                         if (propertyContractUri !== '#') {
                             continue
                         }
+                        // Get CST property definitions for this spine contract to merge depends
+                        const cstProperties = cst?.spineContracts?.[spineContractUri]?.propertyContracts?.[propertyContractUri]?.properties
+
                         for (const [propertyName, propertyDefinition] of Object.entries(properties)) {
 
                             if (!propertyDefinition.type || !(propertyDefinition.type in CapsulePropertyTypes)) throw new Error(`Type '${propertyDefinition.type}' for property '${propertyName}' on spineContract '${spineContractUri}' not set or supported!`)
 
+                            // Merge CST depends into property definition (CST is authoritative)
+                            const cstDepends = cstProperties?.[propertyName]?.depends
+                            if (cstDepends && !propertyDefinition.depends) {
+                                propertyDefinition.depends = cstDepends
+                            }
                             await spineContractCapsuleInstance.mapProperty({
                                 overrides,
                                 options,
@@ -866,17 +897,17 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                                     propertyContractUri
                                 }
                             })
+
+                            // Re-set capsule metadata after the Capsule struct delegate mapping overwrites self
+                            if (propertyDefinition.propertyContractDelegate === '#@stream44.studio/encapsulate/structs/Capsule') {
+                                self[propertyName] = capsuleMetadataStruct
+                            }
                         }
                     }
                 }
 
-                // Set capsule metadata struct on self/ownSelf AFTER spine contract processing
-                // to avoid being overwritten by the empty struct marker in the definition
-                if (!self['#@stream44.studio/encapsulate/structs/Capsule'] ||
-                    typeof self['#@stream44.studio/encapsulate/structs/Capsule'] !== 'object' ||
-                    !self['#@stream44.studio/encapsulate/structs/Capsule'].capsuleName) {
-                    self['#@stream44.studio/encapsulate/structs/Capsule'] = capsuleMetadataStruct
-                }
+                // Ensure capsule metadata struct is set on ownSelf after spine contract processing
+                // (self may have been updated by the extends chain; ownSelf always reflects this capsule)
                 ownSelf['#@stream44.studio/encapsulate/structs/Capsule'] = capsuleMetadataStruct
 
                 // Collect lifecycle functions and mapped capsule instances from all spine contract capsule instances

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

@@ -127,10 +127,12 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
 
         // delegateOptions is set by encapsulate.ts for property contract delegates
         // options can be a function or an object for regular mappings
+        // Always pass { self, constants } - self is populated when depends is specified, empty otherwise
+        const optionsFn = property.definition.options
         const mappingOptions = property.definition.delegateOptions
-            || (typeof property.definition.options === 'function'
-                ? await property.definition.options({ constants })
-                : property.definition.options)
+            || (typeof optionsFn === 'function'
+                ? await optionsFn({ self: property.definition.depends ? this.self : {}, constants })
+                : optionsFn)
 
         // Check for existing instance in registry - reuse if available (regardless of options)
         // Pre-registration with null allows parent capsules to "claim" a slot before child capsules process
@@ -333,7 +335,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
             // This avoids triggering the proxy and firing unwanted membrane events
             const delegateTarget = this.encapsulatedApi[property.definition.propertyContractDelegate]
             const mappedCapsuleCst = mappedCapsule.cst
-            const spineContractProperties = mappedCapsuleCst?.spineContracts?.[this.spineContractUri]?.properties
+            const spineContractProperties = mappedCapsuleCst?.spineContracts?.[this.spineContractUri]?.propertyContracts
 
             if (spineContractProperties) {
                 for (const [key, propDef] of Object.entries(spineContractProperties)) {