ruvnet-constellation 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rUv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# ruvnet-constellation — discover, plan and scaffold useful packages
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Explore a supplied package catalog, build an explicit installation plan and scaffold a reviewable local adapter. The onramp installs nothing automatically and keeps namespace proposals separate from ownership proof.
+
+**Topics:** package discovery · explicit install plans · local scaffolding · modular integrations.
+
+```sh
+npm install ruvnet-constellation@0.1.0
+```
+
+[Package on npm](https://www.npmjs.com/package/ruvnet-constellation) · [Core 0.2.0 entrypoint: `ruv-fann/constellation`](https://github.com/ruvnet/ruv-FANN/tree/main/packages/core#capability-entrypoints) · [Interactive ruv-fann field guide](https://ruvnet.github.io/ruv-FANN/) · [Toolkit API and release guide](https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit#readme)
+
+Choose this standalone package for its declared dependency footprint, or use `ruv-fann/constellation` from the complete `ruv-fann@0.2.0` facade. Package version: **0.1.0**. [Umbrella release and evidence](https://github.com/ruvnet/ruv-FANN/releases/tag/ruv-fann-toolkit-v0.2.0).
+
+A lightweight explicit onramp for a constellation of independently useful packages. ESM, Node 20.9+. Its only runtime dependency is `ruvnet-constellation-contracts@0.1.0`; no ML runtime, model, provider or telemetry collector is pulled in by this package.
+
+```sh
+constellation help
+constellation catalog
+constellation plan weights
+constellation plan local-loop
+constellation scaffold ./new-json-adapter --name @your-scope/json-adapter --integration ruv-fann-wsp
+```
+
+`readCatalog(path?)` reads a bounded local JSON file; by default it uses the packaged `catalog.json`. `planProfile(catalog,id)` validates and owns the catalog, and returns `registrySpecs` for declared published packages, `localCandidates` separately, and `publicInstallAvailable:false` if any profile member is only a candidate. Planning executes no install command and never substitutes candidates for public packages. Catalog status and proposed scopes are metadata, not namespace ownership proofs.
+
+`scaffoldSatellite({directory,name,description?,integrations?})` creates a new explicit directory containing a bounded identity JSON adapter, TypeScript declaration, module manifest, independent malformed-input/snapshot tests, a small local benchmark and publication-preparation guidance. It refuses existing targets, symlinks, traversal and unknown/executable options. Parents must already exist and consist of real directories. Scaffolding requires Linux with `O_DIRECTORY`, `O_NOFOLLOW` and `/proc/self/fd`; it fails closed on unsupported platforms, while catalog and planning remain portable. It opens every parent/child directory through a held directory descriptor, anchors exclusive leaf writes to those descriptors, and verifies directory inode relationships before writes and completion. Child-directory substitution by symlinks cannot redirect output into an existing outside path. It performs no recursive cleanup on failure. These controls do not make a hardened sandbox against arbitrary same-UID code, privileged mount changes, or an attacker moving entire owned directory trees. An I/O or detected namespace-change failure can leave an inspectable partial candidate rather than risk deleting unrelated paths.
+
+The scaffold is a template, not an AI-generated domain solution. Its default checks do not establish WSP correctness, task accuracy or benchmark superiority. Add useful domain mapping and independent cases before publication. Optional integrations are metadata; no irrelevant peer dependencies or nucleus installs are added to inflate dependency volume.
+
+All commands are local unless the user separately runs a package manager or provider. No automatic install, provider request, background telemetry, registry publication, scope claim or credential configuration occurs. `--json` is accepted for catalog/plan/scaffold; data output is JSON by default. CLI usage/input failures exit 2.
+
+<!-- constellation-links:start -->
+
+Explore the [ruv-fann field guide](https://ruvnet.github.io/ruv-FANN/), [constellation onramp](https://www.npmjs.com/package/ruvnet-constellation) and [shared contracts](https://www.npmjs.com/package/ruvnet-constellation-contracts). Optional ecosystem primitives: [ruv-fann-wsp](https://www.npmjs.com/package/ruv-fann-wsp), [AgentDB](https://www.npmjs.com/package/agentdb), [RuVector](https://www.npmjs.com/package/ruvector). Optional orchestration: [MetaHarness](https://www.npmjs.com/package/metaharness) and [Ruflo](https://www.npmjs.com/package/ruflo).
+
+These links describe integrations; package.json defines install-time dependencies. The [versioned catalog](https://github.com/ruvnet/ruv-FANN/blob/main/packages/wsp-toolkit/packages/constellation/catalog.json) declares release profiles and package versions; registry availability and publication provenance require independent verification.
+
+<!-- constellation-links:end -->

package/catalog.json

@@ -0,0 +1,423 @@
+{
+  "schema": "ruvnet.constellation-catalog/1",
+  "repository": "ruvnet/ruv-FANN",
+  "packages": [
+    {
+      "name": "metaharness",
+      "version": "0.4.23",
+      "role": "nucleus",
+      "family": "metaharness",
+      "status": "published",
+      "repository": "ruvnet/metaharness",
+      "description": "Developer harness scaffolding and orchestration",
+      "links": {
+        "npm": "https://www.npmjs.com/package/metaharness",
+        "source": "https://github.com/ruvnet/metaharness"
+      },
+      "proposedScope": "@metaharness"
+    },
+    {
+      "name": "@metaharness/router",
+      "version": "0.4.1",
+      "role": "nucleus",
+      "family": "metaharness",
+      "status": "published",
+      "repository": "ruvnet/metaharness",
+      "description": "Harness routing entry point",
+      "links": {
+        "npm": "https://www.npmjs.com/package/@metaharness/router",
+        "source": "https://github.com/ruvnet/metaharness"
+      }
+    },
+    {
+      "name": "@claude-flow/cli",
+      "version": "3.25.6",
+      "role": "nucleus",
+      "family": "ruflo",
+      "status": "published",
+      "repository": "ruvnet/ruflo",
+      "description": "Validated Ruflo coordination CLI pin; latest version is observed separately",
+      "links": {
+        "npm": "https://www.npmjs.com/package/@claude-flow/cli",
+        "source": "https://github.com/ruvnet/ruflo"
+      }
+    },
+    {
+      "name": "ruflo",
+      "version": "3.75.3",
+      "role": "nucleus",
+      "family": "ruflo",
+      "status": "published",
+      "repository": "ruvnet/ruflo",
+      "description": "Public Ruflo convenience entry point",
+      "links": {
+        "npm": "https://www.npmjs.com/package/ruflo",
+        "source": "https://github.com/ruvnet/ruflo"
+      }
+    },
+    {
+      "name": "agentdb",
+      "version": "3.10.0",
+      "role": "primitive",
+      "family": "agentdb",
+      "status": "published",
+      "repository": "ruvnet/agentdb",
+      "description": "Persistent model programs, proposals and revision histories",
+      "links": {
+        "npm": "https://www.npmjs.com/package/agentdb",
+        "source": "https://github.com/ruvnet/agentdb"
+      },
+      "contracts": [
+        "ruv-fann.dense-layers/1",
+        "ruv-fann.weight-patch/1",
+        "ruv-fann.weight-evaluation/1"
+      ],
+      "proposedScope": "@agentdb"
+    },
+    {
+      "name": "ruvector",
+      "version": "0.3.24",
+      "role": "primitive",
+      "family": "ruvector",
+      "status": "published",
+      "repository": "ruvnet/RuVector",
+      "description": "Independent vector retrieval primitive",
+      "links": {
+        "npm": "https://www.npmjs.com/package/ruvector",
+        "source": "https://github.com/ruvnet/RuVector"
+      },
+      "proposedScope": "@ruvector"
+    },
+    {
+      "name": "ruv-fann",
+      "version": "0.2.0",
+      "role": "primitive",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "description": "Dense neural-network WebAssembly facade with optional weight-space toolkit entry points",
+      "links": {
+        "npm": "https://www.npmjs.com/package/ruv-fann",
+        "source": "https://github.com/ruvnet/ruv-FANN"
+      },
+      "contracts": [
+        "ruv-fann.dense-layers/1"
+      ]
+    },
+    {
+      "name": "ruv-fann-wasm",
+      "version": "0.1.2",
+      "role": "primitive",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "description": "Precompiled scalar and SIMD WebAssembly runtime",
+      "links": {
+        "npm": "https://www.npmjs.com/package/ruv-fann-wasm",
+        "source": "https://github.com/ruvnet/ruv-FANN"
+      },
+      "contracts": [
+        "ruv-fann.dense-layers/1"
+      ]
+    },
+    {
+      "name": "ruv-fann-wsp",
+      "version": "0.2.0",
+      "role": "primitive",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "description": "Bounded parameter patches, diagnostics and regression gates",
+      "links": {
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp",
+        "source": "https://github.com/ruvnet/ruv-FANN"
+      },
+      "contracts": [
+        "ruv-fann.dense-layers/1",
+        "ruv-fann.weight-patch/1",
+        "ruv-fann.weight-evaluation/1"
+      ]
+    },
+    {
+      "name": "agentic-flow",
+      "version": "3.5.4",
+      "role": "satellite",
+      "family": "agentic-flow",
+      "status": "published",
+      "repository": "ruvnet/agentic-flow",
+      "description": "Optional agent workflow integration",
+      "links": {
+        "npm": "https://www.npmjs.com/package/agentic-flow",
+        "source": "https://github.com/ruvnet/agentic-flow"
+      }
+    },
+    {
+      "name": "@ruvector/attention",
+      "version": "2.3.1",
+      "role": "satellite",
+      "family": "ruvector",
+      "status": "published",
+      "repository": "ruvnet/RuVector",
+      "description": "Specialized attention integration",
+      "links": {
+        "npm": "https://www.npmjs.com/package/@ruvector/attention",
+        "source": "https://github.com/ruvnet/RuVector"
+      }
+    },
+    {
+      "name": "@ruvector/ruvllm",
+      "version": "4.2.2",
+      "role": "satellite",
+      "family": "ruvector",
+      "status": "published",
+      "repository": "ruvnet/RuVector",
+      "description": "Specialized language-model integration",
+      "links": {
+        "npm": "https://www.npmjs.com/package/@ruvector/ruvllm",
+        "source": "https://github.com/ruvnet/RuVector"
+      }
+    },
+    {
+      "name": "ruv-fann-wsp-lifecycle",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/lifecycle",
+      "description": "Evaluate bounded neural weight patches across named regression suites and independent candidate branches.",
+      "contracts": [
+        "ruv-fann.dense-layers/1",
+        "ruv-fann.weight-patch/1",
+        "ruv-fann.weight-evaluation/1"
+      ],
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/lifecycle",
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp-lifecycle"
+      }
+    },
+    {
+      "name": "ruv-fann-wsp-search",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/search",
+      "description": "Search explicit neural weight values without gradients; propose bounded Boolean-table and experimental Hebbian edits.",
+      "contracts": [
+        "ruv-fann.dense-layers/1",
+        "ruv-fann.weight-patch/1"
+      ],
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/search",
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp-search"
+      }
+    },
+    {
+      "name": "ruv-fann-wsp-huggingface",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/huggingface",
+      "description": "Load public Hugging Face dense JSON checkpoints with pinned revisions, SHA-256 integrity and bounded WSP validation.",
+      "contracts": [
+        "ruv-fann.dense-layers/1"
+      ],
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/huggingface",
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp-huggingface"
+      }
+    },
+    {
+      "name": "ruv-fann-wsp-cloudflare",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/cloudflare",
+      "description": "Run bounded neural weight patches and regression evaluations in Cloudflare Workers with static WebAssembly modules.",
+      "contracts": [
+        "ruv-fann.dense-layers/1",
+        "ruv-fann.weight-patch/1",
+        "ruv-fann.weight-evaluation/1"
+      ],
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/cloudflare",
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp-cloudflare"
+      }
+    },
+    {
+      "name": "ruv-fann-wsp-ruos",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/ruos",
+      "description": "Validate real WebAssembly canary output and bind trusted ruOS executor completion evidence to explicit requests.",
+      "contracts": [
+        "ruv-fann.dense-layers/1",
+        "ruv-fann.weight-patch/1"
+      ],
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/ruos",
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp-ruos"
+      }
+    },
+    {
+      "name": "ruv-fann-wsp-invariants",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/invariants",
+      "description": "Check finite-domain neural output bounds and expected values using real scalar or SIMD WebAssembly inference.",
+      "contracts": [
+        "ruv-fann.dense-layers/1"
+      ],
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/invariants",
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp-invariants"
+      }
+    },
+    {
+      "name": "ruv-fann-wsp-swarm",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/swarm",
+      "description": "Run bounded neural patch and search proposals in real Node.js worker threads with isolated WebAssembly instances.",
+      "contracts": [
+        "ruv-fann.dense-layers/1",
+        "ruv-fann.weight-patch/1"
+      ],
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/swarm",
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp-swarm"
+      }
+    },
+    {
+      "name": "ruv-fann-wsp-registry",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/registry",
+      "description": "Adapt AgentDB weight programs with serialized operations, revision checks and caller-supplied persistence acknowledgment.",
+      "contracts": [
+        "ruv-fann.dense-layers/1",
+        "ruv-fann.weight-patch/1",
+        "ruv-fann.weight-evaluation/1"
+      ],
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/registry",
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp-registry"
+      }
+    },
+    {
+      "name": "ruv-fann-wsp-loop",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "ruv-fann",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/loop",
+      "description": "Coordinate bounded local weight evolution with worker proposals, independent regression gates and revision-based promotion.",
+      "contracts": [
+        "ruv-fann.dense-layers/1",
+        "ruv-fann.weight-patch/1",
+        "ruv-fann.weight-evaluation/1"
+      ],
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/loop",
+        "npm": "https://www.npmjs.com/package/ruv-fann-wsp-loop"
+      }
+    },
+    {
+      "name": "ruvnet-constellation-contracts",
+      "version": "0.1.0",
+      "role": "primitive",
+      "family": "constellation",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/contracts",
+      "description": "Validate bounded JSON catalogs and module manifests for independently installable RuvNet packages.",
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/contracts",
+        "npm": "https://www.npmjs.com/package/ruvnet-constellation-contracts"
+      }
+    },
+    {
+      "name": "ruvnet-constellation",
+      "version": "0.1.0",
+      "role": "nucleus",
+      "family": "constellation",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/constellation",
+      "description": "Discover versioned RuvNet packages, plan explicit installs and scaffold local integration adapters with a lightweight CLI.",
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/constellation",
+        "npm": "https://www.npmjs.com/package/ruvnet-constellation"
+      }
+    },
+    {
+      "name": "ruvnet-constellation-telemetry",
+      "version": "0.1.0",
+      "role": "satellite",
+      "family": "constellation",
+      "status": "published",
+      "repository": "ruvnet/ruv-FANN",
+      "directory": "packages/wsp-toolkit/packages/telemetry",
+      "description": "Analyze public npm and GitHub observations, consented project samples and standalone package dashboards.",
+      "links": {
+        "source": "https://github.com/ruvnet/ruv-FANN/tree/main/packages/wsp-toolkit/packages/telemetry",
+        "npm": "https://www.npmjs.com/package/ruvnet-constellation-telemetry"
+      }
+    }
+  ],
+  "profiles": [
+    {
+      "id": "weights",
+      "description": "Use the independently installable published weight-editing primitive",
+      "packages": [
+        "ruv-fann-wsp"
+      ]
+    },
+    {
+      "id": "memory",
+      "description": "Combine durable model programs with bounded parameter edits",
+      "packages": [
+        "agentdb",
+        "ruv-fann-wsp"
+      ]
+    },
+    {
+      "id": "orchestration",
+      "description": "Optional public harness and validated CLI entry points",
+      "packages": [
+        "metaharness",
+        "@metaharness/router",
+        "@claude-flow/cli"
+      ]
+    },
+    {
+      "id": "local-loop",
+      "description": "Plan explicit version-pinned installs for the local weight-evolution loop and its supporting packages",
+      "packages": [
+        "ruv-fann-wsp-loop",
+        "ruv-fann-wsp-registry",
+        "ruv-fann-wsp-swarm",
+        "ruv-fann-wsp-invariants"
+      ]
+    }
+  ]
+}

