@appstrate/afps-shared 0.7.0 → 0.9.0

package/README.md

@@ -35,6 +35,7 @@ import each module by subpath.
 | `./file-field`                       | File-field parsing helpers.                                                                                                                                 |
 | `./token-usage`                      | Token-usage accounting shapes.                                                                                                                              |
 | `./backoff`                          | Retry backoff computation.                                                                                                                                  |
+| `./jsonpath`                         | The single-value RFC 9535 JSONPath subset every integration-manifest path field is read with (`identity_claims`, login-engine selectors).                   |
 
 ```ts
 import { guardedFetch } from "@appstrate/afps-shared/guarded-fetch";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/afps-shared",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Zero-dependency AFPS helpers shared by @appstrate/core and @appstrate/afps-runtime (companion-file checks, semver resolution, SRI integrity, credential templates, delivery.http projection)",
   "license": "Apache-2.0",
   "type": "module",
@@ -51,12 +51,14 @@
     "./unzip-bounded": "./src/unzip-bounded.ts",
     "./archive-prefix": "./src/archive-prefix.ts",
     "./backoff": "./src/backoff.ts",
-    "./mime": "./src/mime.ts"
+    "./mime": "./src/mime.ts",
+    "./jsonpath": "./src/jsonpath.ts"
   },
   "dependencies": {
     "@types/semver": "^7.8.0",
     "fflate": "^0.8.3",
-    "semver": "^7.8.4"
+    "semver": "^7.8.4",
+    "yaml": "^2.9.0"
   },
   "peerDependencies": {
     "typescript": ">=5 <8"

package/src/api-tool-naming.ts

@@ -1,7 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Appstrate
 
-import { MCP_TOOL_NAME_MAX_LENGTH, MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH } from "./mcp-naming.ts";
+import {
+  fnv1a64Hex,
+  MCP_TOOL_NAME_MAX_LENGTH,
+  MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH,
+} from "./mcp-naming.ts";
 
 /** Canonical unprefixed name of the credential-injecting API tool. */
 export const API_CALL_TOOL_NAME = "api_call";
@@ -36,7 +40,7 @@ const API_TOOL_AUTH_HASH_HEX_LENGTH = API_TOOL_AUTH_TOKEN_LENGTH - 2;
  */
 export function apiToolAuthToken(authKey: string): string {
   if (authKey.length <= API_TOOL_RAW_AUTH_KEY_MAX_LENGTH) return authKey;
-  return `h0${fnv1a64(authKey).slice(0, API_TOOL_AUTH_HASH_HEX_LENGTH)}`;
+  return `h0${fnv1a64Hex(authKey).slice(0, API_TOOL_AUTH_HASH_HEX_LENGTH)}`;
 }
 
 /** Throw when two distinct auth keys collapse onto the same bounded token. */
@@ -54,17 +58,6 @@ export function assertUniqueApiToolAuthTokens(authKeys: readonly string[]): void
   }
 }
 
-function fnv1a64(value: string): string {
-  let hash = 0xcbf29ce484222325n;
-  const prime = 0x100000001b3n;
-  const mask = 0xffffffffffffffffn;
-  for (const byte of new TextEncoder().encode(value)) {
-    hash ^= BigInt(byte);
-    hash = (hash * prime) & mask;
-  }
-  return hash.toString(16).padStart(16, "0");
-}
-
 /** Derive the unprefixed api_call name for one auth surface. */
 export function apiCallToolNameForAuth(authKey: string, multiAuth: boolean): string {
   return multiAuth ? `${API_CALL_TOOL_NAME}__${apiToolAuthToken(authKey)}` : API_CALL_TOOL_NAME;

package/src/companion-files.ts

@@ -17,6 +17,8 @@
  *     `bundle/validate-bundle.ts`; it is not a package subpath either.
  */
 
+import { parse as parseYaml } from "yaml";
+
 /**
  * Stable, machine-readable companion-file violation reasons.
  */
@@ -24,7 +26,11 @@ export type CompanionViolationReason =
   | "AGENT_MISSING_PROMPT"
   | "AGENT_EMPTY_PROMPT"
   | "SKILL_MISSING_SKILL_MD"
+  | "SKILL_INVALID_FRONTMATTER"
   | "SKILL_MISSING_FRONTMATTER_NAME"
+  | "SKILL_INVALID_FRONTMATTER_NAME"
+  | "SKILL_MISSING_FRONTMATTER_DESCRIPTION"
+  | "SKILL_INVALID_FRONTMATTER_DESCRIPTION"
   | "MCP_SERVER_MISSING_ENTRY_POINT";
 
 /**
@@ -70,6 +76,27 @@ export function companionFilesFromRecord(files: Record<string, Uint8Array>): Com
   };
 }
 
+/**
+ * Candidate spellings for a manifest-declared archive path, in order.
+ *
+ * A manifest may write `./server.js` or `server.js`; zip entries are stored
+ * without the `./` prefix. Only the leading `./` is normalised — `..`
+ * segments and absolute paths are NOT resolved, so this cannot widen the
+ * lookup beyond the archive root.
+ */
+function archivePathCandidates(declared: string): string[] {
+  const stripped = declared.startsWith("./") ? declared.slice(2) : declared;
+  return stripped === declared ? [declared] : [declared, stripped];
+}
+
+/** First candidate spelling of `declared` present in `files`, else null. */
+function resolveArchivePath(files: CompanionFileSource, declared: string): string | null {
+  for (const candidate of archivePathCandidates(declared)) {
+    if (files.has(candidate)) return candidate;
+  }
+  return null;
+}
+
 /**
  * Validate companion-file presence per AFPS §3.3 / §3.4 for the given
  * package type. Returns the first violation encountered, or `null` when
@@ -77,8 +104,9 @@ export function companionFilesFromRecord(files: Record<string, Uint8Array>): Com
  *
  * The check is intentionally minimal and presence-focused:
  *   - `agent` → `prompt.md` present at root, non-empty bytes (§3.2).
- *   - `skill` → `SKILL.md` present at root, with YAML frontmatter `name`
- *     (§3.3). Missing `description` is tolerated per spec.
+ *   - `skill` → `SKILL.md` present at root, with a YAML frontmatter `name`
+ *     (§3.3). Missing `description` is tolerated — this is the LOADER gate;
+ *     the producer rule is {@link checkSkillMarkdown}.
  *   - `mcp-server` → file at `manifest.server.entry_point` present in the
  *     archive (§3.4 "self-contained — every runtime dep bundled").
  *   - `integration` → no required companion (§3.5).
@@ -144,7 +172,14 @@ export function checkCompanionFiles(
         message: "mcp-server manifest must declare server.entry_point",
       };
     }
-    if (!files.has(entryPoint)) {
+    // MCPB manifests conventionally write the entry point relative-explicit
+    // (`./server.js`), while archive entries are stored flat (`server.js`).
+    // Both spellings name the same file, so resolve either — an exact
+    // `has(entryPoint)` rejected every package in this repo's own
+    // `system-packages/` tree when imported through `POST /api/packages/import`,
+    // while the on-disk system-package loader accepted them. One archive, two
+    // verdicts, depending on which door it came through.
+    if (!resolveArchivePath(files, entryPoint)) {
       return {
         reason: "MCP_SERVER_MISSING_ENTRY_POINT",
         message: `mcp-server archive missing server.entry_point payload: ${entryPoint}`,
@@ -169,6 +204,12 @@ function isEffectivelyEmpty(bytes: Uint8Array): boolean {
   return true;
 }
 
+/**
+ * Deliberately NOT {@link parseSkillFrontmatter}: published artifacts exist
+ * whose frontmatter `yaml` cannot parse at all (17 in production at the time of
+ * writing, each an unquoted `description: … : …`) and the run launcher has to
+ * keep serving them, so this probe's acceptance set may never shrink.
+ */
 function hasFrontmatterName(content: string): boolean {
   const fmMatch = content.match(/^---[^\S\n]*\n([\s\S]*?)\n---/);
   if (!fmMatch) return false;
@@ -177,8 +218,191 @@ function hasFrontmatterName(content: string): boolean {
   if (!nameMatch) return false;
   const raw = (nameMatch[1] ?? "").trim();
   if (raw.length === 0) return false;
-  // Strip surrounding quotes to mirror extractSkillMeta's stripQuotes.
   const unquoted = /^(['"])(.*)\1$/.exec(raw);
   const value = unquoted ? unquoted[2] : raw;
   return (value ?? "").trim().length > 0;
 }
+
+/** Agent Skills bounds, in code points. */
+export const SKILL_NAME_MAX_LENGTH = 64;
+export const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+
+/** The bare slug an agent runtime addresses — NOT a `@scope/name` package id. */
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function codePointLength(value: string): number {
+  return [...value].length;
+}
+
+export function isValidSkillName(name: string): boolean {
+  return codePointLength(name) <= SKILL_NAME_MAX_LENGTH && SKILL_NAME_PATTERN.test(name);
+}
+
+/** Parsed `SKILL.md` frontmatter. Never throws; a parse failure is `error`. */
+export interface SkillFrontmatter {
+  found: boolean;
+  /** Opens with `---` but never closes the block. */
+  unterminated: boolean;
+  error: string | null;
+  name: string;
+  description: string;
+}
+
+/** Parses the way the skill runtime does, so the gate cannot accept what it fails to read. */
+export function parseSkillFrontmatter(content: string): SkillFrontmatter {
+  const empty = { found: false, unterminated: false, error: null, name: "", description: "" };
+
+  const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (!normalized.startsWith("---")) return empty;
+  const endIndex = normalized.indexOf("\n---", 3);
+  if (endIndex === -1) return { ...empty, unterminated: true };
+
+  const block = normalized.slice(4, endIndex);
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(block, { uniqueKeys: true, strict: true });
+  } catch (err) {
+    return {
+      ...empty,
+      found: true,
+      error: `frontmatter is not valid YAML: ${firstLine(err)}`,
+    };
+  }
+
+  const mapping = parsed ?? {};
+  if (typeof mapping !== "object" || Array.isArray(mapping)) {
+    return {
+      ...empty,
+      found: true,
+      error: "frontmatter is not valid YAML: expected a mapping of keys to values",
+    };
+  }
+
+  const record = mapping as Record<string, unknown>;
+  const name = readStringField(record, "name");
+  if (typeof name !== "string") return { ...empty, found: true, error: name.error };
+  const description = readStringField(record, "description");
+  if (typeof description !== "string") return { ...empty, found: true, error: description.error };
+
+  return { found: true, unterminated: false, error: null, name, description };
+}
+
+/** An absent key and an empty scalar both mean "not provided" and yield `""`. */
+function readStringField(record: Record<string, unknown>, key: string): string | { error: string } {
+  const value = record[key];
+  if (value === undefined || value === null) return "";
+  if (typeof value !== "string") {
+    return {
+      error: `frontmatter is not valid YAML: '${key}' must be a string, got ${describeType(value)}`,
+    };
+  }
+  return value.trim();
+}
+
+function describeType(value: unknown): string {
+  if (Array.isArray(value)) return "a list";
+  if (typeof value === "object") return "a mapping";
+  return `a ${typeof value}`;
+}
+
+function startsWithBom(content: string): boolean {
+  return content.charCodeAt(0) === 0xfeff;
+}
+
+/** `ignoreBOM: true` reads backwards: it means "do not CONSUME the BOM". */
+export function decodeSkillMarkdown(bytes: Uint8Array): string {
+  return new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes);
+}
+
+function firstLine(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err);
+  return message.split("\n")[0]!.trim();
+}
+
+/**
+ * The producer-side AFPS §3.3 gate: an Agent Skills `name`
+ * (https://agentskills.io/specification) plus a non-empty bounded `description`.
+ */
+export function checkSkillMarkdown(content: string): CompanionFileViolation | null {
+  // Rejected rather than stripped, and it stays rejected now that Pi >= 0.85
+  // strips a BOM itself: a minted version is immutable and has to load on every
+  // runtime image the platform ships, including the 0.84.x ones that test
+  // startsWith("---"), read no frontmatter behind a BOM and drop the skill.
+  // The platform's own loader eats it either way, so without this check the
+  // version would be minted and simply never load on those images.
+  if (startsWithBom(content)) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER",
+      message:
+        "skill SKILL.md starts with a byte-order mark (U+FEFF); remove it — " +
+        "older runtimes read no frontmatter behind a BOM and drop the skill",
+      path: "SKILL.md",
+    };
+  }
+
+  const { unterminated, error, name, description } = parseSkillFrontmatter(content);
+
+  if (unterminated) {
+    return {
+      reason: "SKILL_MISSING_FRONTMATTER_NAME",
+      message: "skill SKILL.md frontmatter block is not closed (expected a second '---' line)",
+      path: "SKILL.md",
+    };
+  }
+  if (error) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER",
+      message: `skill SKILL.md ${error}`,
+      path: "SKILL.md",
+    };
+  }
+  if (!name) {
+    return {
+      reason: "SKILL_MISSING_FRONTMATTER_NAME",
+      message: "skill SKILL.md must declare a 'name' in YAML frontmatter",
+      path: "SKILL.md",
+    };
+  }
+  if (!isValidSkillName(name)) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER_NAME",
+      message:
+        `skill SKILL.md 'name' must be 1-${SKILL_NAME_MAX_LENGTH} characters of lowercase ` +
+        `a-z, 0-9 and '-', with no leading or trailing hyphen and no consecutive hyphens ` +
+        `(got '${name}')`,
+      path: "SKILL.md",
+    };
+  }
+  if (!description) {
+    return {
+      reason: "SKILL_MISSING_FRONTMATTER_DESCRIPTION",
+      message: "skill SKILL.md must declare a non-empty 'description' in YAML frontmatter",
+      path: "SKILL.md",
+    };
+  }
+  const descriptionLength = codePointLength(description);
+  if (descriptionLength > SKILL_DESCRIPTION_MAX_LENGTH) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER_DESCRIPTION",
+      message:
+        `skill SKILL.md 'description' must be at most ${SKILL_DESCRIPTION_MAX_LENGTH} ` +
+        `characters (got ${descriptionLength})`,
+      path: "SKILL.md",
+    };
+  }
+
+  // Containment: `name:\n  triage` is valid YAML the loader's probe cannot
+  // read, so accepting it would mint a version the run launcher cannot load.
+  if (!hasFrontmatterName(content)) {
+    return {
+      reason: "SKILL_INVALID_FRONTMATTER_NAME",
+      message:
+        `skill SKILL.md 'name' must be written inline on one line, e.g. "name: my-skill" ` +
+        `(a name on a following line, or a space before the colon, makes the platform's ` +
+        `package loader unable to read it)`,
+      path: "SKILL.md",
+    };
+  }
+  return null;
+}

