Source build: README build path, and ns.dependency aborting the boot — bugs or misuse?

[rustamwin]

I spent a few days evaluating Wippy from a source build and hit two things right at the start. Both have workarounds, but I couldn't tell from the docs whether they're bugs or my own misuse — hence Q&A rather than a bug report. Issues are disabled on this repo, so apologies if this is the wrong venue.

Environment: commit 4da90cc (fix(s3): reject nil upload readers (#566), 2026-08-10), go1.26.5, darwin/arm64. wippy version prints dev unknown on a source build, so I'm citing the commit.

---

1. The README's build command points at a directory that doesn't exist

README.md:115 says:

go build -o wippy ./cmd/runner/

But cmd/ contains only internal/ and wippy/. The command that works is:

go build -o wippy ./cmd/wippy/

Happy to open a PR for the one-line fix if that's welcome.

---

2. Any ns.dependency entry aborts the boot with invalid dependency resolution

This one I'm genuinely unsure about. The docs and tutorials show ns.dependency as the way to wire a framework module into an app, e.g.:

- name: dep.llm
  kind: ns.dependency
  component: wippy/llm
  parameters:
    - name: env_storage
      value: app:os_env
    - name: process_host
      value: app:processes

With any such entry present, the boot fails:

ERROR run  entry loading failed
  {"error": "failed to save new version: invalid dependency resolution"}

I narrowed it down as follows:

• With parameters: → fails
• With component: only, no parameters: → fails identically
• With the ns.dependency entry removed entirely → boots to runtime ready

So it's the entry kind itself, not the parameter wiring. Removing it and declaring the app's resources directly (env.storage.os, process.host, http.service, http.router, db.sql.sqlite) gets to a clean boot — but then the hub modules' own internal env.variable and http.endpoint entries have unresolved storage: / meta.router: fields, which I ended up filling in with 23 wippy run --override flags. That works, but it's clearly not the intended path, and the runtime reports 8 unresolved requirements (wippy.bootloader:application_host, wippy.migration:app_db, wippy.session:api_router, etc.) that I assume ns.dependency is meant to supply.

Questions:

1. Is ns.dependency expected to work on this commit, or is it mid-refactor?
2. If it is expected to work, is there something my project layout is missing? I ran wippy init, then wippy add for each module, then wippy install.
3. If it isn't, what's the current intended way to supply a module's required parameters declaratively?

Also a small related note: wippy search wippy/migration returns "No modules found", while wippy add wippy/migration resolves and installs it fine. Searching the bare name (wippy search migration) does find it. That led me to briefly conclude the module wasn't published, so it may be worth a look.

---

For context, I was evaluating Wippy as a possible replacement for a Temporal-based agent workflow engine. The evaluation went well on the whole — the dataflow module, signal nodes, and the ABAC tenant isolation all did what I needed. These two were the main friction in getting started, and I'd rather report them than leave them for the next person.

[sueun-dev]

That's a real README typo, not your mistake. On 4da90cc there's no cmd/runner/ at all, so go build -o wippy ./cmd/runner/ dies with stat .../cmd/runner: directory not found. Under cmd/ the only main package is cmd/wippy (everything else there is a cmd/internal/* lib), and ./cmd/wippy/ builds fine, giving the same "dev unknown" binary you got. The Makefile points every build target at ./cmd/wippy/ too, so a one-line README PR pointing there is exactly right.

I only looked at #1. The ns.dependency boot failure needs a full app config to reproduce, so I left that one for the maintainers.

[wolfy-j]

Yeah, some files run a bit outdated, we will take care of it.

[wolfy-j]

Thanks for the detailed report. I checked this against current runtime main (2026-09-23), since your reproduction used the August commit.

1. The README build path was still wrong. PR fix(cli): resolve qualified module searches exactly #836 changes it to ./cmd/wippy/.
2. The generic invalid dependency resolution error from a versionless controlling ns.dependency has since been addressed by Identify dependencies missing a controlling version #647. A controlling dependency now needs a version constraint; use version: "*" for an unconstrained selection. If omitted, current main reports the specific entry and missing field instead of failing later while saving history. Your parameters were not the cause. I have not reproduced your entire application boot, so I cannot claim that adding the version resolves every requirement in that project.
3. The qualified search issue still reproduced today: wippy search wippy/migration returned no modules, while wippy search migration found it. PR fix(cli): resolve qualified module searches exactly #836 makes qualified org/module queries use an exact lookup. I verified the patched CLI against the live Hub.

The CLI and dependency package tests pass locally; #836 is awaiting its normal CI review.