@morit/cli 1.0.0

package/src/workspace.js

@@ -0,0 +1,1630 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  chmod,
+  copyFile,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  canonicalJson,
+  createZip,
+  generateSigningKey,
+  readZip,
+  sha256,
+  signEntries,
+  verifySignedEntries,
+} from "./archive.js";
+
+const contract = JSON.parse(
+  readFileSync(new URL("../assets/plugin_contract.json", import.meta.url), "utf8"),
+);
+
+const MAX_FILES = 64;
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_PROJECT_BYTES = 1024 * 1024;
+const MAX_PACKAGE_BYTES = 2 * 1024 * 1024;
+const PLUGIN_ID = /^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9_-]*)+$/;
+const IDENTIFIER = /^[a-z][a-z0-9_.-]{1,79}$/;
+const PUBLISHER = /^[A-Za-z0-9][A-Za-z0-9._-]{1,119}$/;
+const VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+const WINDOWS_RESERVED = /^(?:con|prn|aux|nul|clock\$|com[1-9]|lpt[1-9])(?:\.|$)/i;
+const UI_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const UI_STATE_KEY = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const UI_BINDING = /^(?:state|data|item)(?:\.[A-Za-z0-9_-]+){0,12}$/;
+const UI_TEMPLATE_BINDING = /\{\{\s*([^{}]+?)\s*\}\}/g;
+const MANIFEST_FIELDS = new Set(contract.manifest_fields);
+const CAPABILITY_KINDS = new Set(contract.capability_kinds);
+const CAPABILITY_FIELDS = new Set(contract.object_fields.capability);
+const UI_EXTENSION_FIELDS = new Set(contract.object_fields.ui_extension);
+const CREDENTIAL_FIELDS = new Set(contract.object_fields.credential);
+const SLASH_COMMAND_FIELDS = new Set(contract.object_fields.slash_command);
+const CONNECTOR_FIELDS = new Set(contract.object_fields.connector);
+const DEPENDENCY_FIELDS = new Set(contract.object_fields.dependency);
+const DEVELOPER_FIELDS = new Set(contract.object_fields.developer);
+const REQUIRED_SECRET_FIELDS = new Set(contract.object_fields.required_secret);
+const CAPABILITY_RUNTIME_SHORTHAND = contract.capability_runtime_shorthand;
+const UI_POINTS = new Set(contract.ui_points);
+const RUNTIME_ADAPTERS = new Set(contract.runtime_adapters);
+const PERMISSIONS = new Set(contract.permissions);
+const CREDENTIAL_KINDS = new Set(contract.credential_kinds);
+const CONNECTOR_KINDS = new Set(contract.connector_kinds);
+const FRAGMENTS = new Map(
+  Object.entries(contract.fragment_directories)
+    .map(([directory, value]) => [directory, [value.target, value.kind]]),
+);
+const SAFE_ASSET = new Set([".gif", ".jpeg", ".jpg", ".json", ".md", ".png", ".txt", ".webp"]);
+const BINARY_ASSET = new Set([".gif", ".jpeg", ".jpg", ".png", ".webp"]);
+const BINARY_SOURCE_PREFIX = "morit-base64-v1:";
+const IGNORED_DIRECTORIES = new Set([
+  ".git", ".morit", ".morit-plugin-mcp", ".mypy_cache", ".pytest_cache", ".ruff_cache",
+  ".venv", "__pycache__", "dist", "node_modules", "venv",
+]);
+const IGNORED_FILES = new Set(["morit-plugin.json"]);
+const SAFE_ENV_TEMPLATES = new Set([".env.example", ".env.sample", ".env.template"]);
+
+export const SDK_CONTRACT = Object.freeze(contract);
+
+export class LocalWorkspace {
+  constructor(root = process.env.MORIT_PLUGIN_WORKSPACE || process.cwd()) {
+    this.root = resolve(root);
+    this.stateDirectory = join(this.root, ".morit");
+    this.statePath = join(this.stateDirectory, "state.json");
+    this.keyDirectory = resolve(
+      process.env.MORIT_PLUGIN_KEY_DIR
+        || process.env.MORIT_PLUGIN_MCP_KEY_DIR
+        || join(homedir(), ".morit", "plugin", "keys"),
+    );
+    this.state = null;
+  }
+
+  async initialize() {
+    await mkdir(this.root, { recursive: true });
+    await mkdir(this.stateDirectory, { recursive: true });
+    try {
+      this.state = JSON.parse(await readFile(this.statePath, "utf8"));
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      try {
+        this.state = JSON.parse(
+          await readFile(join(this.root, ".morit-plugin-mcp", "state.json"), "utf8"),
+        );
+      } catch (legacyError) {
+        if (legacyError.code !== "ENOENT") throw legacyError;
+        this.state = { version: 1, projects: {}, jobs: {}, artifacts: {} };
+      }
+      await this.save();
+    }
+    if (this.state?.version !== 1) throw new Error("Unsupported Morit MCP workspace state");
+    return this;
+  }
+
+  async save() {
+    const temporary = `${this.statePath}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(this.state, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(temporary, this.statePath);
+  }
+
+  async createProject({ plugin_id, name, publisher, description = "", advanced = true, directory }) {
+    validateMetadata(plugin_id, name, publisher, description);
+    const relativePath = safeProjectPath(directory || join("morit-plugins", plugin_id.split(".").at(-1)));
+    const projectRoot = this.inside(relativePath);
+    await mkdir(projectRoot, { recursive: true });
+    if ((await readDirectory(projectRoot)).length > 0) throw new Error("Project directory is not empty");
+    const manifest = {
+      schema_version: advanced ? 2 : 1,
+      id: plugin_id,
+      name: name.trim(),
+      icon: null,
+      short_description: description.slice(0, 160),
+      description,
+      category: "other",
+      keywords: [],
+      developer: { name: publisher, url: null },
+      homepage_url: null,
+      privacy_policy_url: null,
+      publisher,
+      version: "1.0.0",
+      cloud_project_id: null,
+      required_secrets: [],
+      min_morit_version: "1.7.5",
+      max_morit_version: "1.999.999",
+      permissions: [],
+      capabilities: [],
+      ui_extensions: [],
+      credentials: [],
+      connectors: [],
+      dependencies: [],
+      slash_commands: [],
+      data_policy: "purge",
+    };
+    await writeFile(join(projectRoot, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    await writeFile(
+      join(projectRoot, "README.md"),
+      `# ${name.trim()}\n\nCreated with @morit/cli.\n`,
+      "utf8",
+    );
+    if (advanced) {
+      for (const folder of [...FRAGMENTS.keys(), "src", "assets", "children", "dist"]) {
+        await mkdir(join(projectRoot, folder), { recursive: true });
+      }
+    } else {
+      await mkdir(join(projectRoot, "dist"), { recursive: true });
+    }
+    const projectId = randomUUID();
+    const files = await readProjectFiles(projectRoot);
+    this.state.projects[projectId] = {
+      id: projectId,
+      path: toPosix(relative(this.root, projectRoot)),
+      revision: 1,
+      digest: projectDigest(files),
+      plugin_id,
+      name: name.trim(),
+      publisher,
+      description,
+      updated_at: new Date().toISOString(),
+    };
+    await this.save();
+    return projectResult(this.state.projects[projectId], projectRoot, files, false);
+  }
+
+  async openProject({ path }) {
+    const relativePath = safeProjectPath(path);
+    const projectRoot = this.inside(relativePath);
+    const files = await readProjectFiles(projectRoot);
+    const manifest = compileManifest(files);
+    validateManifest(manifest, files);
+    const existing = Object.values(this.state.projects).find((value) => value.path === toPosix(relativePath));
+    if (existing) return this.getProject(existing.id, true);
+    const projectId = randomUUID();
+    this.state.projects[projectId] = {
+      id: projectId,
+      path: toPosix(relativePath),
+      revision: 1,
+      digest: projectDigest(files),
+      plugin_id: manifest.id,
+      name: manifest.name,
+      publisher: manifest.publisher,
+      description: manifest.description || "",
+      updated_at: new Date().toISOString(),
+    };
+    await this.save();
+    return projectResult(this.state.projects[projectId], projectRoot, files, true);
+  }
+
+  async getProject(projectId, includeFiles = true) {
+    const project = this.requireProject(projectId);
+    const projectRoot = this.inside(project.path);
+    const files = await readProjectFiles(projectRoot);
+    const digest = projectDigest(files);
+    if (digest !== project.digest) {
+      project.digest = digest;
+      project.revision += 1;
+      project.updated_at = new Date().toISOString();
+      const manifest = compileManifest(files);
+      project.plugin_id = String(manifest.id || project.plugin_id);
+      project.name = String(manifest.name || project.name);
+      project.publisher = String(manifest.publisher || project.publisher);
+      project.description = String(manifest.description || "");
+      await this.save();
+    }
+    return projectResult(project, projectRoot, files, includeFiles);
+  }
+
+  async putFiles(projectId, changes, revision) {
+    const current = await this.getProject(projectId, true);
+    if (current.revision !== revision) throw new Error("project revision changed; reload the project and retry");
+    if (!changes || typeof changes !== "object" || Array.isArray(changes) || Object.keys(changes).length === 0) {
+      throw new Error("files must be a non-empty object");
+    }
+    const project = this.requireProject(projectId);
+    const projectRoot = this.inside(project.path);
+    for (const [rawPath, content] of Object.entries(changes)) {
+      const path = safeFilePath(rawPath);
+      const target = resolve(projectRoot, ...path.split("/"));
+      if (content === null) {
+        if (path === "manifest.json") throw new Error("manifest.json cannot be deleted");
+        await rm(target, { force: true });
+      } else {
+        const bytes = projectFileBytes(path, content);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, bytes);
+      }
+    }
+    const files = await readProjectFiles(projectRoot);
+    if (!("manifest.json" in files)) throw new Error("manifest.json cannot be deleted");
+    project.revision += 1;
+    project.digest = projectDigest(files);
+    project.updated_at = new Date().toISOString();
+    await this.save();
+    return projectResult(project, projectRoot, files, false);
+  }
+
+  async validate(projectId) {
+    const project = await this.getProject(projectId, true);
+    const manifest = compileManifest(project.files);
+    const packageEntries = validateManifest(manifest, project.files);
+    return {
+      project_id: projectId,
+      revision: project.revision,
+      valid: true,
+      message: `validated ${manifest.id} ${manifest.version} (${packageEntries.size} package entries)`,
+      workspace_path: project.workspace_path,
+    };
+  }
+
+  async preview(projectId) {
+    const project = await this.getProject(projectId, true);
+    const manifest = compileManifest(project.files);
+    validateManifest(manifest, project.files);
+    const fileName = `${manifest.id}-preview.html`;
+    const target = join(project.workspace_path, "dist", fileName);
+    await mkdir(dirname(target), { recursive: true });
+    const html = previewHtml(manifest);
+    await writeFile(target, html);
+    return this.recordArtifact(projectId, "preview", fileName, "text/html", target, html, null);
+  }
+
+  async sourceDownload(projectId, requestedFileName) {
+    const project = await this.getProject(projectId, true);
+    const manifest = compileManifest(project.files);
+    validateManifest(manifest, project.files);
+    const fileName = artifactFileName(
+      requestedFileName,
+      ".zip",
+      `${manifest.id}-${manifest.version}-source.zip`,
+    );
+    const entries = new Map(Object.entries(project.files).map(([name, value]) => [name, projectFileBytes(name, value)]));
+    const content = createZip(entries);
+    const target = join(project.workspace_path, "dist", fileName);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, content);
+    return this.recordArtifact(projectId, "source", fileName, "application/zip", target, content, null);
+  }
+
+  async build(projectId, requestedFileName) {
+    const project = await this.getProject(projectId, true);
+    const manifest = compileManifest(project.files);
+    const entries = validateManifest(manifest, project.files);
+    const fileName = artifactFileName(
+      requestedFileName,
+      ".mplg",
+      `${manifest.id}-${manifest.version}.mplg`,
+    );
+    const privatePem = await this.signingKey(manifest.publisher);
+    const signed = signEntries(entries, manifest.publisher, privatePem);
+    const content = createZip(signed);
+    if (content.length > MAX_PACKAGE_BYTES) throw new Error("package exceeds Morit's 2 MiB upload limit");
+    verifyPackageContent(content);
+    const target = join(project.workspace_path, "dist", fileName);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, content);
+    const jobId = randomUUID();
+    const artifact = await this.recordArtifact(
+      projectId,
+      "package",
+      fileName,
+      "application/vnd.morit.plugin+zip",
+      target,
+      content,
+      jobId,
+    );
+    const now = new Date().toISOString();
+    this.state.jobs[jobId] = {
+      id: jobId,
+      project_id: projectId,
+      file_name: fileName,
+      state: "completed",
+      progress: 100,
+      artifact_id: artifact.artifact_id,
+      error_code: null,
+      error_message: null,
+      created_at: now,
+      started_at: now,
+      finished_at: now,
+      updated_at: now,
+    };
+    await this.save();
+    return jobResult(this.state.jobs[jobId]);
+  }
+
+  buildStatus(jobId) {
+    const job = this.state.jobs[jobId];
+    if (!job) throw new Error("job_id is not available in this local workspace");
+    return jobResult(job);
+  }
+
+  async artifactDownload(artifactId, requestedFileName) {
+    const artifact = this.state.artifacts[artifactId];
+    if (!artifact) throw new Error("artifact_id is not available in this local workspace");
+    const suffix = { preview: ".html", package: ".mplg", source: ".zip" }[artifact.kind];
+    const fileName = artifactFileName(requestedFileName, suffix, artifact.file_name);
+    let target = this.inside(artifact.path);
+    if (fileName !== artifact.file_name) {
+      const renamed = join(dirname(target), fileName);
+      await copyFile(target, renamed);
+      target = renamed;
+    }
+    return artifactResult(artifact, target, fileName);
+  }
+
+  async recordArtifact(projectId, kind, fileName, mimeType, absolutePath, content, jobId) {
+    const artifactId = randomUUID();
+    const artifact = {
+      id: artifactId,
+      project_id: projectId,
+      job_id: jobId,
+      kind,
+      file_name: fileName,
+      mime_type: mimeType,
+      size_bytes: content.length,
+      sha256: sha256(content),
+      path: toPosix(relative(this.root, absolutePath)),
+      created_at: new Date().toISOString(),
+    };
+    this.state.artifacts[artifactId] = artifact;
+    await this.save();
+    return artifactResult(artifact, absolutePath, fileName);
+  }
+
+  async signingKey(publisher) {
+    return signingKeyForPublisher(this.keyDirectory, publisher);
+  }
+
+  requireProject(projectId) {
+    if (typeof projectId !== "string" || !/^[0-9a-f-]{36}$/i.test(projectId)) {
+      throw new Error("project_id must be a UUID");
+    }
+    const project = this.state.projects[projectId];
+    if (!project) throw new Error("project_id is not available in this local workspace");
+    return project;
+  }
+
+  inside(relativePath) {
+    const target = resolve(this.root, relativePath);
+    if (target !== this.root && !target.startsWith(`${this.root}${sep}`)) {
+      throw new Error("Path escapes the configured local workspace");
+    }
+    return target;
+  }
+}
+
+export async function validateProjectDirectory(source) {
+  const loaded = await loadProjectDirectory(source);
+  return projectDirectoryResult(loaded);
+}
+
+export async function readProjectDirectory(source) {
+  const root = resolve(source);
+  const files = await readProjectFiles(root);
+  const manifest = compileManifest(files);
+  validateManifest(manifest, files);
+  return { root, files, manifest, digest: projectDigest(files) };
+}
+
+export async function scaffoldProjectDirectory(source, options) {
+  const root = resolve(source);
+  const workspace = await new LocalWorkspace(dirname(root)).initialize();
+  return workspace.createProject({
+    ...options,
+    directory: relative(dirname(root), root),
+  });
+}
+
+export async function previewProjectDirectory(source, output) {
+  const loaded = await loadProjectDirectory(source);
+  const target = outputPath(
+    output,
+    join(loaded.root, "dist", `${loaded.manifest.id}-preview.html`),
+    ".html",
+  );
+  const content = previewHtml(loaded.manifest);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, content);
+  return {
+    ...projectDirectoryResult(loaded),
+    output_path: target,
+    size_bytes: content.length,
+    sha256: sha256(content),
+  };
+}
+
+export async function buildProjectDirectory(source, { output, keyDirectory } = {}) {
+  const loaded = await loadProjectDirectory(source);
+  const target = outputPath(
+    output,
+    join(loaded.root, "dist", `${loaded.manifest.id}-${loaded.manifest.version}.mplg`),
+    ".mplg",
+  );
+  const privatePem = await signingKeyForPublisher(
+    resolve(
+      keyDirectory
+        || process.env.MORIT_PLUGIN_MCP_KEY_DIR
+        || join(homedir(), ".morit", "plugin-mcp", "keys"),
+    ),
+    loaded.manifest.publisher,
+  );
+  const content = createZip(signEntries(loaded.entries, loaded.manifest.publisher, privatePem));
+  if (content.length > MAX_PACKAGE_BYTES) throw new Error("package exceeds Morit's 2 MiB upload limit");
+  verifyPackageContent(content);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, content);
+  return {
+    ...projectDirectoryResult(loaded),
+    output_path: target,
+    size_bytes: content.length,
+    sha256: sha256(content),
+    signed: true,
+    signature_algorithm: "ed25519",
+  };
+}
+
+export async function sourceZipProjectDirectory(source, output) {
+  const loaded = await loadProjectDirectory(source);
+  const target = outputPath(
+    output,
+    join(loaded.root, "dist", `${loaded.manifest.id}-${loaded.manifest.version}-source.zip`),
+    ".zip",
+  );
+  const entries = new Map(
+    Object.entries(loaded.files).map(([name, content]) => [name, projectFileBytes(name, content)]),
+  );
+  const content = createZip(entries);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, content);
+  return {
+    ...projectDirectoryResult(loaded),
+    output_path: target,
+    size_bytes: content.length,
+    sha256: sha256(content),
+  };
+}
+
+export async function verifyPackageFile(packagePath) {
+  const target = resolve(packagePath);
+  const content = await readFile(target);
+  const verified = verifyPackageContent(content);
+  return {
+    valid: true,
+    package_path: target,
+    plugin_id: verified.manifest.id,
+    name: verified.manifest.name,
+    publisher: verified.manifest.publisher,
+    version: verified.manifest.version,
+    package_entries: verified.entries.size,
+    size_bytes: content.length,
+    sha256: sha256(content),
+    signature: verified.signature,
+  };
+}
+
+async function loadProjectDirectory(source) {
+  const root = resolve(source || ".");
+  const files = await readStandaloneProjectFiles(root);
+  const manifest = compileManifest(files);
+  const entries = validateManifest(manifest, files);
+  return { root, files, manifest, entries };
+}
+
+function projectDirectoryResult({ root, manifest, entries }) {
+  return {
+    valid: true,
+    source_path: root,
+    plugin_id: manifest.id,
+    name: manifest.name,
+    publisher: manifest.publisher,
+    version: manifest.version,
+    package_entries: entries.size + 1,
+  };
+}
+
+async function readStandaloneProjectFiles(root) {
+  const files = {};
+  async function visit(directory, prefix = "") {
+    let contents;
+    try {
+      contents = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === "ENOENT") throw new Error(`plugin source directory was not found: ${root}`);
+      throw error;
+    }
+    for (const entry of contents) {
+      if (entry.isSymbolicLink()) throw new Error("Project may not contain symbolic links");
+      if (IGNORED_FILES.has(entry.name)) continue;
+      const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) await visit(join(directory, entry.name), name);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const safeName = safeFilePath(name);
+      assertNonSensitiveSource(safeName);
+      const content = await readFile(join(directory, entry.name));
+      if (content.length > MAX_FILE_BYTES) throw new Error(`${safeName} exceeds the 512 KiB file limit`);
+      files[safeName] = projectFileSource(safeName, content);
+    }
+  }
+  await visit(root);
+  const size = Object.entries(files).reduce(
+    (total, [name, content]) => total + Buffer.byteLength(name) + projectFileBytes(name, content).length,
+    0,
+  );
+  if (Object.keys(files).length < 1 || Object.keys(files).length > MAX_FILES) {
+    throw new Error(`project must contain 1 to ${MAX_FILES} files`);
+  }
+  if (size > MAX_PROJECT_BYTES) throw new Error("project exceeds the 1 MiB source limit");
+  return files;
+}
+
+function binarySourcePath(name) {
+  const parts = name.split("/");
+  return (parts[0] === "assets" && parts.length >= 2 && BINARY_ASSET.has(extname(name).toLowerCase()))
+    || (parts[0] === "children" && parts.length === 2 && name.toLowerCase().endsWith(".mplg"));
+}
+
+function strictUtf8(content, name) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(content);
+  } catch {
+    throw new Error(`${name} must be UTF-8 text`);
+  }
+}
+
+function validateBinaryMagic(name, content) {
+  const extension = extname(name).toLowerCase();
+  const matches = extension === ".png"
+    ? content.length >= 8 && content.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex"))
+    : [".jpg", ".jpeg"].includes(extension)
+      ? content.length >= 3 && content[0] === 0xff && content[1] === 0xd8 && content[2] === 0xff
+      : extension === ".webp"
+        ? content.length >= 12 && content.subarray(0, 4).toString("ascii") === "RIFF" && content.subarray(8, 12).toString("ascii") === "WEBP"
+        : extension === ".gif"
+          ? ["GIF87a", "GIF89a"].includes(content.subarray(0, 6).toString("ascii"))
+          : extension === ".mplg"
+            ? content.length >= 4 && content.subarray(0, 4).equals(Buffer.from([0x50, 0x4b, 0x03, 0x04]))
+            : false;
+  if (!matches) throw new Error(`${name} does not match its declared binary file type`);
+}
+
+function projectFileSource(name, content) {
+  if (!Buffer.isBuffer(content)) throw new Error(`${name} must be file bytes`);
+  if (content.length > MAX_FILE_BYTES) throw new Error(`${name} exceeds the 512 KiB file limit`);
+  if (binarySourcePath(name)) {
+    validateBinaryMagic(name, content);
+    return `${BINARY_SOURCE_PREFIX}${content.toString("base64")}`;
+  }
+  const text = strictUtf8(content, name);
+  if (text.startsWith(BINARY_SOURCE_PREFIX)) {
+    throw new Error(`${name} cannot use the Morit binary envelope because it is a text source path`);
+  }
+  return text;
+}
+
+function projectFileBytes(name, content) {
+  if (typeof content !== "string") throw new Error(`${name} must contain source text or a Morit binary envelope`);
+  if (!content.startsWith(BINARY_SOURCE_PREFIX)) {
+    if (binarySourcePath(name)) throw new Error(`${name} must use the Morit binary envelope`);
+    const bytes = Buffer.from(content, "utf8");
+    if (bytes.length > MAX_FILE_BYTES) throw new Error(`${name} exceeds the 512 KiB file limit`);
+    return bytes;
+  }
+  if (!binarySourcePath(name)) {
+    throw new Error(`${name} cannot use the Morit binary envelope because it is a text source path`);
+  }
+  const encoded = content.slice(BINARY_SOURCE_PREFIX.length);
+  if (!encoded || encoded.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded)) {
+    throw new Error(`${name} contains an invalid Morit binary envelope`);
+  }
+  const bytes = Buffer.from(encoded, "base64");
+  if (bytes.toString("base64") !== encoded) throw new Error(`${name} contains a non-canonical Morit binary envelope`);
+  if (bytes.length > MAX_FILE_BYTES) throw new Error(`${name} exceeds the 512 KiB file limit`);
+  validateBinaryMagic(name, bytes);
+  return bytes;
+}
+
+function assertNonSensitiveSource(name) {
+  const base = name.split("/").at(-1).toLowerCase();
+  if (SAFE_ENV_TEMPLATES.has(base)) return;
+  if (base === ".env" || base.startsWith(".env.") || /\.(?:key|p12|pem|pfx)$/.test(base)) {
+    throw new Error(`project contains a sensitive file that cannot be packaged: ${name}`);
+  }
+}
+
+function verifyPackageContent(content) {
+  if (!content.length || content.length > MAX_PACKAGE_BYTES) {
+    throw new Error("package must be a non-empty file within Morit's 2 MiB upload limit");
+  }
+  const entries = readZip(content);
+  if (entries.size > MAX_FILES) throw new Error(`package has more than ${MAX_FILES} entries`);
+  let total = 0;
+  const sourceFiles = {};
+  for (const [name, value] of entries) {
+    const normalized = safeFilePath(name);
+    if (normalized !== name || !installablePackagePath(name)) {
+      throw new Error(`unsupported install package entry: ${name}`);
+    }
+    total += value.length;
+    if (total > MAX_PACKAGE_BYTES * 2) throw new Error("package expands beyond the 4 MiB safety limit");
+    if (name === "signature.json") continue;
+    sourceFiles[name] = projectFileSource(name, value);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(sourceFiles["manifest.json"] || "null");
+  } catch {
+    throw new Error("manifest.json must contain a JSON object");
+  }
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    throw new Error("manifest.json must contain a JSON object");
+  }
+  validateManifest(manifest, sourceFiles);
+  const verified = verifySignedEntries(entries);
+  return { ...verified, entries };
+}
+
+function installablePackagePath(name) {
+  if (["manifest.json", "signature.json", "README.md"].includes(name)) return true;
+  const parts = name.split("/");
+  if (parts[0] === "assets" && parts.length >= 2) return SAFE_ASSET.has(extname(name).toLowerCase());
+  if (parts[0] === "src" && parts.length >= 2) return name.toLowerCase().endsWith(".py");
+  return parts[0] === "children" && parts.length === 2 && name.toLowerCase().endsWith(".mplg");
+}
+
+function outputPath(value, fallback, suffix) {
+  let candidate = resolve(value || fallback);
+  if (!candidate.toLowerCase().endsWith(suffix)) {
+    if (extname(candidate)) throw new Error(`output file must end with ${suffix}`);
+    candidate += suffix;
+  }
+  return candidate;
+}
+
+async function signingKeyForPublisher(keyDirectory, publisher) {
+  await mkdir(keyDirectory, { recursive: true, mode: 0o700 });
+  const keyName = `${createHash("sha256").update(publisher).digest("hex")}.pem`;
+  const path = join(keyDirectory, keyName);
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    const generated = generateSigningKey();
+    try {
+      await writeFile(path, generated.privatePem, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    } catch (writeError) {
+      if (writeError.code === "EEXIST") return readFile(path, "utf8");
+      throw writeError;
+    }
+    await chmod(path, 0o600).catch(() => {});
+    return generated.privatePem;
+  }
+}
+
+function previewHtml(manifest) {
+  const serialized = JSON.stringify(manifest, null, 2).replaceAll("<", "\\u003c");
+  return Buffer.from(
+    `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escapeHtml(manifest.name)} preview</title><style>body{font:15px system-ui;margin:0;background:#f5f7fb;color:#182033}.wrap{max-width:960px;margin:auto;padding:32px}.card{background:white;border-radius:18px;padding:24px;box-shadow:0 8px 30px #17203a18}pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#101727;color:#e8eefc;padding:18px;border-radius:12px}</style></head><body><main class="wrap"><section class="card"><h1>${escapeHtml(manifest.name)}</h1><p>${escapeHtml(manifest.description || "")}</p><p>${manifest.capabilities.length} capabilities · ${manifest.ui_extensions.length} UI extensions</p><pre>${escapeHtml(serialized)}</pre></section></main></body></html>`,
+    "utf8",
+  );
+}
+
+function validateMetadata(pluginId, name, publisher, description) {
+  if (!PLUGIN_ID.test(pluginId) || pluginId.length > 120) throw new Error("plugin_id must be a reverse-domain lowercase identifier");
+  if (typeof name !== "string" || name.trim().length < 1 || name.trim().length > 80) throw new Error("name must contain 1 to 80 characters");
+  if (!PUBLISHER.test(publisher)) throw new Error("publisher contains unsupported characters");
+  if (typeof description !== "string" || description.length > 4000) throw new Error("description must not exceed 4000 characters");
+}
+
+function validateManifest(manifest, files) {
+  assertObject(manifest, "manifest");
+  rejectUnknownFields(manifest, MANIFEST_FIELDS, "manifest");
+  if (![1, 2].includes(manifest.schema_version)) throw new Error("manifest.schema_version must be 1 or 2");
+  validateMetadata(manifest.id, manifest.name, manifest.publisher, manifest.description || "");
+  if (manifest.icon !== undefined && manifest.icon !== null && (
+    typeof manifest.icon !== "string"
+    || !/^assets\/[A-Za-z0-9._/-]+\.(?:png|jpe?g|webp)$/i.test(manifest.icon)
+    || manifest.icon.split("/").includes("..")
+    || !(manifest.icon in files)
+  )) throw new Error("manifest.icon must reference a packaged PNG, JPEG, or WebP asset");
+  if (manifest.short_description !== undefined && (
+    typeof manifest.short_description !== "string" || manifest.short_description.length > 160
+  )) throw new Error("manifest.short_description must not exceed 160 characters");
+  if (manifest.category !== undefined && !/^[a-z][a-z0-9_-]{1,39}$/.test(String(manifest.category))) {
+    throw new Error("manifest.category is invalid");
+  }
+  const keywords = manifest.keywords || [];
+  if (!Array.isArray(keywords) || keywords.length > 12 || new Set(keywords).size !== keywords.length || keywords.some(
+    (value) => typeof value !== "string" || !value.trim() || value.length > 40
+  )) throw new Error("manifest.keywords must contain up to 12 unique short strings");
+  const developer = manifest.developer || {};
+  assertObject(developer, "manifest.developer");
+  rejectUnknownFields(developer, DEVELOPER_FIELDS, "manifest.developer");
+  if (developer.name !== undefined && (typeof developer.name !== "string" || developer.name.length > 120)) {
+    throw new Error("manifest.developer.name is invalid");
+  }
+  for (const [field, value] of [
+    ["developer.url", developer.url],
+    ["homepage_url", manifest.homepage_url],
+    ["privacy_policy_url", manifest.privacy_policy_url],
+  ]) {
+    if (value !== undefined && value !== null) validateHttpsUrl(value, `manifest.${field}`);
+  }
+  if (manifest.cloud_project_id !== undefined && manifest.cloud_project_id !== null && !isUuid(manifest.cloud_project_id)) {
+    throw new Error("manifest.cloud_project_id must be a UUID");
+  }
+  for (const field of ["version", "min_morit_version", "max_morit_version"]) {
+    if (!VERSION.test(String(manifest[field] || ""))) throw new Error(`manifest.${field} must be a semantic version`);
+  }
+  const requestedPermissions = validatePermissions(manifest.permissions || [], "manifest.permissions");
+  if (!["purge", "retain"].includes(manifest.data_policy)) throw new Error("manifest.data_policy must be purge or retain");
+  const capabilities = objectCollection(manifest.capabilities, "manifest.capabilities", 64);
+  const uiExtensions = objectCollection(manifest.ui_extensions, "manifest.ui_extensions", 64);
+  const credentials = objectCollection(manifest.credentials || [], "manifest.credentials", 16);
+  const slashCommands = objectCollection(manifest.slash_commands || [], "manifest.slash_commands", 32);
+  const connectors = objectCollection(manifest.connectors || [], "manifest.connectors", 32);
+  const dependencies = objectCollection(manifest.dependencies || [], "manifest.dependencies", 16);
+  const requiredSecrets = objectCollection(manifest.required_secrets || [], "manifest.required_secrets", 32);
+  if (!capabilities.length && !uiExtensions.length) throw new Error("plugin does not declare any extension");
+
+  const capabilityIds = new Set();
+  const sandboxEntrypoints = new Map();
+  for (const capability of capabilities) {
+    rejectUnknownFields(capability, CAPABILITY_FIELDS, "capability");
+    requireUniqueIdentifier(capability.id, capabilityIds, "capability");
+    capabilityIds.add(capability.id);
+    if (!CAPABILITY_KINDS.has(capability.kind)) throw new Error(`unknown capability kind: ${capability.kind}`);
+    requireText(capability.title, 80, `capability ${capability.id} title`);
+    requireText(capability.description, 500, `capability ${capability.id} description`);
+    const permissions = validatePermissions(capability.permissions || [], `capability ${capability.id} permissions`);
+    requireSubset(permissions, requestedPermissions, `capability ${capability.id} permissions`);
+    const timeout = capability.timeout_seconds ?? 10;
+    if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout < 0.1 || timeout > 30) {
+      throw new Error(`capability ${capability.id} timeout must be between 0.1 and 30 seconds`);
+    }
+    const runtime = capability.runtime || {};
+    assertObject(runtime, `capability ${capability.id} runtime`);
+    assertJsonSize(runtime, 32 * 1024, `capability ${capability.id} runtime`);
+    const adapter = runtime.adapter;
+    if ((["tool", "skill"].includes(capability.kind) || adapter) && !RUNTIME_ADAPTERS.has(adapter)) {
+      throw new Error(`unsupported runtime adapter: ${adapter || "missing"}`);
+    }
+    validateRuntime(capability, runtime, permissions, credentials, connectors, dependencies);
+    if (adapter === "sandbox_python") {
+      const entrypoint = normalizeEntrypointPath(runtime.entrypoint);
+      if (!entrypoint.startsWith("src/") || !entrypoint.endsWith(".py")) throw new Error("sandbox_python entrypoint must be src/*.py");
+      runtime.entrypoint = entrypoint;
+      sandboxEntrypoints.set(entrypoint, (sandboxEntrypoints.get(entrypoint) || 0) + 1);
+    }
+  }
+
+  const uiIds = new Set();
+  for (const extension of uiExtensions) {
+    rejectUnknownFields(extension, UI_EXTENSION_FIELDS, "UI extension");
+    requireUniqueIdentifier(extension.id, uiIds, "UI extension");
+    if (!UI_POINTS.has(extension.point)) throw new Error(`unknown UI extension point: ${extension.point}`);
+    requireText(extension.title, 80, `UI ${extension.id} title`);
+    const order = extension.order ?? 0;
+    if (!Number.isInteger(order) || order < -10000 || order > 10000) throw new Error(`UI ${extension.id} order is invalid`);
+    const permissions = validatePermissions(extension.permissions || [], `UI ${extension.id} permissions`);
+    requireSubset(permissions, requestedPermissions, `UI ${extension.id} permissions`);
+    assertObject(extension.config || {}, `UI ${extension.id} config`);
+    assertJsonSize(extension.config || {}, 32 * 1024, `UI ${extension.id} config`);
+  }
+  for (const extension of uiExtensions) validateUiConfig(extension, capabilities, uiIds);
+
+  const credentialIds = validateCredentials(credentials, requestedPermissions);
+  const secretIds = validateRequiredSecrets(requiredSecrets);
+  const connectorIds = validateConnectors(connectors, credentialIds, secretIds);
+  if ((requiredSecrets.length || connectors.some((value) => value.cloud_connection_id)) && !manifest.cloud_project_id) {
+    throw new Error("Cloud features require manifest.cloud_project_id");
+  }
+  validateDependencies(dependencies, manifest.id);
+  validateSlashCommands(slashCommands, capabilities);
+  validateRuntimeReferences(capabilities, connectors, connectorIds, dependencies);
+
+  const sourceFiles = Object.keys(files).filter((name) => name.startsWith("src/") && name.endsWith(".py"));
+  const duplicateEntrypoints = [...sandboxEntrypoints].filter(([, count]) => count !== 1).map(([name]) => name);
+  const missingEntrypoints = [...sandboxEntrypoints.keys()].filter((name) => !(name in files));
+  const undeclaredSources = sourceFiles.filter((name) => !sandboxEntrypoints.has(name));
+  if (duplicateEntrypoints.length || missingEntrypoints.length || undeclaredSources.length) {
+    const details = [
+      duplicateEntrypoints.length ? `duplicate: ${duplicateEntrypoints.join(", ")}` : "",
+      missingEntrypoints.length ? `not found: ${missingEntrypoints.join(", ")}` : "",
+      undeclaredSources.length ? `undeclared: ${undeclaredSources.join(", ")}` : "",
+    ].filter(Boolean).join("; ");
+    throw new Error(`every src/*.py file must be declared by exactly one sandbox_python entrypoint (${details})`);
+  }
+  const entries = new Map([["manifest.json", canonicalJson(manifest)]]);
+  for (const [name, content] of Object.entries(files)) {
+    if (name === "README.md") entries.set(name, projectFileBytes(name, content));
+    else if (name.startsWith("assets/") && SAFE_ASSET.has(extname(name).toLowerCase())) entries.set(name, projectFileBytes(name, content));
+    else if (name.startsWith("src/") && name.endsWith(".py")) entries.set(name, projectFileBytes(name, content));
+    else if (name.startsWith("children/") && name.endsWith(".mplg")) entries.set(name, projectFileBytes(name, content));
+  }
+  const declaredChildren = new Set(dependencies.filter((value) => value.package_path).map((value) => value.package_path));
+  const packagedChildren = new Set([...entries.keys()].filter((name) => name.startsWith("children/")));
+  if (!equalSets(declaredChildren, packagedChildren)) {
+    throw new Error("manifest dependencies must exactly match bundled children/*.mplg files");
+  }
+  if (entries.size > MAX_FILES) throw new Error(`package has more than ${MAX_FILES} entries`);
+  return entries;
+}
+
+function validatePermissions(values, label) {
+  if (!Array.isArray(values) || values.some((value) => typeof value !== "string" || !PERMISSIONS.has(value))) {
+    throw new Error(`${label} contains an unknown permission`);
+  }
+  return new Set(values);
+}
+
+function assertObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+}
+
+function rejectUnknownFields(value, allowed, label) {
+  assertObject(value, label);
+  const unknown = Object.keys(value).filter((name) => !allowed.has(name)).sort();
+  if (unknown.length) throw new Error(`${label} contains unknown fields: ${unknown.join(", ")}`);
+}
+
+function objectCollection(value, label, maximum) {
+  if (!Array.isArray(value) || value.length > maximum || value.some((item) => !item || typeof item !== "object" || Array.isArray(item))) {
+    throw new Error(`${label} must be an array of at most ${maximum} objects`);
+  }
+  return value;
+}
+
+function requireUniqueIdentifier(value, seen, label) {
+  if (!IDENTIFIER.test(String(value || "")) || seen.has(value)) {
+    throw new Error(`${label} ids must be unique valid identifiers`);
+  }
+  seen.add(value);
+}
+
+function requireText(value, maximum, label) {
+  if (typeof value !== "string" || !value.trim() || value.length > maximum) {
+    throw new Error(`${label} must contain 1 to ${maximum} characters`);
+  }
+}
+
+function assertJsonSize(value, maximum, label) {
+  validateJsonValue(value, 0, label);
+  if (Buffer.byteLength(JSON.stringify(value), "utf8") > maximum) {
+    throw new Error(`${label} is too large`);
+  }
+}
+
+function validateJsonValue(value, depth, label) {
+  if (depth > 12) throw new Error(`${label} is too deeply nested`);
+  if (value === null || typeof value === "boolean" || typeof value === "string") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${label} contains a non-finite number`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > 256) throw new Error(`${label} contains an oversized array`);
+    for (const item of value) validateJsonValue(item, depth + 1, label);
+    return;
+  }
+  if (value && typeof value === "object") {
+    if (Object.keys(value).length > 256) throw new Error(`${label} contains an oversized object`);
+    for (const [key, item] of Object.entries(value)) {
+      if (key.length > 256) throw new Error(`${label} contains an oversized key`);
+      validateJsonValue(item, depth + 1, label);
+    }
+    return;
+  }
+  throw new Error(`${label} must be JSON serializable`);
+}
+
+function requireSubset(values, allowed, label) {
+  const missing = [...values].filter((value) => !allowed.has(value));
+  if (missing.length) throw new Error(`${label} were not requested by the plugin: ${missing.join(", ")}`);
+}
+
+function validateCredentials(credentials, requestedPermissions) {
+  const ids = new Set();
+  for (const credential of credentials) {
+    rejectUnknownFields(credential, CREDENTIAL_FIELDS, "credential");
+    requireUniqueIdentifier(credential.id, ids, "credential");
+    requireText(credential.label, 80, `credential ${credential.id} label`);
+    requireText(credential.description, 500, `credential ${credential.id} description`);
+    const kind = credential.kind || "api_token";
+    if (!CREDENTIAL_KINDS.has(kind)) throw new Error(`credential ${credential.id} kind is invalid`);
+    for (const field of ["required", "allow_multiple"]) {
+      if (credential[field] !== undefined && typeof credential[field] !== "boolean") {
+        throw new Error(`credential ${credential.id} ${field} must be boolean`);
+      }
+    }
+    if (credential.oauth_provider !== undefined && credential.oauth_provider !== null) {
+      if (!IDENTIFIER.test(String(credential.oauth_provider)) || kind !== "oauth_access_token") {
+        throw new Error(`credential ${credential.id} OAuth provider is invalid`);
+      }
+    }
+  }
+  if (credentials.length && !requestedPermissions.has("credentials")) {
+    throw new Error("credential declarations require credentials permission");
+  }
+  return ids;
+}
+
+function validateRequiredSecrets(requiredSecrets) {
+  const ids = new Set();
+  for (const secret of requiredSecrets) {
+    rejectUnknownFields(secret, REQUIRED_SECRET_FIELDS, "required secret");
+    if (!/^[A-Z][A-Z0-9_]{1,79}$/.test(String(secret.id || "")) || ids.has(secret.id)) {
+      throw new Error("required secret ids must be unique environment identifiers");
+    }
+    ids.add(secret.id);
+    requireText(secret.label, 80, `required secret ${secret.id} label`);
+    if (secret.description !== undefined && (typeof secret.description !== "string" || secret.description.length > 500)) {
+      throw new Error(`required secret ${secret.id} description is invalid`);
+    }
+    if (secret.required !== undefined && typeof secret.required !== "boolean") {
+      throw new Error(`required secret ${secret.id} policy is invalid`);
+    }
+  }
+  return ids;
+}
+
+function validateConnectors(connectors, credentialIds, secretIds) {
+  const ids = new Set();
+  for (const connector of connectors) {
+    rejectUnknownFields(connector, CONNECTOR_FIELDS, "connector");
+    requireUniqueIdentifier(connector.id, ids, "connector");
+    if (!CONNECTOR_KINDS.has(connector.kind)) throw new Error(`connector ${connector.id} kind is invalid`);
+    requireText(connector.label, 80, `connector ${connector.id} label`);
+    requireText(connector.description, 500, `connector ${connector.id} description`);
+    const credentialId = connector.credential_id;
+    if (credentialId !== undefined && credentialId !== null && !credentialIds.has(credentialId)) {
+      throw new Error(`connector ${connector.id} references an unknown credential`);
+    }
+    const cloudConnectionId = connector.cloud_connection_id;
+    if (cloudConnectionId !== undefined && cloudConnectionId !== null && !IDENTIFIER.test(String(cloudConnectionId))) {
+      throw new Error(`connector ${connector.id} Cloud connection is invalid`);
+    }
+    const cloudSecretId = connector.cloud_secret_id;
+    if (cloudSecretId !== undefined && cloudSecretId !== null && !secretIds.has(cloudSecretId)) {
+      throw new Error(`connector ${connector.id} references an undeclared Cloud secret`);
+    }
+    if (connector.kind === "oauth" && !credentialId) {
+      throw new Error(`connector ${connector.id} requires a credential`);
+    }
+    if (connector.kind === "api_key" && !credentialId && !cloudSecretId) {
+      throw new Error(`connector ${connector.id} requires a user credential or Cloud secret`);
+    }
+    const endpoint = connector.endpoint;
+    if (["https", "mcp"].includes(connector.kind) && typeof endpoint !== "string") {
+      throw new Error(`connector ${connector.id} requires an HTTPS endpoint`);
+    }
+    if (endpoint !== undefined && endpoint !== null && (
+      typeof endpoint !== "string" || !endpoint.startsWith("https://") || endpoint.length > 2048 || /[\r\n@]/.test(endpoint)
+    )) throw new Error(`connector ${connector.id} endpoint is invalid`);
+    const timeout = connector.timeout_seconds ?? 10;
+    if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout < 0.1 || timeout > 30) {
+      throw new Error(`connector ${connector.id} timeout is invalid`);
+    }
+    const retry = connector.retry || {};
+    assertObject(retry, `connector ${connector.id} retry`);
+    rejectUnknownFields(retry, new Set(["max_attempts"]), `connector ${connector.id} retry`);
+    const attempts = retry.max_attempts ?? 2;
+    if (!Number.isInteger(attempts) || attempts < 1 || attempts > 4) throw new Error(`connector ${connector.id} retry count is invalid`);
+    const rate = connector.rate_limit || {};
+    assertObject(rate, `connector ${connector.id} rate_limit`);
+    rejectUnknownFields(rate, new Set(["requests", "period_seconds"]), `connector ${connector.id} rate_limit`);
+    const requests = rate.requests ?? 60;
+    const period = rate.period_seconds ?? 60;
+    if (!Number.isInteger(requests) || requests < 1 || requests > 10000 || !Number.isInteger(period) || period < 1 || period > 3600) {
+      throw new Error(`connector ${connector.id} rate limit is invalid`);
+    }
+  }
+  return ids;
+}
+
+function isUuid(value) {
+  return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+function validateHttpsUrl(value, label) {
+  if (typeof value !== "string" || value.length > 2048 || /[\r\n]/.test(value)) throw new Error(`${label} is invalid`);
+  let parsed;
+  try { parsed = new URL(value); } catch { throw new Error(`${label} is invalid`); }
+  if (parsed.protocol !== "https:" || parsed.username || parsed.password || !parsed.hostname) {
+    throw new Error(`${label} is invalid`);
+  }
+}
+
+function validateDependencies(dependencies, pluginId) {
+  const ids = new Set();
+  for (const dependency of dependencies) {
+    rejectUnknownFields(dependency, DEPENDENCY_FIELDS, "dependency");
+    requireUniqueIdentifier(dependency.id, ids, "dependency");
+    if (!IDENTIFIER.test(String(dependency.plugin_id || "")) || dependency.plugin_id === pluginId) {
+      throw new Error(`dependency ${dependency.id} plugin_id is invalid`);
+    }
+    if (dependency.required !== undefined && typeof dependency.required !== "boolean") throw new Error(`dependency ${dependency.id} required must be boolean`);
+    for (const [field, fallback] of [["min_version", "0.0.0"], ["max_version", "999.999.999"]]) {
+      if (!VERSION.test(String(dependency[field] || fallback))) throw new Error(`dependency ${dependency.id} ${field} is invalid`);
+    }
+    if (dependency.package_path !== undefined && dependency.package_path !== null) {
+      const path = String(dependency.package_path).replaceAll("\\", "/");
+      if (!/^children\/[A-Za-z0-9._-]+\.mplg$/.test(path) || path.length > 240) throw new Error(`dependency ${dependency.id} package_path is invalid`);
+      dependency.package_path = path;
+    }
+    const exposed = dependency.exposed_capabilities || [];
+    if (!Array.isArray(exposed) || exposed.length > 32 || new Set(exposed).size !== exposed.length || exposed.some((value) => !IDENTIFIER.test(String(value)))) {
+      throw new Error(`dependency ${dependency.id} exposed_capabilities are invalid`);
+    }
+  }
+}
+
+function validateSlashCommands(commands, capabilities) {
+  const ids = new Set();
+  const names = new Set();
+  const executable = new Set(capabilities.filter((value) => ["tool", "skill"].includes(value.kind)).map((value) => value.id));
+  for (const command of commands) {
+    rejectUnknownFields(command, SLASH_COMMAND_FIELDS, "slash command");
+    requireUniqueIdentifier(command.id, ids, "slash command");
+    if (!/^[a-z0-9][a-z0-9_-]{0,31}$/.test(String(command.command || "")) || names.has(command.command)) {
+      throw new Error(`slash command ${command.id} command is invalid or duplicate`);
+    }
+    names.add(command.command);
+    requireText(command.title, 80, `slash command ${command.id} title`);
+    requireText(command.description, 500, `slash command ${command.id} description`);
+    if (!executable.has(command.capability)) throw new Error(`slash command ${command.id} targets a non-executable capability`);
+    assertObject(command.argument_template || {}, `slash command ${command.id} argument_template`);
+    assertJsonSize(command.argument_template || {}, 16 * 1024, `slash command ${command.id} argument_template`);
+  }
+}
+
+function validateRuntime(capability, runtime, permissions, credentials, connectors, dependencies) {
+  const adapter = runtime.adapter;
+  const credentialIds = new Set(credentials.map((value) => value.id));
+  const dependencyById = new Map(dependencies.map((value) => [value.id, value]));
+  const connector = connectors.find((value) => value.id === runtime.connector_id);
+  const effectiveCredential = runtime.credential_id || connector?.credential_id;
+  const effectiveEndpoint = runtime.endpoint || connector?.endpoint;
+  if (adapter === "text_template" && (typeof runtime.template !== "string" || !runtime.template.trim() || runtime.template.length > 2000)) {
+    throw new Error("text_template requires a bounded template");
+  }
+  if (adapter === "http_json" && effectiveCredential && (
+    !credentialIds.has(effectiveCredential) || !permissions.has("network") || !permissions.has("credentials")
+  )) throw new Error("http_json requires a declared credential and network/credentials permissions");
+  if (adapter === "mcp_http") {
+    if (!permissions.has("network")) throw new Error("mcp_http requires network permission");
+    if (effectiveCredential && (!credentialIds.has(effectiveCredential) || !permissions.has("credentials"))) throw new Error("mcp_http requires a declared credential");
+    if (typeof effectiveEndpoint !== "string" || !effectiveEndpoint.startsWith("https://") || effectiveEndpoint.includes("@")) throw new Error("mcp_http requires a valid HTTPS endpoint");
+    if (!/^[A-Za-z0-9_.:/-]{1,160}$/.test(String(runtime.tool_name || ""))) throw new Error("mcp_http requires a valid tool name");
+  }
+  if (adapter === "child_plugin") {
+    const dependency = dependencyById.get(runtime.dependency_id);
+    if (!dependency || !(dependency.exposed_capabilities || []).includes(runtime.capability)) throw new Error("child_plugin requires an exposed dependency capability");
+  }
+  if (adapter === "calendar_store") {
+    if (!permissions.has("storage")) throw new Error("calendar_store requires storage permission");
+    if (runtime.operation === "reminder" && !permissions.has("notifications")) throw new Error("calendar reminder requires notifications permission");
+  }
+  if (adapter === "neis_school") {
+    if (!permissions.has("network") || !permissions.has("storage")) throw new Error("neis_school requires network and storage permissions");
+    if (!["setup", "lookup", "overview", "search", "reminder", "briefing"].includes(runtime.operation)) throw new Error("invalid neis_school operation");
+    if (["reminder", "briefing"].includes(runtime.operation) && !permissions.has("notifications")) throw new Error("NEIS reminder requires notifications permission");
+  }
+  if (capability.kind === "provider" && (runtime.role !== "search" || !adapter)) throw new Error("provider capabilities must declare a search runtime");
+  if (capability.kind === "background" && Object.keys(runtime).length) {
+    if (!Number.isInteger(runtime.interval_minutes) || runtime.interval_minutes < 15 || runtime.interval_minutes > 10080) {
+      throw new Error("background interval must be between 15 and 10080 minutes");
+    }
+  }
+}
+
+function validateRuntimeReferences(capabilities, connectors, connectorIds, dependencies) {
+  const connectorById = new Map(connectors.map((value) => [value.id, value]));
+  const dependencyIds = new Set(dependencies.map((value) => value.id));
+  for (const capability of capabilities) {
+    const runtime = capability.runtime || {};
+    if (runtime.connector_id) {
+      if (!connectorIds.has(runtime.connector_id)) throw new Error(`capability ${capability.id} references an unknown connector`);
+      if (!["http_json", "mcp_http"].includes(runtime.adapter)) throw new Error(`capability ${capability.id} connector is unsupported by its runtime`);
+      const connector = connectorById.get(runtime.connector_id);
+      if (connector.endpoint && runtime.endpoint !== undefined && runtime.endpoint !== connector.endpoint) throw new Error(`capability ${capability.id} connector endpoint conflicts with runtime`);
+      if (connector.credential_id && runtime.credential_id !== undefined && runtime.credential_id !== connector.credential_id) throw new Error(`capability ${capability.id} connector credential conflicts with runtime`);
+    }
+    if (runtime.adapter === "child_plugin" && !dependencyIds.has(runtime.dependency_id)) throw new Error(`capability ${capability.id} references an unknown dependency`);
+  }
+}
+
+function validateUiConfig(extension, capabilities, routeIds) {
+  const config = extension.config || {};
+  const executable = new Set(capabilities.filter((value) => ["tool", "skill", "provider", "notification"].includes(value.kind)).map((value) => value.id));
+  if (config.ui_schema === 2) {
+    if (config.placement !== undefined && !["card", "action"].includes(extension.point)) throw new Error("UI placement is only valid for home extensions");
+    validateUiRuntimeV2(config, executable, routeIds);
+    return;
+  }
+  const allowed = new Set(["icon", "description", "component", "sections", "actions", "capability", "label", "form"]);
+  rejectUnknownFields(config, allowed, `UI ${extension.id} config`);
+  if (config.icon !== undefined && !IDENTIFIER.test(String(config.icon))) throw new Error(`UI ${extension.id} icon is invalid`);
+  if (config.description !== undefined) requireText(config.description, 240, `UI ${extension.id} description`);
+  if (config.component !== undefined && !["action", "card", "settings_action"].includes(config.component)) throw new Error(`UI ${extension.id} component is invalid`);
+  const sections = config.sections || [];
+  if (!Array.isArray(sections) || sections.length > 12) throw new Error(`UI ${extension.id} sections are invalid`);
+  for (const section of sections) {
+    rejectUnknownFields(section, new Set(["heading", "body"]), `UI ${extension.id} section`);
+    if (section.heading !== undefined) requireText(section.heading, 80, `UI ${extension.id} section heading`);
+    requireText(section.body, 1200, `UI ${extension.id} section body`);
+  }
+  const actions = config.actions || [];
+  if (!Array.isArray(actions) || actions.length > 6) throw new Error(`UI ${extension.id} actions are invalid`);
+  const actionIds = new Set();
+  for (const action of actions) {
+    rejectUnknownFields(action, new Set(["id", "label", "capability", "style"]), `UI ${extension.id} action`);
+    requireUniqueIdentifier(action.id, actionIds, `UI ${extension.id} action`);
+    requireText(action.label, 60, `UI ${extension.id} action label`);
+    if (!executable.has(action.capability) || !["primary", "secondary"].includes(action.style || "secondary")) throw new Error(`UI ${extension.id} action is invalid`);
+  }
+  if ((config.capability === undefined) !== (config.label === undefined)) throw new Error(`UI ${extension.id} shorthand action is incomplete`);
+  if (config.capability !== undefined && (actions.length || !executable.has(config.capability))) throw new Error(`UI ${extension.id} shorthand action is invalid`);
+  if (config.label !== undefined) requireText(config.label, 60, `UI ${extension.id} shorthand label`);
+  if (config.form !== undefined) validateLegacyUiForm(config.form, executable, extension.id);
+}
+
+function validateLegacyUiForm(form, executable, extensionId) {
+  rejectUnknownFields(form, new Set(["submit_capability", "submit_label", "fields"]), `UI ${extensionId} form`);
+  if (!executable.has(form.submit_capability)) throw new Error(`UI ${extensionId} form targets an unknown capability`);
+  requireText(form.submit_label, 60, `UI ${extensionId} form submit label`);
+  if (!Array.isArray(form.fields) || form.fields.length < 1 || form.fields.length > 12) throw new Error(`UI ${extensionId} form fields are invalid`);
+  const ids = new Set();
+  for (const field of form.fields) {
+    rejectUnknownFields(field, new Set(["id", "type", "label", "description", "placeholder", "required", "min", "max", "options"]), `UI ${extensionId} form field`);
+    requireUniqueIdentifier(field.id, ids, `UI ${extensionId} form field`);
+    if (!["text", "integer", "select"].includes(field.type)) throw new Error(`UI ${extensionId} form field type is invalid`);
+    requireText(field.label, 80, `UI ${extensionId} form field label`);
+    if (field.description !== undefined) requireText(field.description, 240, `UI ${extensionId} form field description`);
+    if (field.placeholder !== undefined) requireText(field.placeholder, 120, `UI ${extensionId} form field placeholder`);
+    if (field.required !== undefined && typeof field.required !== "boolean") throw new Error(`UI ${extensionId} form field required must be boolean`);
+    if (field.type === "integer") {
+      for (const value of [field.min, field.max]) if (value !== undefined && (!Number.isInteger(value) || Math.abs(value) > 1000000)) throw new Error(`UI ${extensionId} integer range is invalid`);
+      if (Number.isInteger(field.min) && Number.isInteger(field.max) && field.min > field.max) throw new Error(`UI ${extensionId} integer range is invalid`);
+    } else if (field.min !== undefined || field.max !== undefined) throw new Error(`UI ${extensionId} range is only valid for integers`);
+    if (field.type === "select") {
+      if (!Array.isArray(field.options) || field.options.length < 1 || field.options.length > 50) throw new Error(`UI ${extensionId} select options are invalid`);
+      for (const option of field.options) {
+        if (!option || typeof option !== "object" || Array.isArray(option) || new Set(Object.keys(option)).size !== 2 || !("value" in option) || !("label" in option)) throw new Error(`UI ${extensionId} select option is invalid`);
+        requireText(option.value, 120, `UI ${extensionId} option value`);
+        requireText(option.label, 120, `UI ${extensionId} option label`);
+      }
+    } else if (field.options !== undefined) throw new Error(`UI ${extensionId} options are only valid for selects`);
+  }
+}
+
+function validateUiRuntimeV2(config, executable, routes) {
+  rejectUnknownFields(config, new Set(["ui_schema", "icon", "description", "placement", "initial_state", "data_sources", "view"]), "UI Runtime v2");
+  if (config.ui_schema !== 2) throw new Error("UI Runtime version must be 2");
+  optionalUiText(config.icon, 128, { identifier: true });
+  optionalUiText(config.description, 240);
+  if (config.placement !== undefined) {
+    const placement = config.placement;
+    rejectUnknownFields(placement, new Set(["section_id", "section_title", "section_order", "layout", "show_header"]), "UI placement");
+    optionalUiText(placement.section_id, 128, { required: true, identifier: true });
+    optionalUiText(placement.section_title, 80, { required: true });
+    const order = placement.section_order ?? 0;
+    if (!Number.isInteger(order) || order < -10000 || order > 10000) throw new Error("UI placement order is invalid");
+    if (!["stack", "horizontal", "grid"].includes(placement.layout || "stack")) throw new Error("UI placement layout is invalid");
+    if (typeof (placement.show_header ?? true) !== "boolean") throw new Error("UI placement show_header must be boolean");
+  }
+
+  const state = config.initial_state || {};
+  assertObject(state, "UI initial_state");
+  if (Object.keys(state).length > 32) throw new Error("UI initial_state is too large");
+  for (const [key, value] of Object.entries(state)) {
+    if (!UI_STATE_KEY.test(key)) throw new Error("UI initial_state contains an invalid key");
+    validateUiJson(value, 0);
+  }
+  const stateKeys = new Set(Object.keys(state));
+
+  const sources = config.data_sources || [];
+  if (!Array.isArray(sources) || sources.length > 8) throw new Error("UI data_sources are invalid");
+  const sourceIds = new Set();
+  for (const source of sources) {
+    rejectUnknownFields(source, new Set(["id", "capability", "trigger", "query", "arguments", "refresh_seconds"]), "UI data source");
+    if (!UI_IDENTIFIER.test(String(source.id || "")) || sourceIds.has(source.id) || !executable.has(source.capability) || !["load", "manual"].includes(source.trigger || "load")) {
+      throw new Error("UI data source reference is invalid");
+    }
+    sourceIds.add(source.id);
+  }
+  for (const source of sources) {
+    optionalUiTemplate(source.query, 2000);
+    validateTemplateReferences(source.query, stateKeys, sourceIds);
+    assertObject(source.arguments || {}, "UI data source arguments");
+    validateUiBindingValue(source.arguments || {}, 0, stateKeys, sourceIds);
+    if (source.refresh_seconds !== undefined && (!Number.isInteger(source.refresh_seconds) || source.refresh_seconds < 30 || source.refresh_seconds > 86400)) {
+      throw new Error("UI refresh must be between 30 and 86400 seconds");
+    }
+  }
+  assertObject(config.view, "UI Runtime v2 view");
+  validateUiNode(config.view, 0, { value: 0 }, executable, routes, sourceIds, stateKeys);
+}
+
+function validateUiNode(node, depth, counter, executable, routes, sources, stateKeys) {
+  const nodeKeys = new Set(["id", "type", "props", "children", "action", "visible_when"]);
+  rejectUnknownFields(node, nodeKeys, "UI component");
+  counter.value += 1;
+  if (depth > 12 || counter.value > 160) throw new Error("UI component tree is too large");
+  if (!new Set(contract.ui_nodes).has(node.type)) throw new Error(`unknown UI component type: ${node.type}`);
+  if (node.id !== undefined && !UI_IDENTIFIER.test(String(node.id))) throw new Error("UI component id is invalid");
+  const props = node.props || {};
+  validateUiProps(node.type, props, sources, stateKeys);
+  validateUiCondition(node.visible_when, stateKeys, sources);
+  validateUiAction(node.action, executable, routes, sources, stateKeys);
+  const children = node.children || [];
+  if (!Array.isArray(children) || children.length > 32) throw new Error("UI component children are invalid");
+  const leaves = new Set(["text", "icon", "divider", "spacer", "button", "chip", "metric", "progress", "calendar", "chart", "field", "select", "switch", "empty"]);
+  if (leaves.has(node.type) && children.length) throw new Error("leaf UI component cannot have children");
+  if (["list", "timeline"].includes(node.type) && children.length !== 1) throw new Error("list UI component requires one item template");
+  for (const child of children) {
+    assertObject(child, "UI component child");
+    validateUiNode(child, depth + 1, counter, executable, routes, sources, stateKeys);
+  }
+}
+
+function validateUiProps(nodeType, props, sources, stateKeys) {
+  const allowed = new Set([
+    "text", "title", "subtitle", "label", "supporting", "icon", "style", "tone", "align",
+    "max_lines", "spacing", "padding", "columns", "stack_at", "min_item_width", "size", "value",
+    "source", "empty_text", "limit", "state_key", "placeholder", "input_type", "options", "persist",
+    "selected", "dense", "chart_type", "x_key", "y_key", "date_key", "title_key", "show_legend", "full_width",
+  ]);
+  rejectUnknownFields(props, allowed, "UI component props");
+  for (const key of ["text", "title", "subtitle", "label", "supporting", "placeholder", "empty_text", "value"]) {
+    if (props[key] !== undefined) {
+      optionalUiTemplate(props[key], 1200, true);
+      validateTemplateReferences(props[key], stateKeys, sources);
+    }
+  }
+  for (const key of ["icon", "style", "tone", "align", "input_type", "chart_type", "x_key", "y_key", "date_key", "title_key"]) {
+    if (props[key] !== undefined) optionalUiText(props[key], 80, { required: true, identifier: true });
+  }
+  for (const key of ["max_lines", "spacing", "padding", "columns", "size", "limit"]) {
+    if (props[key] !== undefined && (!Number.isInteger(props[key]) || props[key] < 0 || props[key] > 100)) throw new Error(`UI numeric property ${key} is invalid`);
+  }
+  if (props.stack_at !== undefined && (!Number.isInteger(props.stack_at) || props.stack_at < 0 || props.stack_at > 1200)) throw new Error("UI stack_at is invalid");
+  if (props.min_item_width !== undefined && (!Number.isInteger(props.min_item_width) || props.min_item_width < 96 || props.min_item_width > 600)) throw new Error("UI min_item_width is invalid");
+  for (const key of ["persist", "selected", "dense", "show_legend", "full_width"]) if (props[key] !== undefined && typeof props[key] !== "boolean") throw new Error(`UI boolean property ${key} is invalid`);
+  if (["list", "timeline", "calendar", "chart"].includes(nodeType)) {
+    if (typeof props.source !== "string" || !UI_BINDING.test(props.source) || !props.source.startsWith("data.") || !sources.has(props.source.split(".")[1])) throw new Error("UI list source is invalid");
+  }
+  if (nodeType === "chart" && !["bar", "line", "donut"].includes(props.chart_type || "bar")) throw new Error("UI chart type is invalid");
+  if (nodeType === "calendar" && props.state_key !== undefined && !stateKeys.has(props.state_key)) throw new Error("UI calendar state is unknown");
+  if (["field", "select", "switch"].includes(nodeType) && !stateKeys.has(props.state_key)) throw new Error("UI state field is unknown");
+  if (props.options !== undefined) {
+    if (nodeType !== "select" || !Array.isArray(props.options) || props.options.length < 1 || props.options.length > 32) throw new Error("UI select options are invalid");
+    for (const option of props.options) {
+      if (!option || typeof option !== "object" || Array.isArray(option) || Object.keys(option).sort().join(",") !== "label,value") throw new Error("UI select option is invalid");
+      validateUiJson(option.value, 0);
+      optionalUiText(option.label, 80, { required: true });
+    }
+  }
+}
+
+function validateUiCondition(condition, stateKeys, sources) {
+  if (condition === undefined) return;
+  rejectUnknownFields(condition, new Set(["path", "equals", "not_equals", "exists"]), "UI visibility condition");
+  if (typeof condition.path !== "string" || !UI_BINDING.test(condition.path)) throw new Error("UI visibility path is invalid");
+  validateKnownBinding(condition.path, stateKeys, sources);
+  const checks = ["equals", "not_equals", "exists"].filter((key) => key in condition);
+  if (checks.length !== 1 || (checks[0] === "exists" && typeof condition.exists !== "boolean")) throw new Error("UI visibility comparison is invalid");
+  if (checks[0] !== "exists") validateUiJson(condition[checks[0]], 0);
+}
+
+function validateUiAction(action, executable, routes, sources, stateKeys) {
+  if (action === undefined) return;
+  rejectUnknownFields(action, new Set(["type", "capability", "query", "arguments", "store", "target", "source", "values", "persist"]), "UI action");
+  if (!["invoke", "navigate", "set_state", "refresh", "back"].includes(action.type)) throw new Error("UI action type is invalid");
+  if (action.type === "invoke") {
+    if (!executable.has(action.capability)) throw new Error("UI action targets a non-executable capability");
+    optionalUiTemplate(action.query, 2000);
+    validateTemplateReferences(action.query, stateKeys, sources);
+    assertObject(action.arguments || {}, "UI action arguments");
+    validateUiBindingValue(action.arguments || {}, 0, stateKeys, sources);
+    if (action.store !== undefined && !sources.has(action.store)) throw new Error("UI action store is unknown");
+  } else if (action.type === "navigate") {
+    if (!routes.has(action.target)) throw new Error("UI navigation target is unknown");
+  } else if (action.type === "set_state") {
+    assertObject(action.values, "UI state action values");
+    if (!Object.keys(action.values).length || Object.keys(action.values).some((key) => !stateKeys.has(key))) throw new Error("UI state action targets an unknown state key");
+    validateUiBindingValue(action.values, 0, stateKeys, sources);
+    if (typeof (action.persist ?? false) !== "boolean") throw new Error("UI state persistence flag is invalid");
+  } else if (action.type === "refresh") {
+    if (!sources.has(action.source)) throw new Error("UI refresh source is unknown");
+  } else if (Object.keys(action).length !== 1) throw new Error("back UI action cannot contain arguments");
+}
+
+function validateUiBindingValue(value, depth, stateKeys, sources) {
+  if (depth > 8) throw new Error("UI binding value is too deep");
+  if (typeof value === "string") {
+    optionalUiTemplate(value, 2000, true);
+    validateTemplateReferences(value, stateKeys, sources);
+  } else if (value === null || typeof value === "boolean" || typeof value === "number") {
+    validateUiJson(value, depth);
+  } else if (Array.isArray(value)) {
+    if (value.length > 64) throw new Error("UI binding list is too large");
+    for (const item of value) validateUiBindingValue(item, depth + 1, stateKeys, sources);
+  } else {
+    assertObject(value, "UI binding object");
+    if (Object.keys(value).length > 64 || Object.keys(value).some((key) => !UI_STATE_KEY.test(key))) throw new Error("UI binding object is invalid");
+    for (const item of Object.values(value)) validateUiBindingValue(item, depth + 1, stateKeys, sources);
+  }
+}
+
+function validateUiJson(value, depth) {
+  if (depth > 8) throw new Error("UI JSON value is too deep");
+  if (value === null || typeof value === "boolean" || Number.isInteger(value)) return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("UI number is non-finite");
+    return;
+  }
+  if (typeof value === "string") {
+    if (value.length > 2000) throw new Error("UI string is too long");
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > 64) throw new Error("UI list is too large");
+    for (const item of value) validateUiJson(item, depth + 1);
+    return;
+  }
+  assertObject(value, "UI JSON object");
+  if (Object.keys(value).length > 64 || Object.keys(value).some((key) => key.length > 64 || key.startsWith("_"))) throw new Error("UI JSON object is invalid");
+  for (const item of Object.values(value)) validateUiJson(item, depth + 1);
+}
+
+function optionalUiTemplate(value, maximum, required = false) {
+  if (value === undefined || value === null) {
+    if (required) throw new Error("UI text template is required");
+    return;
+  }
+  if (typeof value !== "string" || (required && !value.trim()) || value.length > maximum) throw new Error("UI text template is invalid");
+  for (const match of value.matchAll(UI_TEMPLATE_BINDING)) if (!UI_BINDING.test(match[1].trim())) throw new Error("UI template binding is invalid");
+}
+
+function validateTemplateReferences(value, stateKeys, sources) {
+  if (typeof value !== "string") return;
+  for (const match of value.matchAll(UI_TEMPLATE_BINDING)) validateKnownBinding(match[1].trim(), stateKeys, sources);
+}
+
+function validateKnownBinding(path, stateKeys, sources) {
+  const parts = path.split(".");
+  if (parts[0] === "state" && (parts.length < 2 || !stateKeys.has(parts[1]))) throw new Error("UI state binding is unknown");
+  if (parts[0] === "data" && (parts.length < 2 || !sources.has(parts[1]))) throw new Error("UI data binding is unknown");
+}
+
+function optionalUiText(value, maximum, { required = false, identifier = false } = {}) {
+  if (value === undefined || value === null) {
+    if (required) throw new Error("UI text is required");
+    return;
+  }
+  if (typeof value !== "string" || (required && !value.trim()) || value.length > maximum || (identifier && value && !UI_IDENTIFIER.test(value))) {
+    throw new Error("UI text is invalid");
+  }
+}
+
+function equalSets(left, right) {
+  return left.size === right.size && [...left].every((value) => right.has(value));
+}
+
+function compileManifest(files) {
+  let manifest;
+  try {
+    manifest = JSON.parse(files["manifest.json"]);
+  } catch {
+    throw new Error("manifest.json must contain a JSON object");
+  }
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) throw new Error("manifest.json must contain a JSON object");
+  manifest = structuredClone(manifest);
+  for (const [folder, [target, kind]] of FRAGMENTS) {
+    const fragments = Object.keys(files).filter((name) => name.startsWith(`${folder}/`) && name.endsWith(".json")).sort();
+    if (!Array.isArray(manifest[target])) manifest[target] = [];
+    for (const name of fragments) {
+      let value;
+      try {
+        value = JSON.parse(files[name]);
+      } catch {
+        throw new Error(`${name} must contain valid JSON`);
+      }
+      for (const item of Array.isArray(value) ? value : [value]) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error(`${name} must contain an object or array of objects`);
+        const fragment = kind ? { ...item, kind } : { ...item };
+        if (folder === "search") {
+          if (!fragment.runtime || typeof fragment.runtime !== "object" || Array.isArray(fragment.runtime)) {
+            fragment.runtime = {};
+          }
+          if (fragment.runtime.role === undefined) fragment.runtime.role = "search";
+        }
+        manifest[target].push(fragment);
+      }
+    }
+  }
+  if (Array.isArray(manifest.capabilities)) {
+    manifest.capabilities = manifest.capabilities.map((capability, index) => (
+      normalizeCapabilitySource(capability, `manifest.capabilities[${index}]`)
+    ));
+  }
+  return manifest;
+}
+
+function normalizeCapabilitySource(value, label) {
+  const capability = structuredClone(value);
+  const shorthand = CAPABILITY_RUNTIME_SHORTHAND.filter((name) => Object.hasOwn(capability, name));
+  if (capability.runtime !== undefined && (!capability.runtime || typeof capability.runtime !== "object" || Array.isArray(capability.runtime))) {
+    throw new Error(`${label}.runtime must be an object`);
+  }
+  if (shorthand.length) {
+    const runtime = { ...(capability.runtime || {}) };
+    for (const name of shorthand) {
+      if (Object.hasOwn(runtime, name) && !canonicalJson(runtime[name]).equals(canonicalJson(capability[name]))) {
+        throw new Error(`${label}.${name} conflicts with ${label}.runtime.${name}`);
+      }
+      runtime[name] = capability[name];
+      delete capability[name];
+    }
+    capability.runtime = runtime;
+  }
+  if (capability.runtime?.entrypoint !== undefined) {
+    capability.runtime.entrypoint = normalizeEntrypointPath(capability.runtime.entrypoint);
+  }
+  return capability;
+}
+
+async function readProjectFiles(root) {
+  const files = {};
+  async function visit(directory, prefix = "") {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) throw new Error("Project may not contain symbolic links");
+      const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) await visit(join(directory, entry.name), name);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const safeName = safeFilePath(name);
+      assertNonSensitiveSource(safeName);
+      const content = await readFile(join(directory, entry.name));
+      if (content.length > MAX_FILE_BYTES) throw new Error(`${safeName} exceeds the 512 KiB file limit`);
+      files[safeName] = projectFileSource(safeName, content);
+    }
+  }
+  await visit(root);
+  const size = Object.entries(files).reduce((total, [name, content]) => total + Buffer.byteLength(name) + projectFileBytes(name, content).length, 0);
+  if (Object.keys(files).length < 1 || Object.keys(files).length > MAX_FILES) throw new Error(`project must contain 1 to ${MAX_FILES} files`);
+  if (size > MAX_PROJECT_BYTES) throw new Error("project exceeds the 1 MiB source limit");
+  return files;
+}
+
+async function readDirectory(path) {
+  try {
+    return await readdir(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+function safeFilePath(value) {
+  if (typeof value !== "string" || value.length < 1 || value.length > 240 || value.includes("\\") || value.includes("\0")) throw new Error("file path is invalid");
+  const parts = value.split("/");
+  if (parts.some((part) => !part || part === "." || part === ".." || !SAFE_SEGMENT.test(part) || WINDOWS_RESERVED.test(part) || part.trim() !== part)) {
+    throw new Error("file path must be a safe relative POSIX path");
+  }
+  return parts.join("/");
+}
+
+function normalizeEntrypointPath(value) {
+  return safeFilePath(String(value || "").replaceAll("\\", "/"));
+}
+
+function safeProjectPath(value) {
+  if (typeof value !== "string" || !value.trim() || resolve(value) === resolve(".")) throw new Error("project path must be a non-empty relative path");
+  if (resolve(value) === value) throw new Error("project path must be relative to the configured workspace");
+  return value.replaceAll("\\", "/").split("/").map((part) => {
+    if (!part || part === "." || part === ".." || WINDOWS_RESERVED.test(part)) throw new Error("project path is unsafe");
+    return part;
+  }).join("/");
+}
+
+function artifactFileName(value, suffix, fallback) {
+  let candidate = String(value || fallback).trim();
+  if (!candidate || candidate === "." || candidate === ".." || candidate.includes("/") || candidate.includes("\\") || [...candidate].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)) {
+    throw new Error("artifact file_name must be a safe file name without a directory");
+  }
+  if (!candidate.toLowerCase().endsWith(suffix)) {
+    if (extname(candidate)) throw new Error(`artifact file_name must end with ${suffix}`);
+    candidate += suffix;
+  }
+  if (candidate.length > 180) throw new Error("artifact file_name is too long");
+  return candidate;
+}
+
+function projectDigest(files) {
+  const digest = createHash("sha256");
+  for (const name of Object.keys(files).sort()) {
+    digest.update(name);
+    digest.update("\0");
+    digest.update(files[name]);
+    digest.update("\0");
+  }
+  return digest.digest("hex");
+}
+
+function projectResult(project, root, files, includeFiles) {
+  return {
+    project_id: project.id,
+    plugin_id: project.plugin_id,
+    name: project.name,
+    description: project.description,
+    publisher: project.publisher,
+    revision: project.revision,
+    updated_at: project.updated_at,
+    workspace_path: root,
+    ...(includeFiles ? { files } : { file_names: Object.keys(files).sort() }),
+  };
+}
+
+function artifactResult(artifact, absolutePath, downloadFileName) {
+  return {
+    artifact_id: artifact.id,
+    project_id: artifact.project_id,
+    job_id: artifact.job_id,
+    kind: artifact.kind,
+    file_name: artifact.file_name,
+    download_file_name: downloadFileName,
+    mime_type: artifact.mime_type,
+    size_bytes: artifact.size_bytes,
+    sha256: artifact.sha256,
+    local_path: absolutePath,
+    download_url: pathToFileURL(absolutePath).href,
+    expires_in_seconds: null,
+  };
+}
+
+function jobResult(job) {
+  return {
+    job_id: job.id,
+    project_id: job.project_id,
+    file_name: job.file_name,
+    state: job.state,
+    progress: job.progress,
+    artifact_id: job.artifact_id,
+    error_code: job.error_code,
+    error_message: job.error_message,
+    created_at: job.created_at,
+    started_at: job.started_at,
+    finished_at: job.finished_at,
+    updated_at: job.updated_at,
+  };
+}
+
+function toPosix(value) {
+  return value.split(sep).join("/");
+}
+
+function escapeHtml(value) {
+  return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+
+export const internal = {
+  artifactFileName,
+  compileManifest,
+  normalizeEntrypointPath,
+  projectFileBytes,
+  safeFilePath,
+  signatureContract: SDK_CONTRACT.signature,
+  validateManifest,
+};