package/src/jsonpath.ts

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * The JSONPath dialect of AFPS integration manifests — a single-value RFC 9535
+ * subset: `$`, `.name` (member-name-shorthand), `['name']` / `["name"]` (RFC
+ * 9535 string literals and escapes), `[0]` / `[-1]` (RFC 9535 `int`). Anything
+ * else throws {@link JsonPathSyntaxError} rather than silently missing.
+ */
+
+export class JsonPathSyntaxError extends Error {
+  override readonly name = "JsonPathSyntaxError";
+}
+
+type JsonPathSegment = string | number;
+
+const SIMPLE_ESCAPES: Record<string, string> = {
+  b: "\b",
+  f: "\f",
+  n: "\n",
+  r: "\r",
+  t: "\t",
+  "/": "/",
+  "\\": "\\",
+};
+
+const isDigit = (ch: string) => ch >= "0" && ch <= "9";
+const isNameFirst = (ch: string) =>
+  (ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z") || ch === "_" || ch.charCodeAt(0) >= 0x80;
+const isBlank = (ch: string | undefined) => ch === " " || ch === "\t" || ch === "\n" || ch === "\r";
+
+/** Tokenize `path` into member names and array indices. Throws on anything outside the subset. */
+export function parseJsonPath(path: string): JsonPathSegment[] {
+  const fail = (at: number, what: string): never => {
+    throw new JsonPathSyntaxError(`jsonpath '${path}' at offset ${at}: ${what}`);
+  };
+  if (path[0] !== "$") fail(0, "must start with '$'");
+
+  const segments: JsonPathSegment[] = [];
+  let i = 1;
+  const skipBlank = () => {
+    while (isBlank(path[i])) i++;
+  };
+
+  const readString = (quote: string): string => {
+    const start = i;
+    i++;
+    let out = "";
+    while (i < path.length) {
+      const ch = path[i]!;
+      if (ch === quote) {
+        i++;
+        return out;
+      }
+      if (ch.charCodeAt(0) < 0x20) fail(i, "unescaped control character in string");
+      if (ch !== "\\") {
+        out += ch;
+        i++;
+        continue;
+      }
+      const esc = path[i + 1];
+      if (esc === quote) out += quote;
+      else if (esc !== undefined && esc in SIMPLE_ESCAPES) out += SIMPLE_ESCAPES[esc];
+      else if (esc === "u") {
+        const unit = readHex4(i + 2);
+        if (unit >= 0xdc00 && unit <= 0xdfff) fail(i, "lone low surrogate escape");
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+          const low = path.startsWith("\\u", i + 6) ? readHex4(i + 8) : -1;
+          if (low < 0xdc00 || low > 0xdfff)
+            fail(i, "high surrogate escape without a low surrogate");
+          out += String.fromCharCode(unit, low);
+          i += 12;
+          continue;
+        }
+        out += String.fromCharCode(unit);
+        i += 6;
+        continue;
+      } else fail(i, `invalid escape '\\${esc ?? ""}'`);
+      i += 2;
+    }
+    return fail(start, "unterminated string");
+  };
+
+  const readHex4 = (at: number): number => {
+    const hex = path.slice(at, at + 4);
+    if (!/^[0-9A-Fa-f]{4}$/.test(hex)) fail(at, "\\u must be followed by 4 hex digits");
+    return parseInt(hex, 16);
+  };
+
+  const readInt = (): number => {
+    const start = i;
+    if (path[i] === "-") i++;
+    const digitsAt = i;
+    while (isDigit(path[i] ?? "")) i++;
+    const text = path.slice(start, i);
+    if (i === digitsAt) fail(start, "expected an index");
+    if (text === "-0" || (path[digitsAt] === "0" && i - digitsAt > 1)) {
+      fail(start, `index '${text}' is not an RFC 9535 int (no leading zeros, no -0)`);
+    }
+    const n = Number(text);
+    if (!Number.isSafeInteger(n)) fail(start, `index '${text}' is out of range`);
+    return n;
+  };
+
+  while (i < path.length) {
+    const ch = path[i]!;
+    if (ch === ".") {
+      i++;
+      const start = i;
+      const first = path[i];
+      if (first === ".") fail(start, "recursive descent is not supported");
+      if (first === "*") fail(start, "a wildcard is not supported");
+      if (first !== undefined && isDigit(first)) {
+        fail(
+          start,
+          "a member name cannot start with a digit — write an index as [0] or a member as ['0']",
+        );
+      }
+      if (first === undefined || !isNameFirst(first)) fail(start, "expected a member name");
+      while (i < path.length && (isNameFirst(path[i]!) || isDigit(path[i]!))) i++;
+      segments.push(path.slice(start, i));
+    } else if (ch === "[") {
+      i++;
+      skipBlank();
+      const sel = path[i];
+      if (sel === "'" || sel === '"') segments.push(readString(sel));
+      else if (sel === "-" || (sel !== undefined && isDigit(sel))) segments.push(readInt());
+      else if (sel === undefined) fail(i, "unterminated '['");
+      else
+        fail(i, `unsupported selector '${sel}' (wildcards, filters and slices are not supported)`);
+      skipBlank();
+      if (path[i] === ",") fail(i, "a union of selectors is not supported");
+      if (path[i] === ":") fail(i, "a slice is not supported");
+      if (path[i] !== "]") fail(i, path[i] === undefined ? "unterminated '['" : "expected ']'");
+      i++;
+    } else {
+      fail(i, `unexpected character '${ch}'`);
+    }
+  }
+  return segments;
+}
+
+/**
+ * Evaluate `path` against `root`. Returns `undefined` when the path is valid
+ * but selects nothing; throws {@link JsonPathSyntaxError} when it is invalid.
+ * Members are own properties only, so `$.constructor` cannot reach a prototype.
+ */
+export function evaluateJsonPath(root: unknown, path: string): unknown {
+  let cur: unknown = root;
+  for (const seg of parseJsonPath(path)) {
+    if (cur === null || typeof cur !== "object") return undefined;
+    if (typeof seg === "number") {
+      if (!Array.isArray(cur)) return undefined;
+      cur = cur[seg < 0 ? cur.length + seg : seg];
+    } else {
+      // Not `Object.hasOwn`: the web app compiles this leaf against ES2020.
+      if (Array.isArray(cur) || !Object.prototype.hasOwnProperty.call(cur, seg)) return undefined;
+      cur = (cur as Record<string, unknown>)[seg];
+    }
+  }
+  return cur;
+}

