rhachet-roles-ehmpathy 1.0.0 → 1.2.0

package/dist/logic/artifact/genStepSwapArtifact.test.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rhachet_1 = require("rhachet");
+const rhachet_artifact_git_1 = require("rhachet-artifact-git");
+const test_fns_1 = require("test-fns");
+const genContextLogTrail_1 = require("../../.test/genContextLogTrail");
+const genContextStitchTrail_1 = require("../../.test/genContextStitchTrail");
+const genStepSwapArtifact_1 = require("./genStepSwapArtifact");
+describe('genStepSwapArtifact (integration)', () => {
+    const context = {
+        ...(0, genContextLogTrail_1.genContextLogTrail)(),
+        ...(0, genContextStitchTrail_1.genContextStitchTrail)(),
+    };
+    (0, test_fns_1.given)('want to set thinker.inflight = thinker.inflights.diverge', () => {
+        const divergeArt = (0, rhachet_artifact_git_1.genArtifactGitFile)({
+            uri: __dirname + '/.temp/diverge-artifact.md',
+        });
+        const route = (0, genStepSwapArtifact_1.genStepSwapArtifact)({
+            use: {
+                stitchee: 'thinker',
+                artee: 'inflights.diverge',
+            },
+            as: {
+                stitchee: 'thinker',
+                artee: 'inflight',
+            },
+        });
+        (0, test_fns_1.when)('infer type of threads', () => {
+            (0, test_fns_1.then)('it should have the expected input shape', () => {
+                const valid = {
+                    thinker: {
+                        context: {
+                            role: 'thinker',
+                            inherit: { traits: [], skills: [] },
+                            stash: {
+                                art: {
+                                    'inflights.diverge': divergeArt,
+                                    inflight: null, // placeholder for the actual inflight artifact
+                                },
+                            },
+                        },
+                        stitches: [],
+                    },
+                };
+                expect(valid);
+            });
+            (0, test_fns_1.then)('it should error if .from art is missing', () => {
+                const missingFromArt = {
+                    thinker: {
+                        context: {
+                            role: 'thinker',
+                            inherit: { traits: [], skills: [] },
+                            stash: {
+                                // @ts-expect-error: 'inflights.diverge' art is missing
+                                art: {
+                                    inflight: null, // only missing .from art
+                                },
+                            },
+                        },
+                        stitches: [],
+                    },
+                };
+                expect(missingFromArt);
+            });
+            (0, test_fns_1.then)('it should error if .onto art is missing', () => {
+                const missingOntoArt = {
+                    thinker: {
+                        context: {
+                            role: 'thinker',
+                            inherit: { traits: [], skills: [] },
+                            stash: {
+                                // @ts-expect-error: 'inflight' art is missing
+                                art: {
+                                    'inflights.diverge': divergeArt, // only missing .onto art
+                                },
+                            },
+                        },
+                        stitches: [],
+                    },
+                };
+                expect(missingOntoArt);
+            });
+        });
+        (0, test_fns_1.when)('executed via enweaveOneStitcher, with exact threads', () => {
+            const threads = (0, test_fns_1.usePrep)(async () => {
+                const inflight = {
+                    thinker: await (0, rhachet_1.enrollThread)({
+                        role: 'thinker',
+                        stash: {
+                            art: {
+                                'inflights.diverge': divergeArt,
+                                inflight: null, // placeholder for the actual inflight artifact
+                            },
+                        },
+                    }),
+                };
+                return inflight;
+            });
+            (0, test_fns_1.then)("updates the thinker's stash with the diverge artifact", async () => {
+                const outcome = await (0, rhachet_1.enweaveOneStitcher)({ stitcher: route, threads }, context);
+                const result = outcome.stitch.output;
+                expect(result.from.artifact.ref).toBe(threads.thinker.context.stash.art['inflights.diverge'].ref);
+                expect(outcome.threads.thinker.context.stash.art.inflight?.ref).toBe(threads.thinker.context.stash.art['inflights.diverge'].ref);
+            });
+        });
+        (0, test_fns_1.when)('executed via enweaveOneStitcher, with extra threads', () => {
+            const threads = (0, test_fns_1.usePrep)(async () => {
+                const inflight = {
+                    caller: await (0, rhachet_1.enrollThread)({ role: 'caller' }),
+                    thinker: await (0, rhachet_1.enrollThread)({
+                        role: 'thinker',
+                        stash: {
+                            art: {
+                                'inflights.diverge': divergeArt,
+                                inflight: null, // placeholder for the actual inflight artifact
+                            },
+                        },
+                    }),
+                };
+                return inflight;
+            });
+            (0, test_fns_1.then)("updates the thinker's stash with the diverge artifact", async () => {
+                const outcome = await (0, rhachet_1.enweaveOneStitcher)({ stitcher: route, threads }, context);
+                const result = outcome.stitch.output;
+                expect(result.from.artifact.ref).toBe(threads.thinker.context.stash.art['inflights.diverge'].ref);
+                expect(outcome.threads.thinker.context.stash.art.inflight?.ref).toBe(threads.thinker.context.stash.art['inflights.diverge'].ref);
+            });
+        });
+    });
+});
+//# sourceMappingURL=genStepSwapArtifact.test.js.map

