jishushell 0.6.5 → 0.7.3

package/node_modules/jishushell-panel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jishushell-panel",
-  "version": "0.6.5",
+  "version": "0.7.3",
   "jishushellCoreMinVersion": "0.5.28",
   "description": "JishuShell panel server and web frontend",
   "type": "module",
@@ -23,7 +23,7 @@
     "check:i18n": "node scripts/check-i18n.mjs"
   },
   "dependencies": {
-    "@fastify/static": "^8.1.0",
+    "@fastify/static": "^9.1.3",
     "fastify": "^5.2.0"
   },
   "devDependencies": {

package/node_modules/semver/classes/range.js

@@ -277,6 +277,11 @@ const parseComparator = (comp, options) => {
 
 const isX = id => !id || id.toLowerCase() === 'x' || id === '*'
 
+const invalidXRangeOrder = (M, m, p) => (
+  (isX(M) && !isX(m)) ||
+  (isX(m) && p && !isX(p))
+)
+
 // ~, ~> --> * (any, kinda silly)
 // ~2, ~2.x, ~2.x.x, ~>2, ~>2.x ~>2.x.x --> >=2.0.0 <3.0.0-0
 // ~2.0, ~2.0.x, ~>2.0, ~>2.0.x --> >=2.0.0 <2.1.0-0
@@ -294,6 +299,10 @@ const replaceTildes = (comp, options) => {
 
 const replaceTilde = (comp, options) => {
   const r = options.loose ? re[t.TILDELOOSE] : re[t.TILDE]
+  // if we're including prereleases in the match, then the lower bound is
+  // -0, the lowest possible prerelease value, just like x-ranges and carets.
+  // this keeps `~1.2` equivalent to the `1.2.x` x-range it's documented as.
+  const z = options.includePrerelease ? '-0' : ''
   return comp.replace(r, (_, M, m, p, pr) => {
     debug('tilde', comp, _, M, m, p, pr)
     let ret
@@ -301,10 +310,10 @@ const replaceTilde = (comp, options) => {
     if (isX(M)) {
       ret = ''
     } else if (isX(m)) {
-      ret = `>=${M}.0.0 <${+M + 1}.0.0-0`
+      ret = `>=${M}.0.0${z} <${+M + 1}.0.0-0`
     } else if (isX(p)) {
       // ~1.2 == >=1.2.0 <1.3.0-0
-      ret = `>=${M}.${m}.0 <${M}.${+m + 1}.0-0`
+      ret = `>=${M}.${m}.0${z} <${M}.${+m + 1}.0-0`
     } else if (pr) {
       debug('replaceTilde pr', pr)
       ret = `>=${M}.${m}.${p}-${pr
@@ -373,10 +382,10 @@ const replaceCaret = (comp, options) => {
       if (M === '0') {
         if (m === '0') {
           ret = `>=${M}.${m}.${p
-          }${z} <${M}.${m}.${+p + 1}-0`
+          } <${M}.${m}.${+p + 1}-0`
         } else {
           ret = `>=${M}.${m}.${p
-          }${z} <${M}.${+m + 1}.0-0`
+          } <${M}.${+m + 1}.0-0`
         }
       } else {
         ret = `>=${M}.${m}.${p
@@ -402,6 +411,10 @@ const replaceXRange = (comp, options) => {
   const r = options.loose ? re[t.XRANGELOOSE] : re[t.XRANGE]
   return comp.replace(r, (ret, gtlt, M, m, p, pr) => {
     debug('xRange', comp, ret, gtlt, M, m, p, pr)
+    if (invalidXRangeOrder(M, m, p)) {
+      return comp
+    }
+
     const xM = isX(M)
     const xm = xM || isX(m)
     const xp = xm || isX(p)

package/node_modules/semver/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semver",
-  "version": "7.8.2",
+  "version": "7.8.5",
   "description": "The semantic version parser used by npm.",
   "main": "index.js",
   "scripts": {
@@ -14,7 +14,7 @@
     "eslint": "eslint \"**/*.{js,cjs,ts,mjs,jsx,tsx}\""
   },
   "devDependencies": {
-    "@npmcli/eslint-config": "^6.0.0",
+    "@npmcli/eslint-config": "^7.0.0",
     "@npmcli/template-oss": "5.0.0",
     "benchmark": "^2.1.4",
     "tap": "^16.0.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jishushell",
-  "version": "0.6.5",
+  "version": "0.7.3",
   "description": "JishuShell — Raspberry Pi server management panel (Core + Web UI)",
   "type": "module",
   "jishushellPanel": {
@@ -15,62 +15,7 @@
     "./config": "./dist/config.js",
     "./auth": "./dist/auth.js",
     "./types": "./dist/types.js",
-    "./constants": "./dist/constants.js",
-    "./services/instance-admin": "./dist/services/instance-admin.js",
-    "./services/connection-admin": "./dist/services/connection-admin.js",
-    "./services/app-config-admin": "./dist/services/app-config-admin.js",
-    "./services/app-create-from-installed": "./dist/services/app-create-from-installed.js",
-    "./services/backup-admin": "./dist/services/backup-admin.js",
-    "./services/instance-manager": "./dist/services/instance-manager.js",
-    "./services/backup-manager": "./dist/services/backup-manager.js",
-    "./services/backup-verify": "./dist/services/backup-verify.js",
-    "./services/capability-registry": "./dist/services/capability-registry.js",
-    "./services/connection-resolver": "./dist/services/connection-resolver.js",
-    "./services/connection-transactor": "./dist/services/connection-transactor.js",
-    "./services/plugin-installer": "./dist/services/plugin-installer.js",
-    "./services/files-mounts": "./dist/services/files-mounts.js",
-    "./services/nomad-manager": "./dist/services/nomad-manager.js",
-    "./services/process-manager": "./dist/services/process-manager.js",
-    "./services/setup-manager": "./dist/services/setup-manager.js",
-    "./services/task-registry": "./dist/services/task-registry.js",
-    "./services/update-manager": "./dist/services/update-manager.js",
-    "./services/app-passwords": "./dist/services/app-passwords.js",
-    "./services/workspace-builder": "./dist/services/workspace-builder.js",
-    "./services/external-mounts": "./dist/services/external-mounts.js",
-    "./services/files-manager": "./dist/services/files-manager.js",
-    "./services/system-monitor": "./dist/services/system-monitor.js",
-    "./services/suggestions": "./dist/services/suggestions.js",
-    "./services/app/app-manager": "./dist/services/app/app-manager.js",
-    "./services/app/remote-spec": "./dist/services/app/remote-spec.js",
-    "./services/app/terminal-session-manager": "./dist/services/app/terminal-session-manager.js",
-    "./services/agent-apps/index": "./dist/services/agent-apps/index.js",
-    "./services/llm-proxy/encryption": "./dist/services/llm-proxy/encryption.js",
-    "./services/llm-proxy/adapters": "./dist/services/llm-proxy/adapters.js",
-    "./services/llm-proxy/circuit-breaker": "./dist/services/llm-proxy/circuit-breaker.js",
-    "./services/llm-proxy/index": "./dist/services/llm-proxy/index.js",
-    "./services/llm-proxy/instance-proxy": "./dist/services/llm-proxy/instance-proxy.js",
-    "./services/llm-proxy/providers": "./dist/services/llm-proxy/providers.js",
-    "./services/llm-proxy/proxy-runtime": "./dist/services/llm-proxy/proxy-runtime.js",
-    "./services/llm-proxy/rate-limiter": "./dist/services/llm-proxy/rate-limiter.js",
-    "./services/llm-proxy/sse": "./dist/services/llm-proxy/sse.js",
-    "./services/llm-proxy/ssrf": "./dist/services/llm-proxy/ssrf.js",
-    "./services/llm-proxy/probe": "./dist/services/llm-proxy/probe.js",
-    "./services/llm-proxy/types": "./dist/services/llm-proxy/types.js",
-    "./services/llm-proxy/usage": "./dist/services/llm-proxy/usage.js",
-    "./services/llm-proxy/validate-key": "./dist/services/llm-proxy/validate-key.js",
-    "./services/organize/applier": "./dist/services/organize/applier.js",
-    "./services/organize/rules": "./dist/services/organize/rules.js",
-    "./services/organize/scanner": "./dist/services/organize/scanner.js",
-    "./services/organize/store": "./dist/services/organize/store.js",
-    "./services/core-manager": "./dist/services/core-manager.js",
-    "./services/runtime/index": "./dist/services/runtime/index.js",
-    "./services/runtime/instance": "./dist/services/runtime/instance.js",
-    "./services/runtime/migrations": "./dist/services/runtime/migrations.js",
-    "./services/runtime/types": "./dist/services/runtime/types.js",
-    "./services/webdav/server": "./dist/services/webdav/server.js",
-    "./utils/fs": "./dist/utils/fs.js",
-    "./utils/safe-json": "./dist/utils/safe-json.js",
-    "./utils/ttl-cache": "./dist/utils/ttl-cache.js"
+    "./constants": "./dist/constants.js"
   },
   "files": [
     "dist/",
@@ -83,7 +28,7 @@
     "openclaw-entry.sh",
     "INSTALL-NOTICE",
     "THIRD-PARTY-NOTICES",
-    "dependencies/jishushell-panel-0.6.5.tgz"
+    "dependencies/jishushell-panel-0.7.3.tgz"
   ],
   "scripts": {
     "build": "npm install && npm run compile:backend",
@@ -117,12 +62,12 @@
     "build:pack": "npm run build && npm pack",
     "build:pack:cli": "npm run build:pack",
     "build:pack:gui": "npm run build && node scripts/pack-with-gui.mjs",
-    "check:contracts": "node --experimental-strip-types scripts/check-adapter-isolation.ts && node scripts/check-open-core-boundaries.mjs && node scripts/check-colima-launchd.mjs",
+    "check:contracts": "node --experimental-strip-types scripts/check-integration-isolation.ts && node scripts/check-app-path-boundaries.mjs && node scripts/check-architecture-boundaries.mjs && node scripts/check-open-core-boundaries.mjs && node scripts/check-colima-launchd.mjs",
     "check:open-core-boundaries": "node scripts/check-open-core-boundaries.mjs",
     "check:i18n": "echo 'i18n checks live in sibling repo ../jishushell-panel.'",
     "check:app-spec": "node scripts/check-app-spec.mjs",
     "check:new-file-tests": "node scripts/check-new-file-tests.mjs",
-    "release:pack": "npm run build && npm pack",
+    "release:pack": "npm run build:pack:gui",
     "release:pack:gui": "npm run build:pack:gui"
   },
   "engines": {
@@ -142,7 +87,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@fastify/multipart": "^10.0.0",
-    "@fastify/static": "^8.1.0",
+    "@fastify/static": "^9.1.3",
     "@noble/hashes": "^2.0.1",
     "bcryptjs": "^2.4.3",
     "exifr": "^7.1.3",
@@ -150,11 +95,14 @@
     "jsonwebtoken": "^9.0.2",
     "systeminformation": "^5.23.0",
     "yaml": "^2.8.3",
-    "jishushell-panel": "file:dependencies/jishushell-panel-0.6.5.tgz"
+    "jishushell-panel": "file:dependencies/jishushell-panel-0.7.3.tgz"
   },
   "optionalDependencies": {
     "macos-temperature-sensor": "^1.0.4"
   },
+  "overrides": {
+    "qs": "6.15.2"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
     "@stryker-mutator/core": "^9.6.1",
@@ -163,10 +111,10 @@
     "@types/bcryptjs": "^2.4.6",
     "@types/jsonwebtoken": "^9.0.7",
     "@types/node": "^22.19.15",
-    "@vitest/coverage-v8": "^4.1.1",
+    "@vitest/coverage-v8": "^4.1.9",
     "pptxgenjs": "^4.0.1",
     "typescript": "^5.7.0",
-    "vitest": "^4.1.1"
+    "vitest": "^4.1.9"
   },
   "bundleDependencies": [
     "jishushell-panel"

package/scripts/check-app-path-boundaries.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * Enforce the canonical instance path boundary.
+ *
+ * Normal service code must resolve instance directories through
+ * src/services/app-common/paths.ts. Migration and repair code are excluded
+ * because they intentionally inspect historical or partially broken layouts.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+
+const REPO_ROOT = resolve(import.meta.dirname ?? ".", "..");
+const SERVICES_ROOT = resolve(REPO_ROOT, "src/services");
+const PATHS_MODULE = "src/services/app-common/paths.ts";
+
+const EXCLUDED_SEGMENTS = new Set(["legacy-migrator", "repair"]);
+const ALLOWED_DIR_RESOLVERS = new Set([
+  "resolveAppDir",
+  "resolveInstalledAppDir",
+]);
+
+const PATH_JOIN_PATTERN = /join\s*\(\s*APPS_DIR\s*,\s*([A-Za-z_$][\w$]*)\s*\)/g;
+const CONFIG_INSTANCE_DIR_PATTERN = /\bgetInstanceDir\s*\(\s*(?:instanceId|id)\s*\)/g;
+const DIR_RESOLVER_PATTERNS = [
+  /\b(?:export\s+)?function\s+([A-Za-z_$][\w$]*(?:AppDir|InstanceDir))\s*\(\s*(?:instanceId|id)\b/g,
+  /\b(?:export\s+)?const\s+([A-Za-z_$][\w$]*(?:AppDir|InstanceDir))\s*=\s*(?:async\s*)?\(?\s*(?:instanceId|id)\b/g,
+];
+
+function isSourceFile(path) {
+  return path.endsWith(".ts") && !path.endsWith(".d.ts");
+}
+
+function isExcluded(path) {
+  const rel = relative(SERVICES_ROOT, path);
+  if (rel.startsWith("..")) return true;
+  return rel.split(sep).some((segment) => EXCLUDED_SEGMENTS.has(segment));
+}
+
+function* walk(dir) {
+  for (const entry of readdirSync(dir)) {
+    const full = resolve(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      yield* walk(full);
+    } else if (stat.isFile() && isSourceFile(full) && !isExcluded(full)) {
+      yield full;
+    }
+  }
+}
+
+function lineForIndex(content, index) {
+  return content.slice(0, index).split("\n").length;
+}
+
+function isCommentLine(content, index) {
+  const lineStart = content.lastIndexOf("\n", index) + 1;
+  const lineEnd = content.indexOf("\n", index);
+  const line = content.slice(lineStart, lineEnd === -1 ? content.length : lineEnd).trimStart();
+  return line.startsWith("//") || line.startsWith("*") || line.startsWith("/*");
+}
+
+const violations = [];
+
+for (const abs of walk(SERVICES_ROOT)) {
+  const rel = relative(REPO_ROOT, abs).split(sep).join("/");
+  const content = readFileSync(abs, "utf-8");
+  const isPathsModule = rel === PATHS_MODULE;
+
+  if (!isPathsModule) {
+    let match;
+    const pathJoinPattern = new RegExp(PATH_JOIN_PATTERN.source, "g");
+    while ((match = pathJoinPattern.exec(content)) !== null) {
+      if (isCommentLine(content, match.index)) continue;
+      violations.push({
+        file: rel,
+        line: lineForIndex(content, match.index),
+        rule: "instance-path-join",
+        text: match[0],
+      });
+    }
+
+    const configInstanceDirPattern = new RegExp(CONFIG_INSTANCE_DIR_PATTERN.source, "g");
+    while ((match = configInstanceDirPattern.exec(content)) !== null) {
+      if (isCommentLine(content, match.index)) continue;
+      violations.push({
+        file: rel,
+        line: lineForIndex(content, match.index),
+        rule: "config-instance-dir",
+        text: match[0],
+      });
+    }
+  }
+
+  for (const pattern of DIR_RESOLVER_PATTERNS) {
+    let match;
+    const dirResolverPattern = new RegExp(pattern.source, "g");
+    while ((match = dirResolverPattern.exec(content)) !== null) {
+      if (isCommentLine(content, match.index)) continue;
+      const name = match[1];
+      if (isPathsModule && name === "resolveAppDir") continue;
+      if (ALLOWED_DIR_RESOLVERS.has(name)) continue;
+      violations.push({
+        file: rel,
+        line: lineForIndex(content, match.index),
+        rule: "duplicate-dir-resolver",
+        text: name,
+      });
+    }
+  }
+}
+
+if (violations.length > 0) {
+  console.error(`check-app-path-boundaries FAILED: ${violations.length} violation(s)\n`);
+  for (const violation of violations) {
+    console.error(`  ${violation.file}:${violation.line} [${violation.rule}] ${violation.text}`);
+  }
+  process.exit(1);
+}
+
+console.log("check-app-path-boundaries OK");

package/scripts/check-app-spec.mjs

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 /**
- * Validates `apps/*.yaml` against the Provider Authoring Contract
- * (docs/app-interconnect-design.md §13.2.3).
+ * Validates `apps/*.yaml` against the provider authoring contract.
  *
  * Three provide classes:
  *   A. Bindable category   — capability has CAPABILITY_CATEGORIES prefix
- *      (`llm-` / `search-` / `browser-` / `mcp-`). Must declare task,
+ *      (`llm-` / `search-` / `browser-`). Must declare task,
  *      port (resolvable to a task port via host_port ?? port), protocol
  *      from category whitelist, optional health, description.
  *   B. Legacy bindable exact — capability is in LEGACY_BINDABLE_EXACT_ALLOWLIST
@@ -31,27 +30,34 @@ const APPS_DIR = process.env.APPS_DIR_OVERRIDE ?? join(__dirname, "..", "apps");
 
 // ── Allowlists (kept here so check-app-spec stays mechanically driven) ──
 
-// Keep in sync with CAPABILITY_CATEGORIES in
-// src/services/connection-resolver.ts. `files` (W1-W2) and `knowledge`
-// (W2, AnythingLLM) are full categories with adapter hooks and slot UX.
+// Keep in sync with src/services/capabilities/contract.ts. These values are
+// deliberately small and closed: provider app ids stay free-form, but
+// matching protocol must be explicit and statically checkable.
 const CAPABILITY_CATEGORIES = new Set([
-  "llm", "search", "browser", "mcp", "files", "knowledge",
+  "llm", "search", "browser", "files", "knowledge", "ui", "terminal",
 ]);
 
+const INTERFACES_BY_KIND = {
+  llm: new Set(["openai-compatible"]),
+  search: new Set(["searxng-json"]),
+  browser: new Set(["cdp-ws"]),
+  files: new Set(["web-file-manager"]),
+  knowledge: new Set(["kb-search"]),
+  ui: new Set(["web-ui"]),
+  terminal: new Set(["terminal"]),
+};
+
 const LEGACY_BINDABLE_EXACT_ALLOWLIST = new Set([
   "ollama-api",
   "browserless-api",
 ]);
 
 const UI_LEGACY_ALLOWLIST = new Set([
-  "openwebui-web",
   "hollama-web",
-  "playwright-ui",
   "openclaw-dashboard",
   "ollama-terminal",
   "web-ui",
   "web-searxng",
-  "web-openwebui",
   "web-hermes",
   "browserless-debugger",
   "browserless-docs",
@@ -61,25 +67,116 @@ const PROTOCOL_WHITELIST = {
   llm: new Set(["http", "https"]),
   search: new Set(["http", "https"]),
   browser: new Set(["ws", "wss", "http", "https"]),
-  mcp: new Set(["http", "https", "ws", "sse"]),
   // Filebrowser exposes an HTTP Web UI under /apps/filebrowser; webdav adds
   // PROPFIND/PUT over the same HTTP origin. Both fit `http(s)`.
   files: new Set(["http", "https"]),
   // AnythingLLM exposes an OpenAI-compatible HTTP API for kb_search; baseUrl
   // is always http(s) regardless of LAN vs container host topology.
   knowledge: new Set(["http", "https"]),
+  ui: new Set(["http", "https"]),
+  terminal: new Set(["tcp"]),
   default: new Set(["http", "https", "ws", "wss", "tcp"]),
 };
 
 // ── Helpers ──
 
 function categoryOf(capability) {
+  if (CAPABILITY_CATEGORIES.has(capability)) return capability;
   const dashIdx = capability.indexOf("-");
   if (dashIdx <= 0) return null;
   const head = capability.slice(0, dashIdx);
   return CAPABILITY_CATEGORIES.has(head) ? head : null;
 }
 
+function inferLegacyInterface(kind, capability, protocol) {
+  switch (kind) {
+    case "llm": return "openai-compatible";
+    case "search": return capability === "search" || capability === "search-searxng" ? "searxng-json" : null;
+    case "browser": return "cdp-ws";
+    case "files": return "web-file-manager";
+    case "knowledge": return "kb-search";
+    case "ui": return "web-ui";
+    case "terminal": return "terminal";
+    default: return null;
+  }
+}
+
+function capabilityContract(obj) {
+  const capability = typeof obj?.capability === "string" ? obj.capability : "";
+  const explicitKind = typeof obj?.kind === "string" && CAPABILITY_CATEGORIES.has(obj.kind) ? obj.kind : null;
+  const kind = explicitKind ?? categoryOf(capability);
+  if (!kind) return null;
+  const iface = typeof obj?.interface === "string" && INTERFACES_BY_KIND[kind]?.has(obj.interface)
+    ? obj.interface
+    : inferLegacyInterface(kind, capability, obj?.protocol);
+  return iface ? { kind, interface: iface } : null;
+}
+
+function isContractRequire(req) {
+  // Keep mirrored with src/services/capabilities/contract.ts. The checker runs
+  // as a standalone Node script, so this local copy must preserve the same
+  // domain rule: category tokens (`llm`, `search`) use kind/interface
+  // matching; concrete provider capabilities (`llm-ollama`) remain exact.
+  return typeof req?.capability === "string" && CAPABILITY_CATEGORIES.has(req.capability);
+}
+
+function capabilityMatchesRequire(req, provider) {
+  if (!isContractRequire(req)) {
+    return provider?.capability === req?.capability;
+  }
+  const reqContract = capabilityContract(req);
+  const providerContract = capabilityContract(provider);
+  if (reqContract && providerContract) {
+    return providerContract.kind === reqContract.kind && providerContract.interface === reqContract.interface;
+  }
+  return provider?.capability === req?.capability;
+}
+
+function validateStructuredContract(file, label, item) {
+  const hasKind = item.kind !== undefined;
+  const hasInterface = item.interface !== undefined;
+  if (!hasKind && !hasInterface) return;
+  if (typeof item.kind !== "string" || !CAPABILITY_CATEGORIES.has(item.kind)) {
+    err(file, `${label} kind must be one of ${[...CAPABILITY_CATEGORIES].join("|")}`);
+    return;
+  }
+  if (typeof item.interface !== "string" || !INTERFACES_BY_KIND[item.kind]?.has(item.interface)) {
+    err(file, `${label} interface '${item.interface}' is not valid for kind '${item.kind}'`);
+  }
+}
+
+function validateEndpoint(file, spec, cap, provide) {
+  if (provide.endpoint === undefined) return;
+  if (typeof provide.endpoint !== "object" || provide.endpoint === null || Array.isArray(provide.endpoint)) {
+    err(file, `provide '${cap}' endpoint must be an object`);
+    return;
+  }
+  if (typeof provide.endpoint.portName !== "string" || !provide.endpoint.portName) {
+    err(file, `provide '${cap}' endpoint.portName is required when endpoint is declared`);
+  }
+  if ("hostPort" in provide.endpoint || "host" in provide.endpoint) {
+    err(file, `provide '${cap}' endpoint must not declare host/hostPort; use runtime.ports[].hostPort`);
+  }
+  for (const key of Object.keys(provide.endpoint)) {
+    if (key !== "portName") {
+      err(file, `provide '${cap}' endpoint.${key} is not supported; keep protocol/path as top-level provide fields`);
+    }
+  }
+  if (typeof provide.task !== "string" || !provide.task) {
+    err(file, `provide '${cap}' endpoint.portName requires provide.task so it can be checked against task ports[]`);
+    return;
+  }
+  const task = findTask(spec, provide.task);
+  if (!task) return;
+  if (
+    typeof provide.endpoint.portName === "string"
+    && provide.endpoint.portName
+    && !findNamedPortInTask(task, provide.endpoint.portName)
+  ) {
+    err(file, `provide '${cap}' endpoint.portName '${provide.endpoint.portName}' not in task '${provide.task}' ports[]`);
+  }
+}
+
 function isUILegacy(capability) {
   if (UI_LEGACY_ALLOWLIST.has(capability)) return true;
   if (capability.startsWith("web-")) return true;
@@ -172,6 +269,10 @@ function findPortInTask(task, providePort) {
   return (task?.ports ?? []).find((p) => hostPortOf(p) === providePort);
 }
 
+function findNamedPortInTask(task, portName) {
+  return (task?.ports ?? []).find((p) => p?.name === portName);
+}
+
 // ── Main ──
 
 const errors = [];
@@ -219,27 +320,16 @@ const allowedRequiresExact = new Set([
 ]);
 
 // Index every provide capability across the repo for orphan-require check.
-const providersByCapability = new Map();
+const allProviders = [];
 for (const { spec } of specs) {
   for (const provide of spec.provides ?? []) {
     if (typeof provide?.capability !== "string") continue;
-    if (!providersByCapability.has(provide.capability)) {
-      providersByCapability.set(provide.capability, []);
-    }
-    providersByCapability.get(provide.capability).push({ spec });
+    allProviders.push(provide);
   }
 }
 
 function hasProviderForRequire(req) {
-  // A path: prefix match against any provide name starting with `${req}-`.
-  if (CAPABILITY_CATEGORIES.has(req)) {
-    for (const cap of providersByCapability.keys()) {
-      if (cap.startsWith(req + "-")) return true;
-    }
-    return false;
-  }
-  // B path: exact match.
-  return providersByCapability.has(req);
+  return allProviders.some((provider) => capabilityMatchesRequire(req, provider));
 }
 
 // Second pass: validate each spec.
@@ -254,6 +344,7 @@ for (const { file, spec } of specs) {
     }
     const cap = provide.capability;
     const cat = categoryOf(cap);
+    validateStructuredContract(file, `provide '${cap}'`, provide);
     const isB =
       !cat &&
       (LEGACY_BINDABLE_EXACT_ALLOWLIST.has(cap) || exactRequiresInRepo.has(cap)) &&
@@ -267,6 +358,7 @@ for (const { file, spec } of specs) {
       }
       continue;
     }
+    validateEndpoint(file, spec, cap, provide);
 
     if (cat) {
       // Class A
@@ -321,6 +413,7 @@ for (const { file, spec } of specs) {
       if (provide.auth !== undefined) {
         err(file, `provide '${cap}' auth is not allowed on UI-only or url-only provides`);
       }
+
       if (typeof provide.port === "number") {
         if (typeof provide.task === "string" && provide.task) {
           const task = findTask(spec, provide.task);
@@ -338,9 +431,9 @@ for (const { file, spec } of specs) {
     }
 
     // ── §17 (PR 8): tool_schema validation — applies to any bindable
-    //    capability that an LLM-binding adapter may turn into an MCP
-    //    server entry (i.e. category A search-/mcp-, plus any future
-    //    bindable cap). Warn-only this release; promoted to err in v0.5.
+    //    capability that an LLM integration hook may turn into an MCP
+    //    server entry (i.e. category A search-, plus any future bindable
+    //    cap). Warn-only this release; promoted to err in v0.5.
     if (provide.tool_schema !== undefined) {
       const ts = provide.tool_schema;
       if (typeof ts !== "object" || ts === null) {
@@ -388,6 +481,7 @@ for (const { file, spec } of specs) {
     }
     const isCategory = CAPABILITY_CATEGORIES.has(req.capability);
     const isExact = allowedRequiresExact.has(req.capability);
+    validateStructuredContract(file, `require '${req.capability}'`, req);
     if (!isCategory && !isExact) {
       err(
         file,
@@ -422,7 +516,7 @@ for (const { file, spec } of specs) {
     }
 
     // Orphan-require check: at least one provider in the repo must satisfy.
-    if (!hasProviderForRequire(req.capability)) {
+    if (!hasProviderForRequire(req)) {
       const isRequired = req.required !== false; // default true
       if (isRequired) {
         err(