@openwop/cli 1.2.3 → 1.3.0

package/dist/cli.js

@@ -578,7 +578,7 @@ function errText(err) {
 // package.json
 var package_default = {
   name: "@openwop/cli",
-  version: "1.2.3",
+  version: "1.3.0",
   description: "OpenWOP CLI for operating the workflow-engine demo app and OpenWOP-compatible hosts.",
   license: "Apache-2.0",
   type: "module",
@@ -1153,6 +1153,17 @@ var V2_PATH_TEMPLATES = [
   "/workflows/{workflowId}"
 ];
 var V2_MANIFEST_OMITTED = ["/.well-known/openwop", "/openapi.json"];
+var V2_RENAMED = { "/v1/openapi.json": "/openapi.json" };
+var V2_SEAMS_PROFILE = "openwop-conformance-seams-v2";
+var V2_SEAM_PREFIXES = {
+  "/v1/host/workspace/files": "/conformance/seams/workspace/files"
+};
+function v2SeamTwin(path) {
+  for (const [v1, v2] of Object.entries(V2_SEAM_PREFIXES)) {
+    if (path === v1 || path.startsWith(`${v1}/`) || path.startsWith(`${v1}?`)) return `${v2}${path.slice(v1.length)}`;
+  }
+  return null;
+}
 var V2_MATCHERS = V2_PATH_TEMPLATES.map(
   (t) => new RegExp(`^${t.replace(/[.:]/g, "\\$&").replace(/\{[A-Za-z]+\}/g, "[^/]+")}$`)
 );
@@ -1161,6 +1172,7 @@ function v2Twin(path) {
   const bare = q === -1 ? path : path.slice(0, q);
   const query = q === -1 ? "" : path.slice(q);
   if (!bare.startsWith("/v1/")) return null;
+  if (V2_RENAMED[bare] !== void 0) return `${V2_RENAMED[bare]}${query}`;
   const unversioned = bare.slice("/v1".length);
   return V2_MATCHERS.some((m) => m.test(unversioned)) ? `${unversioned}${query}` : null;
 }
@@ -1204,6 +1216,7 @@ async function negotiateMajor(ctx) {
   }
   let major = 1;
   let roots = {};
+  let seams = false;
   try {
     const url = new URL(".well-known/openwop", ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
     const res = await ctx.fetchImpl(url, { method: "GET", headers: { accept: "application/json", "openwop-version": "2" } });
@@ -1212,7 +1225,10 @@ async function negotiateMajor(ctx) {
       ctx.discovery = { doc, servedVersion: res.headers?.get?.("openwop-version") ?? void 0 };
       ctx.discoveredStreamBase = streamBaseFrom(doc?.extensions, ctx.baseUrl);
       major = selectMajor(doc?.protocolVersions);
-      if (major === 2) roots = hostRootsFrom(doc?.extensions);
+      if (major === 2) {
+        roots = hostRootsFrom(doc?.extensions);
+        seams = doc?.conformance?.seamsProfile === V2_SEAMS_PROFILE;
+      }
     } else if (res.status === 406) {
       major = selectMajor(doc?.details?.protocolVersions);
     }
@@ -1220,6 +1236,7 @@ async function negotiateMajor(ctx) {
   }
   ctx.protocolMajor = major;
   ctx.hostRoots = roots;
+  ctx.seamsV2 = seams;
   return major;
 }
 async function resolveRequest(ctx, path, headers) {
@@ -1227,6 +1244,8 @@ async function resolveRequest(ctx, path, headers) {
   if (major !== 2) return { path, headers };
   const twin = v2Twin(path);
   if (twin !== null) return { path: projectRunIdsInPath(twin), headers: { ...headers, "openwop-version": "2.0" } };
+  const seam = ctx.seamsV2 ? v2SeamTwin(path) : null;
+  if (seam !== null) return { path: seam, headers: { ...headers, "openwop-version": "2.0" } };
   const rooted = hostRootFor(path, ctx.hostRoots ?? {});
   if (rooted !== null) return { path: rooted, headers };
   return { path, headers };
@@ -4389,6 +4408,10 @@ registry (\`openwop packs\` operates packs.openwop.dev):
   get     GET /v1/packs/{packName}   \u2014 one pack's node types (reverse-DNS name)
   export  GET /v1/packs/export       \u2014 the installed agent manifests (RFC 0003
           round-trip), re-installable elsewhere; --out writes them to a file.
+These four are v1 operations: protocol v2 names no installed-packs operation
+(spec/v2/path-manifest.json, api/v2/openapi.yaml), so they are sent as the v1
+paths whichever major the host speaks. To read the published catalog, use
+\`openwop packs\`, which resolves the registry's v2 tree.
 
 \`tools\` reads the portable tool catalog (RFC 0078 \xA7B) \u2014 GET /v1/tools, or
 GET /v1/tools/<toolId> for one descriptor. This is the tools an agent/workflow
@@ -11851,8 +11874,12 @@ ${routesHelp("workspace", WORKSPACE_ROUTES)}
 
 Agent workspace (RFC 0059 \xA7C). A tenant-scoped file area an agent reads and
 writes during a run, with optimistic concurrency via ETag / If-Match (WCT-1
-cross-owner isolation is enforced host-side). Drives the real CRUD surface
-GET/PUT/DELETE /v1/host/workspace/files. (The /v1/host/openwop-app/workspace/op
+cross-owner isolation is enforced host-side). Drives GET/PUT/DELETE
+/v1/host/workspace/files. v2 names no canonical workspace operation: its only
+v2 home is the conformance seams profile, so on a host that speaks major 2 AND
+advertises conformance.seamsProfile "openwop-conformance-seams-v2" the same
+calls go to /conformance/seams/workspace/files (OpenWOP-Version: 2.0);
+otherwise the v1 path is used. (The /v1/host/openwop-app/workspace/op
 cross-owner seam is a conformance-only test seam \u2014 reachable here as
 \`workspace op\`, and only on a host started with OPENWOP_TEST_SEAM_ENABLED=true.)
 
@@ -14972,30 +14999,49 @@ import { existsSync as existsSync6, readFileSync as readFileSync15, writeFileSyn
 import { join as join6, resolve as resolvePath8 } from "node:path";
 import { homedir as homedir3 } from "node:os";
 var PACKS_HELP = `Usage:
-  openwop packs search [query] [--registry-url url] [--limit n] [--json]
-  openwop packs info <name> [--version v] [--registry-url url] [--json]
-  openwop packs install <name>[@version] [--version v] [--dir path] [--no-verify] [--registry-url url] [--json]
-  openwop packs publish <dir> [--key ed25519.pem] [--key-id id] [--out dir] [--json]
-  openwop packs yank <name>[@version] [--version v] [--undo] [--json]
+  openwop packs search [query] [--registry-url url] [--tree v1|v2] [--limit n] [--json]
+  openwop packs info <name> [--version v] [--registry-url url] [--tree v1|v2] [--json]
+  openwop packs install <name>[@version|@range] [--version v] [--dir path] [--no-verify] [--registry-url url] [--tree v1|v2] [--json]
+  openwop packs publish <dir> [--key ed25519.pem] [--key-id id] [--out dir] [--tree v1|v2] [--json]
+  openwop packs yank <name>[@version] [--version v] [--undo] [--tree v1|v2] [--json]
 
 Operates the signed node-pack registry (default: https://packs.openwop.dev,
 override with --registry-url or OPENWOP_REGISTRY_URL). The registry is a
 separate surface from the host --base-url.
 
-  search    Reads /v1/index.json and filters the catalog client-side.
-  info      Reads /v1/packs/{name}/index.json (+ the version manifest with --version).
-  install   Downloads /v1/packs/{name}/-/{version}.tgz, checks sha256 integrity
-            against the manifest, and verifies the detached Ed25519 .sig against
-            the publisher key at /keys/{keyId}.pub (skip with --no-verify). Places
-            the tarball + manifest under ~/.openwop/packs/{name}/{version}/
+Every registry path is resolved through the registry's
+/.well-known/openwop-registry.json \`endpoints\` map (spec/v2/core/packs.md
+\xA7"The registry tree"), preferring the v2 tree (\`endpoints.v2\`). The v1 tree
+is used only when the registry names no v2 tree (or publishes no discovery
+document), or when you pass --tree v1.
+
+  search    Reads the registry index (endpoints.registryIndex, /v2/index.json on
+            packs.openwop.dev) and filters the catalog client-side.
+  info      Reads the pack index (endpoints.packMetadata) + the version manifest
+            with --version.
+  install   Resolves the version, downloads the tarball, checks its sha256
+            integrity against the manifest, and verifies the signature (skip
+            with --no-verify). v2: the detached Ed25519 .sig over the in-tarball
+            pack.json (RFC 8785 canonical JSON), under the registry key named by
+            signing.keyId, whose permittedNamespaces must cover the pack name.
+            Places the tarball + manifest under ~/.openwop/packs/{name}/{version}/
             (override with --dir).
+            Version: none = the pack's latest unyanked version; a range (^1.2,
+            ~1.2.0, 1.x, >=1.0.0 <2.0.0) = the highest matching unyanked version;
+            an exact version is a pin and MAY install a yanked version (with a
+            warning). A deprecated version installs with a warning.
   publish   The reference registry has NO write API (publish is PR-based). This
             packages + Ed25519-signs a local pack dir into a signed tarball +
-            sidecars (mirrors scripts/build-pack-tarball.mjs --signed), ready to
-            commit + open a PR. Private key: --key, else ~/.openwop-keys/{keyId}.private.pem.
+            sidecars, ready to commit + open a PR against openwop-registry. The
+            default (v2) signing block is { keyId, scheme: "ed25519-canonical-json" };
+            --tree v1 writes the legacy v1 block. Private key: --key, else
+            ~/.openwop-keys/{keyId}.private.pem.
   yank      Edits a local registry checkout \u2014 flips "yanked": true in the version
-            manifest (--undo reverses). The published change lands via PR + a
+            manifest under registry/v2/ (--tree v1 for the frozen v1 tree;
+            --undo reverses). The published change lands via PR + a
             build-index.mjs rerun. Run from inside the repo.
+
+Exit codes: 0 ok \xB7 1 verification / integrity / resolution failure \xB7 2 usage.
 `;
 async function runPacks(ctx, argv) {
   const sub = argv[0];
@@ -15023,6 +15069,71 @@ Run \`openwop packs --help\` for usage.`);
 function registryUrlFor(options, env) {
   return normalizeBaseUrl(options.registryUrl ?? env.OPENWOP_REGISTRY_URL ?? DEFAULT_REGISTRY_URL);
 }
+var REQUIRED_ENDPOINTS = ["registryIndex", "packMetadata", "versionManifest", "versionTarball", "versionSignature"];
+var LEGACY_V1_ENDPOINTS = {
+  registryIndex: "/v1/index.json",
+  packMetadata: "/v1/packs/{name}/index.json",
+  versionManifest: "/v1/packs/{name}/-/{version}.json",
+  versionTarball: "/v1/packs/{name}/-/{version}.tgz",
+  versionSignature: "/v1/packs/{name}/-/{version}.sig",
+  publicKey: "/keys/{keyId}.pub"
+};
+function treeOption(options) {
+  if (options.tree === void 0) return void 0;
+  if (options.tree !== "v1" && options.tree !== "v2") throw new CliError(`--tree must be v1 or v2 (got "${options.tree}").`);
+  return options.tree;
+}
+function stringTemplates(value) {
+  const out = {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) return out;
+  for (const [k, v] of Object.entries(value)) if (typeof v === "string" && !k.startsWith("_")) out[k] = v;
+  return out;
+}
+async function resolveRegistry(ctx, options) {
+  const url = registryUrlFor(options, ctx.env);
+  const forced = treeOption(options);
+  let doc = null;
+  try {
+    doc = await registryJson(ctx, url, "/.well-known/openwop-registry.json");
+  } catch (err) {
+    if (!(err instanceof HttpError) || err.status !== 404) throw err;
+  }
+  const endpoints = doc && typeof doc.endpoints === "object" ? doc.endpoints : null;
+  if (!endpoints) {
+    if (forced === "v2") throw new CliError(`${url} publishes no /.well-known/openwop-registry.json endpoints map, so no v2 tree can be resolved.`, 1);
+    return { url, tree: "v1", endpoints: { ...LEGACY_V1_ENDPOINTS }, signingKeys: null, source: "legacy-v1" };
+  }
+  const flat = stringTemplates(endpoints);
+  const publicKey = flat.publicKey ?? LEGACY_V1_ENDPOINTS.publicKey;
+  const v2 = stringTemplates(endpoints.v2);
+  const hasV2 = REQUIRED_ENDPOINTS.every((k) => typeof v2[k] === "string");
+  let tree;
+  let map;
+  let source;
+  if (forced === "v2" || forced === void 0 && hasV2) {
+    if (!hasV2) throw new CliError(`${url} names no v2 tree in its discovery document (endpoints.v2); retry with --tree v1.`, 1);
+    tree = "v2";
+    map = v2;
+    source = "endpoints.v2";
+  } else {
+    const v1 = stringTemplates(endpoints.v1);
+    tree = "v1";
+    map = { ...flat, ...v1 };
+    source = "endpoints.v1";
+  }
+  for (const k of REQUIRED_ENDPOINTS) {
+    if (typeof map[k] !== "string") throw new CliError(`${url}'s discovery document names no ${tree} "${k}" endpoint.`, 1);
+  }
+  return { url, tree, endpoints: { ...map, publicKey }, signingKeys: Array.isArray(doc.signingKeys) ? doc.signingKeys : null, source };
+}
+function registryPath(view, key, params = {}) {
+  const template = view.endpoints[key];
+  if (typeof template !== "string") throw new CliError(`${view.url}'s discovery document names no "${key}" endpoint.`, 1);
+  return template.replace(/\{([A-Za-z]+)\}/g, (_m, p) => {
+    if (params[p] === void 0) throw new CliError(`Registry endpoint ${key} needs {${p}}.`, 1);
+    return encodeURIComponent(params[p]);
+  });
+}
 async function registryJson(ctx, registryUrl, path) {
   const url = new URL(path, registryUrl + "/");
   const res = await ctx.fetchImpl(url, { method: "GET", headers: { accept: "application/json" } });
@@ -15043,15 +15154,15 @@ async function registryBytes(ctx, registryUrl, path) {
 async function runPacksSearch(ctx, argv) {
   const { options, positionals } = parseOptions(argv, {
     bool: ["--help"],
-    value: ["--registry-url", "--limit"]
+    value: ["--registry-url", "--limit", "--tree"]
   });
   if (options.help) {
     write(ctx.io.stdout, PACKS_HELP);
     return 0;
   }
   const query = String(positionals[0] ?? "").toLowerCase();
-  const registryUrl = registryUrlFor(options, ctx.env);
-  const index = await registryJson(ctx, registryUrl, "/v1/index.json");
+  const registry = await resolveRegistry(ctx, options);
+  const index = await registryJson(ctx, registry.url, registryPath(registry, "registryIndex"));
   const packs = Array.isArray(index?.packs) ? index.packs : [];
   const matched = packs.filter((p) => {
     if (!query) return true;
@@ -15060,7 +15171,7 @@ async function runPacksSearch(ctx, argv) {
   });
   const limit = Number(options.limit ?? 30);
   if (ctx.json) {
-    writeJson(ctx.io.stdout, { query: positionals[0] ?? "", total: matched.length, packs: matched });
+    writeJson(ctx.io.stdout, { query: positionals[0] ?? "", tree: registry.tree, total: matched.length, packs: matched });
     return 0;
   }
   if (matched.length === 0) {
@@ -15083,7 +15194,7 @@ async function runPacksSearch(ctx, argv) {
 async function runPacksInfo(ctx, argv) {
   const { options, positionals } = parseOptions(argv, {
     bool: ["--help"],
-    value: ["--registry-url", "--version"]
+    value: ["--registry-url", "--version", "--tree"]
   });
   if (options.help) {
     write(ctx.io.stdout, PACKS_HELP);
@@ -15091,15 +15202,11 @@ async function runPacksInfo(ctx, argv) {
   }
   const name = positionals[0];
   if (!name) throw new CliError("packs info requires a pack name.\nUsage: openwop packs info <name> [--version v]");
-  const registryUrl = registryUrlFor(options, ctx.env);
-  const pack = await registryJson(ctx, registryUrl, `/v1/packs/${encodeURIComponent(name)}/index.json`);
+  const registry = await resolveRegistry(ctx, options);
+  const pack = await packMetadata(ctx, registry, name);
   let versionManifest = null;
   if (options.version) {
-    versionManifest = await registryJson(
-      ctx,
-      registryUrl,
-      `/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(options.version)}.json`
-    );
+    versionManifest = await registryJson(ctx, registry.url, registryPath(registry, "versionManifest", { name, version: options.version }));
   }
   if (ctx.json) {
     writeJson(ctx.io.stdout, versionManifest ? { ...pack, requestedVersion: versionManifest } : pack);
@@ -15111,7 +15218,8 @@ async function runPacksInfo(ctx, argv) {
     `Latest:      ${pack.latest ?? "(none)"}`,
     `License:     ${pack.license || "\u2014"}`,
     `Author:      ${pack.author || "\u2014"}`,
-    `Description: ${pack.description || "\u2014"}`
+    `Description: ${pack.description || "\u2014"}`,
+    `Tree:        ${registry.tree}`
   ];
   if (pack.homepage) lines.push(`Homepage:    ${pack.homepage}`);
   lines.push("");
@@ -15121,7 +15229,7 @@ async function runPacksInfo(ctx, argv) {
     const rows = versions.map((v) => ({
       version: v.version,
       keyId: v.signingKeyId ?? "",
-      flags: v.yanked ? "yanked" : v.deprecated ? "deprecated" : "",
+      flags: versionFlags(v),
       integrity: typeof v.integrity === "string" ? v.integrity.slice(0, 24) + "\u2026" : ""
     }));
     writeLine(ctx.io.stdout, formatTable(rows, ["version", "keyId", "flags", "integrity"]));
@@ -15130,38 +15238,52 @@ async function runPacksInfo(ctx, argv) {
   }
   return 0;
 }
+async function packMetadata(ctx, registry, name) {
+  try {
+    return await registryJson(ctx, registry.url, registryPath(registry, "packMetadata", { name }));
+  } catch (err) {
+    if (err instanceof HttpError && err.status === 404) throw new CliError(`No pack named ${name} on ${registry.url} (${registry.tree} tree). Try \`openwop packs search\`.`, 2);
+    throw err;
+  }
+}
+function versionFlags(v) {
+  return v?.yanked ? "yanked" : v?.versionDeprecated || v?.deprecated ? "deprecated" : "";
+}
 async function runPacksInstall(ctx, argv) {
   const { options, positionals } = parseOptions(argv, {
     bool: ["--help", "--no-verify"],
-    value: ["--registry-url", "--version", "--dir"]
+    value: ["--registry-url", "--version", "--dir", "--tree"]
   });
   if (options.help) {
     write(ctx.io.stdout, PACKS_HELP);
     return 0;
   }
   let name = positionals[0];
-  let version = options.version;
+  let requested = options.version;
   if (name && name.includes("@")) {
     const at = name.lastIndexOf("@");
-    version = version ?? name.slice(at + 1);
+    requested = requested ?? name.slice(at + 1);
     name = name.slice(0, at);
   }
   if (!name) throw new CliError("packs install requires a pack name.\nUsage: openwop packs install <name>[@version] [--version v]");
-  const registryUrl = registryUrlFor(options, ctx.env);
-  if (!version) {
-    const pack = await registryJson(ctx, registryUrl, `/v1/packs/${encodeURIComponent(name)}/index.json`);
-    version = pack?.latest;
-    if (!version) throw new CliError(`Could not resolve a version for ${name}; pass --version.`);
+  const registry = await resolveRegistry(ctx, options);
+  const warnings = [];
+  let version;
+  if (requested && isExactVersion(requested)) {
+    version = requested;
+  } else {
+    const pack = await packMetadata(ctx, registry, name);
+    version = resolveVersion(name, pack, requested);
   }
-  const manifest = await registryJson(
-    ctx,
-    registryUrl,
-    `/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.json`
-  );
+  const manifest = await registryJson(ctx, registry.url, registryPath(registry, "versionManifest", { name, version }));
   if (manifest?.yanked) {
-    throw new CliError(`${name}@${version} has been yanked and cannot be installed.`, 1);
+    warnings.push(`${name}@${version} is yanked${manifest.yankedReason ? ` (${manifest.yankedReason})` : ""}; installing it because it was pinned exactly.`);
   }
-  const tgz = await registryBytes(ctx, registryUrl, `/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.tgz`);
+  if (manifest?.versionDeprecated || manifest?.deprecated) {
+    const reason = manifest.deprecationReason ?? (typeof manifest.deprecated === "string" ? manifest.deprecated : "");
+    warnings.push(`${name}@${version} is deprecated${reason ? ` (${reason})` : ""}${manifest.supersededBy ? `; superseded by ${manifest.supersededBy}` : ""}.`);
+  }
+  const tgz = await registryBytes(ctx, registry.url, registryPath(registry, "versionTarball", { name, version }));
   const integrity = "sha256-" + createHash("sha256").update(tgz).digest("base64");
   if (manifest?.integrity && manifest.integrity !== integrity) {
     throw new CliError(
@@ -15171,19 +15293,7 @@ async function runPacksInstall(ctx, argv) {
   }
   let verifyResult = "skipped";
   if (!options.noVerify) {
-    const keyId = manifest?.signing?.keyId ?? manifest?.signing?.publicKeyRef;
-    if (!keyId) throw new CliError(`${name}@${version} manifest has no signing key reference; re-run with --no-verify to bypass.`, 1);
-    const sig = await registryBytes(ctx, registryUrl, `/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.sig`);
-    if (sig.length !== 64) throw new CliError(`Signature for ${name}@${version} is ${sig.length} bytes; expected 64 for Ed25519.`, 1);
-    const pubPem = (await registryBytes(ctx, registryUrl, `/keys/${encodeURIComponent(keyId)}.pub`)).toString("utf8");
-    const publicKey = createPublicKey(pubPem);
-    const method = manifest?.signing?.method ?? "ed25519";
-    const signedBytes = method === "manual" ? extractPackJsonBytes(tgz) : tgz;
-    const valid = ed25519Verify(null, signedBytes, publicKey, sig);
-    if (!valid) {
-      throw new CliError(`Signature verification FAILED for ${name}@${version} (keyId=${keyId}, method=${method}).`, 1);
-    }
-    verifyResult = `verified (keyId=${keyId}, method=${method})`;
+    verifyResult = registry.tree === "v2" ? await verifyV2(ctx, registry, name, version, manifest, tgz) : await verifyV1(ctx, registry, name, version, manifest, tgz);
   }
   const baseDir = options.dir ? resolvePath8(ctx.cwd, options.dir) : join6(configHomeDir(ctx.env), "packs");
   const destDir = join6(baseDir, name, version);
@@ -15192,27 +15302,182 @@ async function runPacksInstall(ctx, argv) {
   const manifestPath = join6(destDir, `${version}.json`);
   writeFileSync10(tgzPath, tgz);
   writeFileSync10(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  for (const w of warnings) writeLine(ctx.io.stderr, `warning: ${w}`);
   if (ctx.json) {
     writeJson(ctx.io.stdout, {
       name,
       version,
+      tree: registry.tree,
       integrity,
       signature: verifyResult,
+      yanked: Boolean(manifest?.yanked),
+      deprecated: Boolean(manifest?.versionDeprecated || manifest?.deprecated),
       tarball: tgzPath,
       manifest: manifestPath
     });
     return 0;
   }
-  writeLine(ctx.io.stdout, `Installed ${name}@${version}`);
+  writeLine(ctx.io.stdout, `Installed ${name}@${version} (${registry.tree} tree)`);
   writeLine(ctx.io.stdout, `  signature: ${verifyResult}`);
   writeLine(ctx.io.stdout, `  integrity: ${integrity}`);
   writeLine(ctx.io.stdout, `  tarball:   ${tgzPath}`);
   return 0;
 }
+async function verifyV1(ctx, registry, name, version, manifest, tgz) {
+  const keyId = manifest?.signing?.keyId ?? manifest?.signing?.publicKeyRef;
+  if (!keyId) throw new CliError(`${name}@${version} manifest has no signing key reference; re-run with --no-verify to bypass.`, 1);
+  const sig = await registryBytes(ctx, registry.url, registryPath(registry, "versionSignature", { name, version }));
+  if (sig.length !== 64) throw new CliError(`Signature for ${name}@${version} is ${sig.length} bytes; expected 64 for Ed25519.`, 1);
+  const pubPem = (await registryBytes(ctx, registry.url, registryPath(registry, "publicKey", { keyId }))).toString("utf8");
+  const method = manifest?.signing?.method ?? "ed25519";
+  const signedBytes = method === "manual" ? extractPackJsonBytes(tgz) : tgz;
+  if (!ed25519Verify(null, signedBytes, createPublicKey(pubPem), sig)) {
+    throw new CliError(`Signature verification FAILED for ${name}@${version} (keyId=${keyId}, method=${method}).`, 1);
+  }
+  return `verified (keyId=${keyId}, method=${method})`;
+}
+var V2_SCHEME = "ed25519-canonical-json";
+async function verifyV2(ctx, registry, name, version, manifest, tgz) {
+  const fail3 = (why) => new CliError(`Signature verification FAILED for ${name}@${version} (pack_signature_invalid): ${why}`, 1);
+  const signing = manifest?.signing;
+  if (!signing || typeof signing !== "object") throw fail3("the version manifest has no signing block; re-run with --no-verify to bypass.");
+  const legacy = ["method", "publicKeyRef", "signatureRef"].filter((k) => k in signing);
+  if (legacy.length > 0) throw fail3(`a v2 signing block carries ${legacy.join(", ")} (v1 fields; a v2 block is { keyId, scheme }).`);
+  if (signing.scheme !== V2_SCHEME) throw fail3(`signing.scheme is ${JSON.stringify(signing.scheme)}; the only v2 scheme is ${V2_SCHEME}.`);
+  const keyId = signing.keyId;
+  if (typeof keyId !== "string" || keyId === "") throw fail3("signing.keyId is missing.");
+  if (!registry.signingKeys) throw fail3(`${registry.url} publishes no signingKeys[], so the namespace check cannot run.`);
+  const key = registry.signingKeys.find((k) => k && k.keyId === keyId);
+  if (!key) throw fail3(`keyId ${keyId} is not listed in the registry's signingKeys[].`);
+  const permitted = Array.isArray(key.permittedNamespaces) ? key.permittedNamespaces : [];
+  if (!permitted.some((pattern) => namespaceCovers(pattern, name))) {
+    throw fail3(`key ${keyId} is not permitted to sign ${name} (permittedNamespaces: ${permitted.join(", ") || "none"}).`);
+  }
+  const packJson = extractPackJsonBytes(tgz);
+  let embedded;
+  try {
+    embedded = JSON.parse(packJson.toString("utf8"));
+  } catch {
+    throw fail3("the in-tarball pack.json is not JSON.");
+  }
+  if (embedded?.name !== name || embedded?.version !== version) {
+    throw fail3(`the in-tarball pack.json is ${embedded?.name}@${embedded?.version}, not ${name}@${version}.`);
+  }
+  if (embedded?.signing?.keyId !== void 0 && embedded.signing.keyId !== keyId) {
+    throw fail3(`the in-tarball pack.json names signer ${embedded.signing.keyId}, the version manifest ${keyId}.`);
+  }
+  if (canonicalJsonStringify(embedded) !== packJson.toString("utf8")) {
+    throw fail3("the in-tarball pack.json is not in canonical (RFC 8785) form, so its bytes are not what ed25519-canonical-json signs.");
+  }
+  const sig = await registryBytes(ctx, registry.url, registryPath(registry, "versionSignature", { name, version }));
+  if (sig.length !== 64) throw fail3(`the signature is ${sig.length} bytes; expected 64 for Ed25519.`);
+  const keyPath = typeof key.publicKeyUrl === "string" && key.publicKeyUrl !== "" ? key.publicKeyUrl : registryPath(registry, "publicKey", { keyId });
+  const pubPem = (await registryBytes(ctx, registry.url, keyPath)).toString("utf8");
+  if (!ed25519Verify(null, packJson, createPublicKey(pubPem), sig)) throw fail3(`the signature does not verify under ${keyId}.`);
+  const status = typeof key.status === "string" ? key.status : "active";
+  return `verified (keyId=${keyId}, scheme=${V2_SCHEME}${status !== "active" ? `, key status ${status}` : ""})`;
+}
+function namespaceCovers(pattern, name) {
+  if (typeof pattern !== "string") return false;
+  if (pattern.endsWith(".*")) return name.startsWith(pattern.slice(0, -1));
+  return name === pattern;
+}
+var SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+function isExactVersion(v) {
+  return SEMVER_RE.test(v.trim());
+}
+function parseSemver(v) {
+  const m = SEMVER_RE.exec(String(v).trim());
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre: m[4] ? m[4].split(".") : [] };
+}
+function compareSemver(a, b) {
+  const x = parseSemver(a);
+  const y = parseSemver(b);
+  if (!x || !y) return String(a).localeCompare(String(b));
+  for (const k of ["major", "minor", "patch"]) if (x[k] !== y[k]) return x[k] - y[k];
+  if (x.pre.length === 0 || y.pre.length === 0) return y.pre.length - x.pre.length;
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const p = x.pre[i];
+    const q = y.pre[i];
+    if (p === void 0) return -1;
+    if (q === void 0) return 1;
+    const pn = /^\d+$/.test(p);
+    const qn = /^\d+$/.test(q);
+    if (pn && qn && Number(p) !== Number(q)) return Number(p) - Number(q);
+    if (pn !== qn) return pn ? -1 : 1;
+    if (p !== q) return p < q ? -1 : 1;
+  }
+  return 0;
+}
+function comparator(raw) {
+  const m = /^(\^|~|>=|<=|>|<|=)?\s*v?(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(-[0-9A-Za-z.-]+)?$/.exec(raw);
+  if (!m) throw new CliError(`Unsupported version range "${raw}". Use an exact version, ^x.y.z, ~x.y.z, x.y.x, or comparators like ">=1.0.0 <2.0.0".`);
+  const op = m[1] ?? "";
+  const wild = (p) => p === void 0 || /^[xX*]$/.test(p);
+  const [maj, min, pat] = [m[2], m[3], m[4]];
+  const n = (p) => wild(p) ? 0 : Number(p);
+  const floor = `${n(maj)}.${n(min)}.${n(pat)}${m[5] ?? ""}`;
+  const cmp = (v) => compareSemver(v, floor);
+  let ceil = null;
+  if (op === "^") {
+    ceil = n(maj) > 0 || wild(min) ? `${n(maj) + 1}.0.0` : n(min) > 0 || wild(pat) ? `0.${n(min) + 1}.0` : `0.0.${n(pat) + 1}`;
+  } else if (op === "~") {
+    ceil = wild(min) ? `${n(maj) + 1}.0.0` : `${n(maj)}.${n(min) + 1}.0`;
+  } else if (op === "" || op === "=") {
+    if (wild(maj)) return () => true;
+    if (wild(min)) ceil = `${n(maj) + 1}.0.0`;
+    else if (wild(pat)) ceil = `${n(maj)}.${n(min) + 1}.0`;
+    else return (v) => cmp(v) === 0;
+  }
+  if (ceil !== null) {
+    const c = ceil;
+    return (v) => cmp(v) >= 0 && compareSemver(v, `${c}-0`) < 0;
+  }
+  switch (op) {
+    case ">=":
+      return (v) => cmp(v) >= 0;
+    case ">":
+      return (v) => cmp(v) > 0;
+    case "<=":
+      return (v) => cmp(v) <= 0;
+    default:
+      return (v) => cmp(v) < 0;
+  }
+}
+function satisfiesRange(version, range) {
+  const parsed = parseSemver(version);
+  if (!parsed) return false;
+  return range.split("||").some((set) => {
+    const parts = set.trim().replace(/(>=|<=|>|<|=|\^|~)\s+/g, "$1").split(/\s+/).filter(Boolean);
+    if (parts.length === 0) return true;
+    if (parsed.pre.length > 0 && !parts.some((p) => p.includes("-"))) return false;
+    return parts.every((p) => comparator(p)(version));
+  });
+}
+function resolveVersion(name, pack, range) {
+  const versions = Array.isArray(pack?.versions) ? pack.versions : [];
+  const unyanked = versions.filter((v) => v && typeof v.version === "string" && !v.yanked).map((v) => v.version);
+  if (!range || range === "latest") {
+    const latest = typeof pack?.latest === "string" ? pack.latest : void 0;
+    const latestEntry = versions.find((v) => v?.version === latest);
+    if (latest && versions.length === 0) return latest;
+    if (latest && latestEntry && !latestEntry.yanked) return latest;
+    const best = unyanked.filter((v) => (parseSemver(v)?.pre.length ?? 1) === 0).sort(compareSemver).pop() ?? unyanked.sort(compareSemver).pop();
+    if (!best) throw new CliError(`${name} has no installable (unyanked) version; pin an exact version to install a yanked one.`, 1);
+    return best;
+  }
+  const match = unyanked.filter((v) => satisfiesRange(v, range)).sort(compareSemver).pop();
+  if (!match) {
+    const yankedHit = versions.some((v) => v?.yanked && typeof v.version === "string" && satisfiesRange(v.version, range));
+    throw new CliError(`No unyanked version of ${name} satisfies "${range}"${yankedHit ? " (a yanked version does; pin it exactly to install it)" : ""}.`, 1);
+  }
+  return match;
+}
 async function runPacksPublish(ctx, argv) {
   const { options, positionals } = parseOptions(argv, {
     bool: ["--help"],
-    value: ["--key", "--key-id", "--out"]
+    value: ["--key", "--key-id", "--out", "--tree"]
   });
   if (options.help) {
     write(ctx.io.stdout, PACKS_HELP);
@@ -15230,9 +15495,10 @@ async function runPacksPublish(ctx, argv) {
   const version = manifest.version;
   if (!name || !version) throw new CliError('pack.json must declare both "name" and "version".');
   const keyId = options.keyId ?? "openwop-team-1";
+  const tree = treeOption(options) ?? "v2";
   const signedManifest = {
     ...manifest,
-    signing: { method: "manual", publicKeyRef: keyId, signatureRef: "keys/pack.json.sig" }
+    signing: tree === "v2" ? { keyId, scheme: V2_SCHEME } : { method: "manual", publicKeyRef: keyId, signatureRef: "keys/pack.json.sig" }
   };
   const canonical = canonicalJsonStringify(signedManifest);
   let privateKey;
@@ -15269,6 +15535,7 @@ async function runPacksPublish(ctx, argv) {
       name,
       version,
       keyId,
+      tree,
       integrity: `sha256:${sha}`,
       tarball: tgzPath,
       signature: sigPath,
@@ -15279,7 +15546,7 @@ async function runPacksPublish(ctx, argv) {
     });
     return 0;
   }
-  writeLine(ctx.io.stdout, `Packaged + signed ${name}@${version} (keyId=${keyId})`);
+  writeLine(ctx.io.stdout, `Packaged + signed ${name}@${version} for the ${tree} tree (keyId=${keyId})`);
   writeLine(ctx.io.stdout, `  tarball:   ${tgzPath}`);
   writeLine(ctx.io.stdout, `  signature: ${sigPath}`);
   writeLine(ctx.io.stdout, `  manifest:  ${manifestOut}`);
@@ -15291,15 +15558,15 @@ async function runPacksPublish(ctx, argv) {
   }
   writeLine(ctx.io.stdout, "");
   writeLine(ctx.io.stdout, "The reference registry has no write API. To publish:");
-  writeLine(ctx.io.stdout, `  1. Copy the artifacts into registry/v1/packs/${name}/-/`);
-  writeLine(ctx.io.stdout, "  2. Run `node registry/scripts/build-index.mjs` to refresh the index.");
+  writeLine(ctx.io.stdout, `  1. Copy the artifacts into registry/${tree}/packs/${name}/-/ of an openwop-registry checkout`);
+  writeLine(ctx.io.stdout, `  2. Run \`node registry/scripts/build-index.mjs --tree ${tree}\` to refresh the index.`);
   writeLine(ctx.io.stdout, "  3. Open a pull request (publishMethod: github-pull-request).");
   return 0;
 }
 async function runPacksYank(ctx, argv) {
   const { options, positionals } = parseOptions(argv, {
     bool: ["--help", "--undo"],
-    value: ["--version"]
+    value: ["--version", "--tree"]
   });
   if (options.help) {
     write(ctx.io.stdout, PACKS_HELP);
@@ -15316,7 +15583,8 @@ async function runPacksYank(ctx, argv) {
     throw new CliError("packs yank requires <name>@<version> (or <name> --version v).");
   }
   const root = requireRepoRoot(ctx);
-  const manifestPath = join6(root, "registry", "v1", "packs", name, "-", `${version}.json`);
+  const tree = treeOption(options) ?? "v2";
+  const manifestPath = join6(root, "registry", tree, "packs", name, "-", `${version}.json`);
   if (!existsSync6(manifestPath)) {
     throw new CliError(`Version manifest not found: ${manifestPath}
 (packs yank edits a local registry checkout; the published change lands via PR.)`);
@@ -15330,12 +15598,12 @@ async function runPacksYank(ctx, argv) {
   manifest.yanked = newValue;
   writeFileSync10(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
   if (ctx.json) {
-    writeJson(ctx.io.stdout, { name, version, yanked: newValue, manifest: manifestPath, publishMethod: "github-pull-request" });
+    writeJson(ctx.io.stdout, { name, version, tree, yanked: newValue, manifest: manifestPath, publishMethod: "github-pull-request" });
     return 0;
   }
   writeLine(ctx.io.stdout, `${newValue ? "Yanked" : "Un-yanked"} ${name}@${version}`);
   writeLine(ctx.io.stdout, `  edited: ${manifestPath}`);
-  writeLine(ctx.io.stdout, "  Next: run `node registry/scripts/build-index.mjs`, commit, and open a PR.");
+  writeLine(ctx.io.stdout, `  Next: run \`node registry/scripts/build-index.mjs --tree ${tree}\`, commit, and open a PR.`);
   return 0;
 }
 function canonicalJsonStringify(value) {
@@ -22507,7 +22775,10 @@ pack's main-frame ES module (GET ${BASE18}/trusted/<name>/plugins/<id>/entry.mjs
 \`rpc\` sends one ui-plugin/1 request (POST ${RPC_PRODUCT}, body { message }); the
 message is { openwop: "ui-plugin/1", type: "request", id (integer,
 default 1), method, params } unless you pass a
-whole body with --body/--body-file.
+whole body with --body/--body-file. --conformance-alias posts to the test-seam
+alias ${RPC_CONFORMANCE} instead; that seam has no v2 equivalent (the v2
+seams profile, api/seams-v2.yaml, defines no ui-plugin operation), so it is
+always sent as the v1 path, on either protocol major.
 
 Exit codes: 0 ok \xB7 2 usage / not found / rejected request \xB7 4 forbidden.
 
@@ -27010,8 +27281,10 @@ var OPENAPI_HELP = `Usage:
   openwop openapi [--out <file>] [--json]
   openwop openapi paths [--filter <text>] [--json]
 
-Fetch the host's OpenAPI document (GET /v1/openapi.json \u2014 the document the
-host serves, which lists the operations it implements).
+Fetch the host's OpenAPI document \u2014 the document the host serves, which lists
+the operations it implements. A host that speaks protocol major 2 is asked for
+GET /openapi.json with OpenWOP-Version: 2.0 (its v2 document); a v1-only host
+for GET /v1/openapi.json.
 
   (default)  Prints the document's title, version and operation count; --json
              prints the whole document; --out <file> saves it.