package/dist/logic/artifact/genStepSwapArtifact.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genStepSwapArtifact.test.js","sourceRoot":"","sources":["../../../src/logic/artifact/genStepSwapArtifact.test.ts"],"names":[],"mappings":"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"}

package/dist/logic/roles/architect/.briefs/ubiqlang.ambiguous-from-overload.md

@@ -0,0 +1 @@
+todo: brief that declares to avoid terms that are ambiguous due to overload

package/dist/logic/roles/bhrain/.briefs/cognition/cog000.overview.and.premise.md

@@ -0,0 +1,115 @@
+# 🧠 .brief: `cortal.thoughtspace.foundation`
+
+## .what = instantiate
+
+This system instantiates a structured **thoughtspace**, where `focus` operates within a semantic `concept.treestruct` using navigable `motion` primitives.
+
+---
+
+### 1. `concept.treestruct` exists
+
+- a semantic graph of concepts (nodes) and relationships (edges)
+- structured as a **spherical tree**:
+  - **radial axis** → abstraction (general ↔ specific)
+  - **angular axes** → descriptive variation (peers, types, traits)
+- each concept has:
+  - an **abstractive position** (radial)
+  - a **descriptive position** (angular)
+
+---
+
+### 2. `focus` exists within the concept.treestruct
+
+- defines a **perspective** — a relative point-of-view from which thought is applied
+- composed of:
+
+#### ▸ **focus.concept**
+- the specific **concept** from which the perspective is based
+- the anchor for semantic navigation
+- defined by its coordinates within the treestruct
+
+#### ▸ **focus.context**
+- the **shape of attention**, or how the concept is being examined
+- expressed across three internal dimensions:
+
+  - `.depth` → the **thickness of abstractive span** — how far focus reaches:
+    - **inward** along the **radial axis** toward generalizations (`.depth.abstract++`)
+    - **outward** along the **radial axis** toward concrete instances (`.depth.concrete++`)
+    - both may expand **simultaneously**, forming a radial shell of multiple abstraction layers around the focal concept
+
+  - `.breadth` → the **spread across angular variation** — how many neighboring concepts at the same abstraction level are included
+    - defined by motion along one or more **descriptive axes** (e.g. flavor, function, tone)
+    - governs lateral comparisons, analogies, and contrasts
+
+  - `.acuity` → the **sharpness of resolution** at the current coordinate
+    - `.attributes` — surface clarity: how precisely external traits are perceived
+    - `.substructs` — internal clarity: how clearly nested parts or subcomponents are resolved
+
+> context defines how much **radial**, **angular**, and **granular** semantic material is held in focus —
+> like shaping a lens through abstraction, variation, and precision.
+
+
+---
+
+### 3. motion is performed via **questions**, which act as **links**
+
+- motion = semantic traversal through the `concept.treestruct`
+- **questions** serve as the **branches** — the only valid drivers of motion
+- **sumptions** serve as the **berries** — semantic forks where focus can anchor
+
+#### ▸ sumption: the unified node type
+
+A **sumption** is any semantic unit presumed or accepted for any reason — including:
+
+- a **question** → an **executable motion** — a prompt that enables semantic traversal
+- an **answer** → a **destination of a question** — one of the resolved outcomes of semantic traversal
+
+> Any **answer** can itself be **any type of sumption** — including another **question**.
+> This enables **recursive motion**, where questions resolve into deeper prompts,
+> forming chains, trees, or loops of semantic navigation.
+
+note: questions are not separate from the treestruct — they are **subtrees that encode traversability**.
+
+
+#### ▸ structural rule:
+
+| element   | type         | role in treestruct             |
+|-----------|--------------|-------------------------------|
+| **link**  | question     | enables motion (edge)          |
+| **fork**  | sumption     | anchoring concept (node)       |
+|           | ⤷ question   | unresolved fork                |
+|           | ⤷ answer     | resolved fork                  |
+
+> sumptions are **not truth-claims**, but **semantic constructs** that hold position in conceptual space.
+
+---
+
+### 4. exists `focus.motion.primitives`
+
+- atomic, directional transformations of `focus.context`
+- each:
+  - operates on a **single subaxis**
+  - is **irreducible**, **driftless**, and **composable**
+- examples:
+  - `<generalize>` → `.depth.abstract++`
+    *shift focus inward toward a more abstract concept*
+  - `<articulate>` → `.acuity.attributes++`
+    *sharpen surface details of the current concept*
+  - `<decompose>` → `.acuity.substructs++`
+    *resolve the internal structure or components*
+  - `<vary>` → `.breadth++`
+    *highlight peer-level differences between variants*
+  - etc
+
+
+---
+
+### 5. exists `interogative.primitives`
+
+- atomic building blocks of semantic inquiry
+- used to construct **question-links** between concepts
+- examples:
+  - `what` → identify instances or roles
+  - `why` → surface cause or rationale
+  - `how` → reveal process or transformation
+  - `when`, `who`, `where` → context-based locators