package/constellation.json

@@ -0,0 +1,12 @@
+{
+  "schema": "ruvnet.constellation-module/1",
+  "name": "ruvnet-constellation",
+  "version": "0.1.0",
+  "role": "nucleus",
+  "contracts": [
+    "ruvnet.constellation-module/1"
+  ],
+  "integrations": [
+    "ruvnet-constellation-contracts"
+  ]
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "ruvnet-constellation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Discover versioned RuvNet packages, plan explicit installs and scaffold local integration adapters with a lightweight CLI.",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./catalog.json": "./catalog.json"
+  },
+  "bin": {
+    "constellation": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "catalog.json",
+    "README.md",
+    "LICENSE",
+    "constellation.json"
+  ],
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "dependencies": {
+    "ruvnet-constellation-contracts": "0.1.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ruvnet/ruv-FANN.git",
+    "directory": "packages/wsp-toolkit/packages/constellation"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ruvnet",
+    "constellation",
+    "package-discovery",
+    "cli",
+    "integration",
+    "scaffolding",
+    "package-catalog"
+  ],
+  "homepage": "https://ruvnet.github.io/ruv-FANN/",
+  "bugs": {
+    "url": "https://github.com/ruvnet/ruv-FANN/issues"
+  }
+}

package/src/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import {readCatalog,planProfile,scaffoldSatellite} from './index.js';
+const help=`constellation — explicit local discovery, planning and satellite scaffolding
+
+Usage:
+  constellation help
+  constellation catalog [--json]
+  constellation plan <profile> [--json]
+  constellation scaffold <new-directory> --name <npm-name> [--description <text>] [--integration <npm-name> ...] [--json]
+
+Plans describe verified published pins and local candidates separately. No command
+installs dependencies, starts an agent, collects telemetry or publishes a package.
+Scaffolding requires Linux with /proc/self/fd, creates a new directory only,
+and refuses existing targets and symlinks. Catalog and planning remain portable.
+
+Nucleus: https://www.npmjs.com/package/metaharness
+         https://www.npmjs.com/package/@claude-flow/cli
+Memory:  https://www.npmjs.com/package/agentdb
+Vectors: https://www.npmjs.com/package/ruvector
+Weights: https://www.npmjs.com/package/ruv-fann-wsp
+`;
+try {
+  const args=process.argv.slice(2),command=args.shift()??'help';
+  if(command==='help'||command==='--help'||command==='-h'){
+    if(args.length)throw new Error('help accepts no arguments');
+    process.stdout.write(help);
+  }else if(command==='catalog'){
+    if(args.length&&!(args.length===1&&args[0]==='--json'))throw new Error('catalog accepts only --json');
+    process.stdout.write(JSON.stringify(await readCatalog(),null,2)+'\n');
+  }else if(command==='plan'){
+    const profile=args.shift();if(!profile||(args.length&&!(args.length===1&&args[0]==='--json')))throw new Error('usage: constellation plan <profile> [--json]');
+    process.stdout.write(JSON.stringify(planProfile(await readCatalog(),profile),null,2)+'\n');
+  }else if(command==='scaffold'){
+    const directory=args.shift();if(!directory||directory.startsWith('--'))throw new Error('scaffold requires an explicit new directory');
+    const config={directory},integrations=[];const seen=new Set();
+    while(args.length){
+      const flag=args.shift();
+      if(flag==='--json'){if(seen.has(flag))throw new Error('duplicate --json');seen.add(flag);continue;}
+      if(!['--name','--description','--integration'].includes(flag))throw new Error('unknown scaffold option');
+      const value=args.shift();if(!value||value.startsWith('--'))throw new Error(`missing value for ${flag}`);
+      if(flag==='--integration')integrations.push(value);
+      else {if(seen.has(flag))throw new Error(`duplicate ${flag}`);seen.add(flag);config[flag.slice(2)]=value;}
+    }
+    if(integrations.length)config.integrations=integrations;
+    process.stdout.write(JSON.stringify(await scaffoldSatellite(config),null,2)+'\n');
+  }else throw new Error('unknown command; use constellation help');
+}catch(error){process.stderr.write(`constellation: ${error.message}\n`);process.exitCode=2;}

