jschoubben
87f4f29cc6
ADR 0027 — the product is Novox Mesh, shortened to mesh internally. HAL was never chosen: it arrived with the dotfiles repository this grew out of, it is borrowed, and it is borrowed from the canonical untrustworthy machine intelligence, which is an odd flag for infrastructure trusted with credentials. Timing is the substance of the decision, not an aside — the skeleton is not built, so renaming costs a search and replace now and a migration later. Nox is an identity of Novox, and specifically the agent of the MESH rather than of a node. Nodes keep their own identities. Nox addresses them, and a human mostly talks to Nox — which makes it the concrete form of the mission's vision: state an intent, and the mesh works out which node holds the thing. It holds no private channel. The gap this opens is recorded: ADR 0012 binds every agent to a home node, and a mesh-scoped agent has none, so the model needs extending. ADR 0028 — HQ is company-scoped, novox/hq, with the mesh as its first product. Checked rather than assumed: the company organisation already holds live projects that the mesh builds and deploys, so they are tenants rather than peers, and the mesh is the ground they stand on. There is also company work outside the mesh already, which strengthens the case and means the eventual split is closer than "some day" — so each document's scope is fixed now, in a table, making that split mechanical instead of archaeological. The folders are deliberately not restructured yet. The skeleton takes the new vocabulary: mesh-host, mesh-substrate, mesh-control, mesh-surfaces, mesh-catalog. Substrate drops to four services now that identity is a hosted workload rather than a dependency. Research 009 opens the migration, with the reframing that lowers its risk: replace the control plane, do not move the workloads. Their data never moves, so it is re-declared rather than adopted — which keeps adoption out of scope, as the lab design requires. Self-hosting is the last phase, or a failed cutover takes away the means to fix it.
52 lines
3.0 KiB
Markdown
52 lines
3.0 KiB
Markdown
---
|
|
status: canonical
|
|
updated: 2026-08-23
|
|
---
|
|
|
|
# The Novox repositories
|
|
|
|
The map of where implementation lives. Humans use it for orientation; agents use it for issue
|
|
triage (playbook [`process/03-issues.md`](process/03-issues.md)). The `code:` frontmatter
|
|
field in design documents points at entries here.
|
|
|
|
Repository *names* are recorded; hosts, URLs and owners are not — this repository is public,
|
|
and a forge address is an operational detail (see [`README`](../README.md)).
|
|
|
|
| Repository | Owns |
|
|
|---|---|
|
|
| `hal` | The monorepo — the node runtime, the module catalogue, the delivery machinery, and the bootstrap scripts. Every core module lives here. |
|
|
| `hq` | This repository, under the company organisation — mission, research, design, decisions, issue diagnosis. Company-scoped ([ADR 0028](../02-DECISIONS/0028-hq-is-company-scoped.md)); the mesh is its first product. The source of truth for *why*. Carries no implementation. |
|
|
| *(one per application)* | Every standalone application, site or side-project gets its own repository, with `module.yml` at the root. Registered with the mesh as a build source; built and deployed by the same pipeline as anything in the monorepo. |
|
|
|
|
## What lives where inside the monorepo
|
|
|
|
Named by role, because the layout is itself part of the as-is design — see
|
|
[`03-DESIGN/00-as-is/`](../03-DESIGN/00-as-is/).
|
|
|
|
| Area | Holds |
|
|
|---|---|
|
|
| Module catalogue | One directory per module, each with a manifest. Core modules sit under the mesh's own namespace; everything else at the top level. |
|
|
| Node runtime | The daemon and interactive runtime that every node runs. |
|
|
| Bootstrap scripts | First-node initialisation, joining an existing mesh, and node rescue. |
|
|
| Shared library | The SDK every module builds against. |
|
|
| Pipeline test harness | End-to-end coverage of the delivery pipeline. Currently unbuildable — see [`04-ISSUES/005`](../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md). |
|
|
|
|
## Why applications do not live in the monorepo
|
|
|
|
A standalone application in the monorepo is a convention violation, and reviewers reject it.
|
|
The reasoning is recorded in [`02-DECISIONS/0010`](../02-DECISIONS/0010-applications-live-in-their-own-repository.md):
|
|
the mesh installs, provisions for, and ships an application through exactly the same machinery
|
|
whether or not its source sits beside the mesh's own — so co-location buys nothing and costs
|
|
the monorepo's review cadence.
|
|
|
|
## There is no npm workspace
|
|
|
|
Each module is a standalone package that consumes its dependencies from the private registry,
|
|
not from a sibling directory. The workspace was removed after it caused build-versus-development
|
|
divergence — a workspace member importing another resolved to local unbuilt source in the
|
|
pipeline and to a published version in development. Recorded in
|
|
[`02-DECISIONS/0007`](../02-DECISIONS/0007-no-npm-workspace.md).
|
|
|
|
Consequence, and it is a real one: a cross-package change is two steps — publish, then consume
|
|
— and a repository-wide `npm install` does not exist.
|