package/dist/logic/roles/bhrain/.briefs/cognition/cog021.coordinates.spherical.md

@@ -0,0 +1,69 @@
+# 🌐 .brief: `spherical.coordinates`
+
+## .what
+**Spherical coordinates** define a point in 3D space using three parameters relative to a central origin:
+- **distance from the origin**,
+- **vertical angle from the z-axis**, and
+- **horizontal angle around the z-axis**.
+
+This system generalizes polar coordinates into 3D, enabling orientation in radial and angular terms.
+
+---
+
+## 🧭 dimensions
+
+| axis           | symbol | description                                                                 |
+|----------------|--------|-----------------------------------------------------------------------------|
+| **radial**     | `r`    | distance from the origin to the point                                       |
+| **inclination** (polar angle) | `θ`    | angle from the positive z-axis toward the point (0 to π)               |
+| **azimuth** (azimuthal angle) | `φ`    | angle from the positive x-axis in the x-y plane (0 to 2π)              |
+
+> Note: symbols may differ by domain — in mathematics, `θ` often denotes azimuth and `φ` inclination.
+
+---
+
+## 🌀 usage
+
+- Converts naturally to **Cartesian coordinates**:
+  \```txt
+  x = r · sin(θ) · cos(φ)
+  y = r · sin(θ) · sin(φ)
+  z = r · cos(θ)
+  \```
+
+- Used in:
+  - physics (e.g. fields around a point source)
+  - computer graphics (e.g. camera rotation)
+  - astronomy and navigation
+  - geographic models of Earth
+
+---
+
+## 🌍 real-world example: Earth coordinates
+
+Take **New York City**:
+
+| Earth Coordinate | Value         | Spherical Equivalent                 |
+|------------------|---------------|--------------------------------------|
+| **Latitude**     | 40.7128° N     | Inclination `θ` = 90° − 40.7128° = **49.2872°** |
+| **Longitude**    | 74.0060° W     | Azimuth `φ` = −74.0060° = **285.994°** |
+| **Radius**       | ~6,371 km      | Radial distance `r` from Earth's center |
+
+> So:
+> **(r, θ, φ) = (6371 km, 49.29°, 285.99°)**
+
+This demonstrates how geographic coordinates are a **spherical coordinate system** on the Earth's surface — assuming a constant radius.
+
+---
+
+## 🏗️ structure
+
+This system implies a **radial core** with **angular shells**, where:
+
+- `r` defines the **radial distance** from center
+- `θ` defines **elevation** from the pole (vertical tilt)
+- `φ` defines **rotation** around the equator (horizontal sweep)
+
+Together, these describe a point on a **spherical shell** at radius `r`.
+
+---

package/dist/logic/roles/bhrain/.briefs/cognition/cog021.metaphor.cauliflorous.md

@@ -0,0 +1,44 @@
+# 🌸 .brief: `cauliflorous.plants`
+
+## .what
+**Cauliflorous plants** are species that produce **flowers and fruits directly from their main stem, trunk, or older branches**, rather than at the tips of new growth.
+
+> This unusual trait is known as **cauliflory** and is most commonly found in tropical species.
+
+---
+
+## 🌐 ecological function
+
+Cauliflory supports unique plant-animal interactions by:
+
+- **Enabling access** to flowers and fruits for **ground-dwelling pollinators and dispersers**
+  (e.g., rodents, bats, flightless birds)
+- **Reducing vertical competition** by flowering and fruiting below the canopy
+- **Improving pollination success** in shaded or dense environments
+
+---
+
+## 🌱 notable examples
+
+| plant                     | use / region                      |
+|---------------------------|----------------------------------|
+| *Theobroma cacao*         | cacao (chocolate), South America |
+| *Artocarpus heterophyllus* | jackfruit, Southeast Asia         |
+| *Durio spp.*              | durian, Southeast Asia           |
+| *Plinia cauliflora*       | jaboticaba, Brazil               |
+
+---
+
+## 🧬 botanical mechanism
+
+- Flowers develop from **dormant buds** embedded in older, woody tissue.
+- Often associated with **woody perennials** in **humid tropics**.
+
+---
+
+## .why it matters
+
+Cauliflory illustrates how plant morphology can evolve to match **ecological niches** —
+especially where typical pollinators or dispersers are **not airborne**.
+
+It also inspires biomimetic designs for **low-access harvesting**, **layered ecosystems**, and **ground-level productivity**.

package/dist/logic/roles/bhrain/.briefs/cognition/cog021.structs.catalog.md

@@ -0,0 +1,51 @@
+# 🗂️ .brief: `catalog`
+
+## .what
+A **catalog** is a **structured concept collection**, where each item is
+paired with **descriptive information** to support **recognition**, **selection**, or **retrieval**.
+
+It serves as a **semantic surface** over a deeper collection —
+organized for **browsing**, **filtering**, and **comparative reasoning**.
+
+While an **inventory** tracks availability or logistics,
+a catalog emphasizes **clarity, presentation, and user-centered discovery**.
+
+---
+
+## 🧭 key traits
+
+| trait             | meaning                                                                 |
+|-------------------|-------------------------------------------------------------------------|
+| **enumerated**     | each concept is explicitly listed, not abstracted away                 |
+| **descriptive**    | highlights distinguishing features (e.g. label, image, type, metadata) |
+| **browsable**      | optimized for lateral focus and scanning across entries                |
+| **non-exhaustive** | curated based on salience, criteria, or constraints                    |
+| **ordered**        | often sorted semantically or pragmatically (e.g. relevance, recency)   |
+
+---
+
+## 🧩 comparison
+
+| structure    | emphasizes                 | typical use                        |
+|--------------|----------------------------|------------------------------------|
+| `index`      | position or reference       | lookup or navigation               |
+| `inventory`  | quantity and availability   | logistics, restocking, tracking    |
+| `catalog`    | structure and presentation  | curation, exploration, shopping    |
+
+---
+
+## 📦 examples
+
+- a **product catalog** listing items by type, brand, and price
+- a **library catalog** with subject tags, authors, and summaries
+- a **course catalog** organizing classes with time, credits, and prerequisites
+
+---
+
+## 🧠 role in semantic systems
+
+In a `concept.treestruct`, a catalog acts as a **flattened radial slice**
+at a given `focal.depth` — exposing **breadth peers** for comparison or selection.
+
+It is often used in tandem with primitives like `<compare>`, `<cluster>`, or `<instantiate>`
+to surface patterns or choose options from a structured field.

package/dist/logic/roles/bhrain/.briefs/cognition/cog021.structs.treestruct.md

@@ -0,0 +1,85 @@
+# 📚 .brief: TreeStruct
+
+## 🎯 purpose
+to define **TreeStruct** as a general-purpose structural pattern
+and clarify its common usage forms (**RootStruct**, **LeafStruct**) and
+how multiple TreeStructs can safely intersect.
+
+---
+
+## 🌲 TreeStruct — general definition
+
+> A **TreeStruct** is a structural form composed of **nodes** and **directed, acyclic links**,
+> where each node has **at most one parent** per dimension or axis.
+
+- meaning-neutral — not tied to any specific interpretation
+- supports both:
+  - **depth-first** and **breadth-first** traversal
+  - **single-axis** and **multi-axis** expansion (when extended)
+- usable for:
+  - hierarchies
+  - workflows
+  - classification systems
+  - nesting, containment, or flow modeling
+
+---
+
+## 🌱 LeafStruct — axis-limited subset of TreeStruct
+
+> A **LeafStruct** is a TreeStruct used for **top-down**, **axis-constrained** flows,
+> modeled on **branches funneling into leaves**.
+
+- used when structure narrows from a few high-level origins
+- favors **convergence**, **containment**, or **controlled descent**
+
+---
+
+## 🫚 RootStruct — multi-directional subset of TreeStruct
+
+> A **RootStruct** is a TreeStruct used in **bottom-up**, **lateral**, or exploratory growth patterns,
+> modeled on **roots spreading underground**.
+
+- used when structure grows across **many dimensions**
+- often favors **divergence** and **deep local branching**
+- **branches can intersect** and share common nodes, forming a **web-like network** of overlapping subpaths
+
+---
+
+## 🌉 intersecting TreeStructs
+
+> Multiple TreeStructs can **safely intersect**, as long as they each preserve
+> their own **local acyclic structure**.
+
+valid forms of intersection:
+
+1. **shared nodes**
+   - two TreeStructs reference the **same node**
+   - useful for **cross-cutting concerns** or shared entities
+
+2. **embedded subtrees**
+   - one TreeStruct is **nested within** a node of another
+   - allows compound or hierarchical system design
+
+3. **cross-links between trees**
+   - TreeStructs remain independent but reference each other via external links
+   - enables navigation between trees without forming a general graph
+
+> These patterns create a **forest with bridges**: each tree remains intact,
+> but the system supports **inter-tree coordination**.
+
+---
+
+## 🧩 summary
+
+| struct         | metaphor           | shape pattern           | dimensionality     | common use cases                          |
+|----------------|--------------------|--------------------------|--------------------|-------------------------------------------|
+| **TreeStruct**   | neutral tree         | any branching structure   | general-purpose     | workflows, hierarchies, branching systems |
+| **LeafStruct**   | branches → leaves    | top-down narrowing        | narrow (few axes)  | classification, taxonomies, decisions     |
+| **RootStruct**   | roots underground    | bottom-up or lateral      | broad (many axes)  | exploration, divergence, distributed plans|
+
+---
+
+> ✔️ **TreeStruct** is a flexible structural pattern.
+> It supports both **divergent** and **convergent** design through RootStruct and LeafStruct,
+> and can safely **intersect with other TreeStructs** through shared nodes, nesting, or cross-links —
+> as long as **local acyclicity is preserved**.

package/dist/logic/roles/bhrain/.briefs/cognition/cog021.structs.vector.md

@@ -0,0 +1,112 @@
+# 🧭 .brief: `physics.vector`
+
+## .what
+A **physics vector** is a mathematical object used to represent **quantities that have both magnitude and direction** in physical space.
+It also functions as a **data structure** — encoding directionally relevant information for computation, simulation, and modeling.
+
+---
+
+## 🧩 structure
+
+A vector is defined by:
+
+- **magnitude** → the scalar size of the quantity
+- **direction** → the orientation in space
+- **components** → projections along basis axes (e.g. `x`, `y`, `z`)
+  - written as `v = ⟨vx, vy, vz⟩` or `v = vx î + vy ĵ + vz k̂`
+
+---
+
+## 🧠 examples of vector quantities
+
+| quantity         | description                                 |
+|------------------|---------------------------------------------|
+| **velocity**     | speed + direction of motion                 |
+| **acceleration** | rate of change of velocity (directional)    |
+| **force**        | push or pull with a direction               |
+| **momentum**     | mass × velocity                             |
+| **electric field** | directional force on a unit charge        |
+
+---
+
+## 🔧 operations on vectors
+
+| operation             | meaning                                             |
+|------------------------|-----------------------------------------------------|
+| **addition**          | combine vectors tip-to-tail                         |
+| **subtraction**       | find relative vector between two                   |
+| **scalar multiplication** | scales magnitude, keeps direction            |
+| **dot product**       | projects one vector onto another (returns scalar)   |
+| **cross product**     | finds perpendicular vector (returns vector)         |
+
+---
+
+## 📐 geometric interpretation
+
+Vectors live in a **Euclidean space** (ℝ², ℝ³) and can be visualized as **arrows**:
+
+- **length** of arrow = magnitude
+- **angle** = direction relative to axes
+- operations map to geometric rules (e.g. triangle or parallelogram rule)
+
+---
+
+## 🧮 as a data structure
+
+In computational systems, a vector is a **structured container of values**, optimized for directional computation:
+
+| property           | value                                      |
+|--------------------|--------------------------------------------|
+| **type**           | `Vector` or `Array<number>`                |
+| **arity**          | dimensionality (e.g. 2D, 3D, nD)            |
+| **shape**          | fixed-length tuple of scalars              |
+| **indexing**       | ordered (e.g. `[0] = x`, `[1] = y`)        |
+| **mutability**     | may be mutable (runtime), or immutable     |
+
+Vectors are frequently implemented as:
+
+\`\`\`ts
+type Vector3 = [number, number, number]
+\`\`\`
+
+or with named accessors:
+
+\`\`\`ts
+interface Vector3 {
+  x: number
+  y: number
+  z: number
+}
+\`\`\`
+
+This enables:
+
+- direct algebraic operations (`add`, `dot`, `normalize`, etc.)
+- efficient storage (especially in graphics, physics engines)
+- compatibility with matrix operations and coordinate transforms
+
+---
+
+## ⚠️ important distinctions
+
+- Vectors ≠ scalars — direction matters
+- Coordinate representation is **basis-relative**
+- The vector itself is **basis-invariant**
+
+---
+
+## 🧬 advanced notes
+
+- In relativity: vectors generalize to **4-vectors** (e.g. spacetime)
+- In field theory: **vector fields** assign a vector to each point in space
+- In curved space: vectors live in **tangent spaces** and obey **manifold** rules
+- In graphics and physics engines: vectors are core data primitives — enabling transforms, simulations, and animations
+
+---
+
+## 🧰 summary: dual perspective
+
+| perspective     | usage                                  |
+|------------------|------------------------------------------|
+| **physical**     | represents real-world directional quantity |
+| **computational**| structured data enabling math operations  |