package/src/index.d.ts

@@ -0,0 +1,12 @@
+import type {ConstellationCatalog,CatalogPackage} from 'ruvnet-constellation-contracts';
+export interface ConstellationPlan {
+  schema:'ruvnet.constellation-plan/1'; profile:string; description:string; packages:CatalogPackage[];
+  registrySpecs:string[]; localCandidates:{name:string;directory?:string;repository:string}[];
+  publicInstallAvailable:boolean; automaticInstall:false; telemetry:'disabled';
+}
+export interface SatelliteScaffoldOptions {directory:string;name:string;description?:string;integrations?:string[]}
+export interface SatelliteScaffold {schema:'ruvnet.constellation-scaffold/1';directory:string;name:string;status:'candidate';files:string[];automaticInstall:false;telemetry:'disabled';published:false}
+export function readCatalog(path?:string|URL):Promise<ConstellationCatalog>;
+export function planProfile(catalog:ConstellationCatalog,id:string):ConstellationPlan;
+/** Scaffolding requires Linux directory descriptors and /proc/self/fd; fails closed elsewhere. */
+export function scaffoldSatellite(options:SatelliteScaffoldOptions):Promise<SatelliteScaffold>;

package/src/index.js

@@ -0,0 +1,203 @@
+import { open, mkdir, lstat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { resolve, dirname, basename, parse, relative, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONTRACTS, CONTRACT_LIMITS, validateCatalog, validateModuleManifest } from 'ruvnet-constellation-contracts';
+
+/** Read only an explicitly selected local catalog; no registry or network access. */
+export async function readCatalog(path = new URL('../catalog.json', import.meta.url)) {
+  if (path instanceof URL) path = fileURLToPath(path);
+  if (typeof path !== 'string' || !path.length || path.length > 4096 || /[\x00-\x1f\x7f]/.test(path)) throw new TypeError('catalog path must be bounded local text');
+  const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    if (!(await handle.stat()).isFile()) throw new TypeError('catalog must be a regular file');
+    const bytes = Buffer.alloc(CONTRACT_LIMITS.maxBytes + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const { bytesRead } = await handle.read(bytes, length, bytes.length - length, null);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    if (length > CONTRACT_LIMITS.maxBytes) throw new RangeError('catalog exceeds byte limit');
+    return validateCatalog(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length))));
+  } finally { await handle.close(); }
+}
+
+/** Planning is data only. Candidate sources never become purported public install specs. */
+export function planProfile(input, id) {
+  const catalog = validateCatalog(input);
+  if (typeof id !== 'string' || !/^[a-z][a-z0-9-]{0,47}$/.test(id)) throw new TypeError('profile must be a bounded identifier');
+  const profile = catalog.profiles.find(profile => profile.id === id);
+  if (!profile) throw new Error(`unknown constellation profile: ${id}`);
+  const entries = new Map(catalog.packages.map(entry => [entry.name, entry]));
+  const packages = profile.packages.map(name => entries.get(name));
+  return { schema: 'ruvnet.constellation-plan/1', profile: id, description: profile.description,
+    packages, registrySpecs: packages.filter(entry => entry.status === 'published').map(entry => `${entry.name}@${entry.version}`),
+    localCandidates: packages.filter(entry => entry.status === 'candidate').map(entry => ({name:entry.name, directory:entry.directory, repository:entry.repository})),
+    publicInstallAvailable: packages.every(entry => entry.status === 'published'), automaticInstall: false, telemetry: 'disabled' };
+}
+function argumentsRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError('scaffold options must be a plain record');
+  const result = {};
+  for (const key of Reflect.ownKeys(value)) {
+    const property = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== 'string' || !['directory','name','description','integrations'].includes(key) || !property || !Object.hasOwn(property,'value'))
+      throw new TypeError('unknown scaffold option or accessor');
+    result[key] = property.value;
+  }
+  if (!Object.hasOwn(result, 'directory') || !Object.hasOwn(result, 'name')) throw new TypeError('scaffold requires directory and name');
+  return result;
+}
+function markdown(value) { return value.replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;').replace(/[\\`*_{}\[\]()#+.!|]/g, '\\$&'); }
+function directoryAlias(handle) { return `/proc/self/fd/${handle.fd}`; }
+async function closeDirectories(resources) {
+  const results = await Promise.allSettled([...resources].reverse().map(resource => resource.handle.close()));
+  const failed = results.find(result => result.status === 'rejected');
+  if (failed) throw failed.reason;
+}
+async function verifyDirectories(resources) {
+  for (const resource of resources) {
+    const held = await resource.handle.stat();
+    const entry = await lstat(resource.parent ? `${directoryAlias(resource.parent)}/${resource.name}` : resource.root);
+    if (!held.isDirectory() || entry.isSymbolicLink() || !entry.isDirectory() || entry.dev !== held.dev || entry.ino !== held.ino)
+      throw new Error('scaffold directory relationship changed during creation');
+  }
+}
+async function openParentDirectories(path) {
+  if (process.platform !== 'linux' || typeof constants.O_DIRECTORY !== 'number' || typeof constants.O_NOFOLLOW !== 'number')
+    throw new Error('scaffolding requires Linux directory descriptors and /proc/self/fd; catalog and planning remain portable');
+  const root = parse(path).root, parts = relative(root, path).split(sep).filter(Boolean), resources = [];
+  if (parts.length > 64) throw new RangeError('scaffold parent path exceeds directory depth limit');
+  const flags = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+  try {
+    // Each next component resolves through a held descriptor. No unverified ancestor
+    // path is reused, and O_NOFOLLOW applies to the newly opened component.
+    let current = await open(root, flags);
+    resources.push({ handle: current, root });
+    // Verify the kernel-provided descriptor namespace before creating any output.
+    const proc = await lstat('/proc/self/fd');
+    if (!proc.isDirectory()) throw new Error('Linux /proc/self/fd directory is unavailable');
+    for (const name of parts) {
+      const parent = current;
+      try { current = await open(`${directoryAlias(parent)}/${name}`, flags); }
+      catch (error) { throw new TypeError('scaffold parent path must consist of existing real directories', {cause:error}); }
+      resources.push({ handle: current, parent, name });
+    }
+    await verifyDirectories(resources);
+    return resources;
+  } catch (error) { await closeDirectories(resources); throw error; }
+}
+async function createDirectory(resources, parent, name) {
+  await verifyDirectories(resources);
+  const path = `${directoryAlias(parent)}/${name}`;
+  // mkdir refuses an existing target, including dangling symlinks. Opening the
+  // result refuses substitution by a symlink before its descriptor is acquired.
+  await mkdir(path, {mode:0o700});
+  const handle = await open(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  resources.push({handle,parent,name});
+  await verifyDirectories(resources);
+  return handle;
+}
+async function writeNew(directoryHandle, name, content) {
+  // Only fixed leaf names reach this function. O_EXCL prevents existing leaf
+  // replacement; the held parent descriptor prevents intermediate symlink races.
+  const path = `${directoryAlias(directoryHandle)}/${name}`;
+  const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try { await handle.writeFile(content); } finally { await handle.close(); }
+}
+const adapterSource = `// Bounded JSON adapter template. Define and independently test domain mapping before release.
+export function adaptRecord(input) {
+  let nodes = 0, text = 0;
+  const ancestors = new Set();
+  function copy(value, depth) {
+    if (++nodes > 8192 || depth > 8) throw new RangeError('adapter structure exceeds limits');
+    if (value === null || typeof value === 'boolean') return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return value === 0 ? 0 : value;
+    if (typeof value === 'string') { text += value.length; if (text > 65536) throw new RangeError('adapter text exceeds limit'); return value; }
+    if (!value || typeof value !== 'object' || ancestors.has(value)) throw new TypeError('adapter accepts finite acyclic JSON data only');
+    const array = Array.isArray(value);
+    if (!(array ? Object.getPrototypeOf(value) === Array.prototype : [Object.prototype, null].includes(Object.getPrototypeOf(value)))) throw new TypeError('adapter requires plain data');
+    if (array && value.length > 8192) throw new RangeError('adapter array exceeds limit');
+    const result = array ? [] : Object.create(null); ancestors.add(value);
+    for (const key of Reflect.ownKeys(value)) {
+      if (array && key === 'length') continue;
+      if (typeof key !== 'string' || ['__proto__','constructor','prototype'].includes(key) || (array && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length))) throw new TypeError('adapter contains unsafe properties');
+      text += key.length; if (text > 65536) throw new RangeError('adapter text exceeds limit');
+      const property = Object.getOwnPropertyDescriptor(value, key);
+      if (!property || !Object.hasOwn(property, 'value')) throw new TypeError('adapter accessors are forbidden');
+      result[key] = copy(property.value, depth + 1);
+    }
+    ancestors.delete(value);
+    if (array && (result.length !== value.length || Object.keys(result).length !== value.length)) throw new TypeError('adapter arrays must be dense');
+    return result;
+  }
+  const result = copy(input, 0);
+  if (new TextEncoder().encode(JSON.stringify(result)).length > 65536) throw new RangeError('adapter bytes exceed limit');
+  return result;
+}
+`;
+const templateTests = `import test from 'node:test';
+import assert from 'node:assert/strict';
+import { adaptRecord } from '../src/index.js';
+test('copies JSON without retaining caller objects', () => {
+  const input = {format:'example', values:[1,2,null]}; const output = adaptRecord(input);
+  input.values[0] = 10; assert.equal(output.values[0],1); assert.equal(output.format,'example');
+});
+test('rejects executable, nonfinite and unsafe inputs without invoking getters', () => {
+  let calls=0; const input={get value(){calls++; return 1;}};
+  assert.throws(()=>adaptRecord(input));assert.equal(calls,0);
+  for(const value of [Infinity,()=>{},new Array(2),JSON.parse('{"__proto__":{"polluted":true}}')]) assert.throws(()=>adaptRecord(value));
+  assert.equal({}.polluted,undefined);
+});
+test('bounds copied data and refuses cycles', () => {
+  const cycle={};cycle.self=cycle;
+  assert.throws(()=>adaptRecord(cycle));assert.throws(()=>adaptRecord('x'.repeat(65537)));
+});
+`;
+const benchmarkSource = `import {performance} from 'node:perf_hooks';
+import assert from 'node:assert/strict';
+import {adaptRecord} from './src/index.js';
+const input={format:'example',values:[1,2,3]},iterations=1000,start=performance.now();
+for(let index=0;index<iterations;index++)assert.equal(adaptRecord(input).values[2],3);
+console.log(JSON.stringify({schema:'ruvnet.satellite-benchmark/1',iterations,elapsedMs:performance.now()-start,note:'Local JSON-copy observation, not a domain accuracy or WASM benchmark.'}));
+`;
+
+/** Create a reviewable local candidate. Never overwrites a target or installs dependencies. */
+export async function scaffoldSatellite(options) {
+  // Capture all configuration before asynchronous filesystem operations.
+  const config = argumentsRecord(options), directory = config.directory;
+  if (typeof directory !== 'string' || !directory.length || directory.length > 4096 || /[\x00-\x1f\x7f]/.test(directory) ||
+      directory.split(/[\\/]/).some(part => part === '..') || (sep === '/' && directory.includes('\\')))
+    throw new TypeError('directory must be bounded text without traversal, control characters or ambiguous separators');
+  const module = validateModuleManifest({schema:CONTRACTS.module,name:config.name,version:'0.1.0',role:'satellite',contracts:[CONTRACTS.module],integrations:config.integrations === undefined ? [] : config.integrations});
+  const description = config.description === undefined ? 'Bounded JSON adapter candidate; replace mapping with independently tested domain logic.' : config.description;
+  if (typeof description !== 'string' || !description.length || description.length > 2000 || /[\x00-\x1f\x7f]/.test(description)) throw new TypeError('description must be bounded plain text');
+  const target = resolve(directory), parent = dirname(target);
+  if (target === parent) throw new TypeError('scaffold target cannot be a filesystem root');
+  const resources = await openParentDirectories(parent);
+  try {
+    const parentHandle = resources.at(-1).handle;
+    const rootHandle = await createDirectory(resources, parentHandle, basename(target));
+    const sourceHandle = await createDirectory(resources, rootHandle, 'src');
+    const testHandle = await createDirectory(resources, rootHandle, 'test');
+  const manifest = {name:module.name,version:module.version,description,type:'module',main:'./src/index.js',types:'./src/index.d.ts',
+    exports:{'.':{types:'./src/index.d.ts',import:'./src/index.js'}},files:['src','constellation.json','README.md','LICENSE'],
+    engines:{node:'>=20.9.0'},scripts:{test:'node --test test/*.test.mjs',check:'npm test',benchmark:'node benchmark.mjs','pack:check':'npm pack --dry-run --ignore-scripts'},license:'MIT',publishConfig:{access:'public'}};
+  const integrationLinks = module.integrations.length ? module.integrations.map(name => `- [${name}](https://www.npmjs.com/package/${name}) — optional integration metadata; no dependency is installed.`).join('\n') : 'No integration is selected. Add only integrations the module actually uses.';
+  const readme = `# ${markdown(module.name)}\n\n${markdown(description)}\n\nThis is a local candidate with a bounded identity JSON adapter template. It has not been published or proven useful for a domain. Replace the mapping and add independent domain cases before release.\n\n\`adaptRecord(value)\` owns finite acyclic JSON, rejects accessors/prototype keys, and bounds depth, elements and bytes. It executes no callbacks and performs no network requests. These checks are not a WSP or domain-accuracy benchmark.\n\nRun \`npm test\`, \`npm run benchmark\` and \`npm run pack:check\`. No install or provider is required for the template.\n\n## Optional constellation integrations\n\n${integrationLinks}\n\nDiscover [MetaHarness](https://www.npmjs.com/package/metaharness), [Ruflo](https://www.npmjs.com/package/@claude-flow/cli), [AgentDB](https://www.npmjs.com/package/agentdb), [RuVector](https://www.npmjs.com/package/ruvector) and [WSP](https://www.npmjs.com/package/ruv-fann-wsp) independently. The template does not force any nucleus dependency.\n\n## Publication preparation\n\nReview the generated files, package name/namespace ownership, license and quality evidence. Configure this package's npm trusted publisher for the exact owner, repository, workflow and optional environment; use a protected exact-source/archive release with supported Node/npm and OIDC provenance. The scaffold neither configures a publisher nor publishes. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).\n`;
+  const files = new Map([
+    ['package.json',JSON.stringify(manifest,null,2)+'\n'],['constellation.json',JSON.stringify(module,null,2)+'\n'],
+    ['README.md',readme],['src/index.js',adapterSource],['src/index.d.ts','/** Owns bounded finite JSON data. Replace this template with domain-specific types. */\nexport function adaptRecord(input: unknown): unknown;\n'],
+    ['test/adapter.test.mjs',templateTests],['benchmark.mjs',benchmarkSource],
+    ['LICENSE',`MIT License\n\nCopyright (c) ${new Date().getUTCFullYear()} contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the "Software"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n`]
+  ]);
+  for (const [path,content] of files) {
+    await verifyDirectories(resources);
+    const parts = path.split('/');
+    const directoryHandle = parts.length === 1 ? rootHandle : parts[0] === 'src' ? sourceHandle : testHandle;
+    await writeNew(directoryHandle, parts.at(-1), content);
+  }
+  await verifyDirectories(resources);
+  return {schema:'ruvnet.constellation-scaffold/1',directory:target,name:module.name,status:'candidate',files:[...files.keys()],automaticInstall:false,telemetry:'disabled',published:false};
+  } finally { await closeDirectories(resources); }
+}