package/src/mcp-naming.ts

@@ -13,7 +13,6 @@ export const MCP_TOOL_NAMESPACE_BASE_MAX_LENGTH = 20;
  * snake-case namespace capped before collision suffixing.
  */
 export function normaliseMcpToolNamespace(raw: string): string {
-  if (typeof raw !== "string") return "";
   const out = trimUnderscores(
     raw
       .replace(/^@/, "")
@@ -24,18 +23,61 @@ export function normaliseMcpToolNamespace(raw: string): string {
 }
 
 /**
- * Canonicalise an untrusted upstream tool body before adding our namespace.
- * An upstream namespace is stripped so `drive__api-call` becomes `api_call`,
- * matching McpHost's outward naming contract.
+ * Exposed tool-name grammar: `{snake_namespace}__{body}`, the body in the LLM
+ * providers' `^[a-zA-Z0-9_-]{1,64}$` alphabet (56-char ceiling: re-prefix headroom).
+ */
+const MCP_TOOL_NAME_PATTERN = /^[a-z0-9][a-z0-9_]*__[A-Za-z0-9_-]+$/;
+
+export function isValidMcpToolName(name: string): boolean {
+  return name.length <= MCP_TOOL_NAME_MAX_LENGTH && MCP_TOOL_NAME_PATTERN.test(name);
+}
+
+/**
+ * Map an untrusted upstream tool name onto the body alphabet: each rejected
+ * code point becomes `_`; nothing else changes.
  */
 export function normaliseMcpToolBody(raw: string): string {
-  if (typeof raw !== "string") return "";
-  let out = trimUnderscores(raw.replace(/[^a-zA-Z0-9_]+/g, "_").toLowerCase());
-  const separator = out.indexOf("__");
-  if (separator >= 0 && separator < out.length - 2) {
-    out = out.slice(separator + 2);
+  return raw.replace(/[^A-Za-z0-9_-]/gu, "_");
+}
+
+const MCP_TOOL_HASH_LENGTH = 8;
+
+/**
+ * Exposed name for an untrusted upstream tool: `{namespace}__{body}` when it
+ * fits and is free, else the body cut to fit plus a hash of the ORIGINAL
+ * upstream name, so two names that normalise to the same body (`a.b`, `a_b`)
+ * still get distinct names. Which of them keeps the plain form depends on
+ * registration order: the first one registered. One salted re-hash on
+ * collision, then it throws.
+ */
+export function allocateMcpToolName(
+  namespace: string,
+  upstreamName: string,
+  taken: (name: string) => boolean,
+): string {
+  const body = normaliseMcpToolBody(upstreamName);
+  const plain = `${namespace}__${body}`;
+  if (isValidMcpToolName(plain) && !taken(plain)) return plain;
+  const budget = MCP_TOOL_NAME_MAX_LENGTH - namespace.length - 2 - MCP_TOOL_HASH_LENGTH - 1;
+  const head = body.slice(0, Math.max(0, budget));
+  for (const seed of [upstreamName, `${upstreamName}\0`]) {
+    const hash = fnv1a64Hex(seed).slice(0, MCP_TOOL_HASH_LENGTH);
+    const candidate = head ? `${namespace}__${head}_${hash}` : `${namespace}__${hash}`;
+    if (!taken(candidate)) return candidate;
+  }
+  throw new Error(`MCP tool name ${JSON.stringify(upstreamName)} collides after re-hashing`);
+}
+
+/** 64-bit FNV-1a over the UTF-8 bytes, as 16 lowercase hex digits. */
+export function fnv1a64Hex(value: string): string {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
+  for (const byte of new TextEncoder().encode(value)) {
+    hash ^= BigInt(byte);
+    hash = (hash * prime) & mask;
   }
-  return out;
+  return hash.toString(16).padStart(16, "0");
 }
 
 /** Trim underscore runs in linear time without a backtracking expression. */

package/src/semver-resolve.ts

@@ -9,8 +9,8 @@
  * string, and for applying yank policy by pre-filtering the
  * `rangeVersions` and `distTags` inputs accordingly.
  *
- * This is the SINGLE source of truth, re-exported by
- * `@appstrate/core/semver` and `@appstrate/afps-runtime/bundle/semver-resolve`.
+ * This is the SINGLE source of truth, re-exported by `@appstrate/core/semver`
+ * and imported directly by `@appstrate/afps-runtime`.
  *
  * Conventional yank policy (matches npm/crates.io):
  * - `exactVersions`: include yanked (exact pins always resolve).