@yansirplus/cli 0.5.17 → 0.5.19

package/dist/check/algorithmic/convergence-smoke-checks.mjs

@@ -1,3 +1,606 @@
+import ts from "typescript";
+
+const runtimeSurfaceClassValues = [
+  "stable-contract",
+  "first-party-host-substrate",
+  "generated-target-wiring",
+  "app-owned-integration-recipe",
+];
+const runtimeSurfaceClasses = new Set(runtimeSurfaceClassValues);
+const runtimeSubstrateClasses = new Set(["stable-contract", "first-party-host-substrate"]);
+const runtimeFirstPartyHostPrefixes = ["./cloudflare", "./in-memory", "./local", "./node"];
+const runtimeExtensionCategoryTokens = {
+  channel: ["channel", "slack", "discord", "teams", "telegram", "email", "webhook", "sms"],
+  sandbox: ["sandbox", "e2b", "container", "browser", "vm"],
+  database: [
+    "database",
+    "db",
+    "postgres",
+    "postgresql",
+    "mysql",
+    "sqlite",
+    "d1",
+    "sql",
+    "neon",
+    "prisma",
+    "drizzle",
+  ],
+  provider: ["provider", "llm", "ai", "openai", "anthropic", "gemini", "mistral", "cohere"],
+  observability: [
+    "observability",
+    "telemetry",
+    "otlp",
+    "trace",
+    "tracing",
+    "metrics",
+    "sentry",
+    "langfuse",
+    "log",
+    "logging",
+  ],
+};
+
+const isPlainRecord = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const runtimeSurfaceLabel = (subpath) =>
+  `@agent-os/runtime${subpath === "." ? "" : subpath.slice(1)}`;
+
+const runtimeExportSubpaths = (runtimePackageJson) =>
+  isPlainRecord(runtimePackageJson?.exports)
+    ? Object.keys(runtimePackageJson.exports)
+        .filter((subpath) => subpath !== "./package.json")
+        .sort((left, right) => left.localeCompare(right))
+    : [];
+
+const publicApiSections = ["Public exports", "Experimental exports", "Deprecated exports"];
+
+const markdownSectionBody = (source, heading) => {
+  const start = source.indexOf(`## ${heading}`);
+  if (start === -1) return "";
+  const bodyStart = start + heading.length + 3;
+  const rest = source.slice(bodyStart);
+  const next = rest.search(/^## /mu);
+  return next === -1 ? rest : rest.slice(0, next);
+};
+
+const runtimeApiSymbolsForSubpath = (source, subpath) =>
+  new Set(
+    publicApiSections
+      .flatMap((section) => [
+        ...markdownSectionBody(source, section).matchAll(/`([^`:]+):([^`]+)`/gu),
+      ])
+      .filter((match) => match[1] === subpath)
+      .map((match) => match[2]),
+  );
+
+const exportedDeclarationNames = (statement) => {
+  if (ts.isExportAssignment(statement)) {
+    return [statement.isExportEquals === true ? "export=" : "default"];
+  }
+  if (
+    statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) !== true
+  ) {
+    return [];
+  }
+  if (statement.modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword)) {
+    return ["default"];
+  }
+  if (
+    ts.isInterfaceDeclaration(statement) ||
+    ts.isTypeAliasDeclaration(statement) ||
+    ts.isClassDeclaration(statement) ||
+    ts.isFunctionDeclaration(statement) ||
+    ts.isEnumDeclaration(statement)
+  ) {
+    return statement.name === undefined ? [] : [statement.name.text];
+  }
+  if (ts.isVariableStatement(statement)) {
+    return statement.declarationList.declarations
+      .map((declaration) => (ts.isIdentifier(declaration.name) ? declaration.name.text : undefined))
+      .filter((name) => name !== undefined);
+  }
+  return [];
+};
+
+const explicitPublicBarrelSymbols = ({ source, file }) => {
+  const findings = [];
+  const names = new Set();
+  const sourceFile = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportDeclaration(statement)) {
+      if (statement.exportClause === undefined || ts.isNamespaceExport(statement.exportClause)) {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(
+          statement.getStart(sourceFile),
+        );
+        findings.push(
+          `${file}:${line + 1}:${character + 1}: runtime cloudflare public barrel must use explicit named exports; export-star syntax is forbidden`,
+        );
+        continue;
+      }
+
+      for (const element of statement.exportClause.elements) {
+        names.add(element.name.text);
+      }
+      continue;
+    }
+
+    for (const name of exportedDeclarationNames(statement)) names.add(name);
+  }
+
+  return { findings, names };
+};
+
+const cloudflarePublicBarrelFindings = ({
+  runtimeApiMarkdown,
+  cloudflarePublicBarrelSource,
+  cloudflarePublicBarrelPath,
+}) => {
+  if (typeof runtimeApiMarkdown !== "string" || typeof cloudflarePublicBarrelSource !== "string") {
+    return [];
+  }
+
+  const docsSymbols = runtimeApiSymbolsForSubpath(runtimeApiMarkdown, "./cloudflare");
+  const barrel = explicitPublicBarrelSymbols({
+    source: cloudflarePublicBarrelSource,
+    file: cloudflarePublicBarrelPath,
+  });
+  const findings = [...barrel.findings];
+
+  for (const symbol of [...barrel.names]
+    .map(String)
+    .sort((left, right) => left.localeCompare(right))) {
+    if (!docsSymbols.has(symbol)) {
+      findings.push(
+        `${cloudflarePublicBarrelPath}: exports ./cloudflare:${symbol}, but docs/api/runtime.md does not declare it`,
+      );
+    }
+  }
+  for (const symbol of [...docsSymbols].sort((left, right) => left.localeCompare(right))) {
+    if (!barrel.names.has(symbol)) {
+      findings.push(
+        `docs/api/runtime.md: declares ./cloudflare:${symbol}, but ${cloudflarePublicBarrelPath} does not export it`,
+      );
+    }
+  }
+
+  return findings;
+};
+
+const isFirstPartyRuntimeHostSubpath = (subpath) =>
+  runtimeFirstPartyHostPrefixes.some(
+    (prefix) => subpath === prefix || subpath.startsWith(`${prefix}/`),
+  );
+
+const runtimeExtensionCategoriesForSubpath = (subpath) => {
+  if (subpath === ".") return [];
+  const tokens = new Set(
+    subpath
+      .toLowerCase()
+      .split(/[^a-z0-9]+/u)
+      .filter(Boolean),
+  );
+  return Object.entries(runtimeExtensionCategoryTokens)
+    .filter(([, categoryTokens]) => categoryTokens.some((token) => tokens.has(token)))
+    .map(([category]) => category);
+};
+
+export const runtimePublicSurfaceFindings = ({
+  surfacePackage,
+  runtimePackageJson,
+  runtimeApiMarkdown,
+  cloudflarePublicBarrelSource,
+  cloudflarePublicBarrelPath = "packages/runtime/src/cloudflare/index.ts",
+}) => {
+  const findings = [];
+  if (!isPlainRecord(surfacePackage)) {
+    return ["docs/surface.json: @agent-os/runtime package is missing"];
+  }
+  if (!isPlainRecord(runtimePackageJson?.exports)) {
+    return ["packages/runtime/package.json: exports must be an object"];
+  }
+
+  const exportSubpaths = runtimeExportSubpaths(runtimePackageJson);
+  const exportSubpathSet = new Set(exportSubpaths);
+  const entrypoints = Array.isArray(surfacePackage.entrypoints) ? surfacePackage.entrypoints : [];
+  const entrypointsBySubpath = new Map();
+  for (const entrypoint of entrypoints) {
+    if (!isPlainRecord(entrypoint) || typeof entrypoint.subpath !== "string") continue;
+    entrypointsBySubpath.set(entrypoint.subpath, entrypoint);
+  }
+
+  for (const subpath of exportSubpaths) {
+    if (!entrypointsBySubpath.has(subpath)) {
+      findings.push(
+        `${runtimeSurfaceLabel(subpath)}: runtime package export is missing docs/surface.json entrypoint`,
+      );
+    }
+  }
+
+  for (const entrypoint of entrypoints) {
+    if (!isPlainRecord(entrypoint)) {
+      findings.push("@agent-os/runtime: docs/surface.json runtime entrypoint must be an object");
+      continue;
+    }
+    const subpath = entrypoint.subpath;
+    if (typeof subpath !== "string") {
+      findings.push("@agent-os/runtime: docs/surface.json runtime entrypoint missing subpath");
+      continue;
+    }
+    const label = runtimeSurfaceLabel(subpath);
+    if (!exportSubpathSet.has(subpath)) {
+      findings.push(`${label}: docs/surface.json entrypoint has no package.json export`);
+    }
+
+    const surfaceClass = entrypoint.surfaceClass;
+    if (typeof surfaceClass !== "string" || !runtimeSurfaceClasses.has(surfaceClass)) {
+      findings.push(
+        `${label}: runtime surfaceClass must be one of ${runtimeSurfaceClassValues.join(", ")}`,
+      );
+      continue;
+    }
+    if (surfaceClass === "app-owned-integration-recipe") {
+      findings.push(
+        `${label}: runtime public export cannot be classified app-owned-integration-recipe; keep app-owned integrations in blueprint recipes`,
+      );
+    }
+    if (surfaceClass === "first-party-host-substrate" && !isFirstPartyRuntimeHostSubpath(subpath)) {
+      findings.push(
+        `${label}: first-party-host-substrate is only valid for ${runtimeFirstPartyHostPrefixes.join(", ")} runtime subpaths`,
+      );
+    }
+    if (
+      surfaceClass === "generated-target-wiring" &&
+      !entrypoint.audiences?.includes("generated-only")
+    ) {
+      findings.push(`${label}: generated-target-wiring requires generated-only audience`);
+    }
+
+    const extensionCategories = runtimeExtensionCategoriesForSubpath(subpath);
+    if (extensionCategories.length > 0 && !runtimeSubstrateClasses.has(surfaceClass)) {
+      findings.push(
+        `${label}: ${extensionCategories.join("/")} integration-shaped runtime export must be classified as stable substrate, not ${surfaceClass}`,
+      );
+    }
+  }
+
+  findings.push(
+    ...cloudflarePublicBarrelFindings({
+      runtimeApiMarkdown,
+      cloudflarePublicBarrelSource,
+      cloudflarePublicBarrelPath,
+    }),
+  );
+
+  return findings.sort((left, right) => left.localeCompare(right));
+};
+
+const blueprintRecipeSchemaVersion = 1;
+const blueprintRecipeKinds = [
+  "channel",
+  "schedule",
+  "sandbox",
+  "database",
+  "provider",
+  "observability",
+];
+const blueprintRecipeKindSet = new Set(blueprintRecipeKinds);
+const blueprintRecipeActions = ["agentos add", "agentos update"];
+const blueprintLifecycleOwnershipKinds = new Set(["provider", "sandbox"]);
+const blueprintLifecycleOwnership = {
+  create: "app-or-generated-target",
+  reuse: "app-or-generated-target",
+  delete: "app-or-generated-target",
+  credentials: "app-owned-material",
+  network: "app-or-generated-target",
+};
+const blueprintLifecycleOwnershipAxes = Object.keys(blueprintLifecycleOwnership);
+const blueprintRecipePrimaryFiles = new Set([
+  "agent/channels/<name>.ts",
+  "agent/schedules/<id>.ts",
+  "agentos.config.jsonc",
+  "agent/agent.json",
+  "package.json",
+]);
+const blueprintRecipeGuidePath = "blueprints/UPGRADE.md";
+const blueprintRecipeIdPattern =
+  /^(channel|schedule|sandbox|database|provider|observability)\.[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const blueprintPrimaryFileMarkerPattern = /<!--\s*agentos:primary-file\s+path="([^"]+)"\s*-->/gu;
+const blueprintUpgradeMarkerPattern = /<!--\s*agentos:blueprint-upgrade\s+id="([^"]+)"\s*-->/gu;
+const blueprintForbiddenTokens = [
+  "target--node",
+  "createLocalWorkspaceEnv",
+  "createLocalAgentRuntime",
+  "packages/runtime",
+  "@agent-os/runtime/",
+  "@yansirplus/runtime/",
+  ".dev.vars",
+];
+const blueprintForbiddenPatterns = [
+  {
+    label: "source import statements",
+    pattern: /(?:^|\n)\s*import\s+[\s\S]*?\s+from\s+["'][^"']+["']/u,
+  },
+  {
+    label: "Cloudflare workspace lifecycle helper wiring",
+    pattern:
+      /\b(?:create|install)Cloudflare(?:Sandbox)?Workspace(?:EnvResolver|OperationProvider|JobProfile)\b/u,
+  },
+];
+const blueprintChannelBoundary = {
+  identity: "agent/channels/<name>.ts",
+  inboundRequest: "provider-native-raw-request",
+  authority: "verifier-derived-principal",
+  outboundSdk: "app-owned",
+  deduplication: "app-owned",
+  secretHandling: "redacted-before-submit-or-dispatch",
+};
+const blueprintChannelBoundaryAxes = Object.keys(blueprintChannelBoundary);
+const blueprintScheduleBoundary = {
+  identity: "agent/schedules/<id>.ts",
+  timeAuthority: "provider-scheduled-metadata",
+  fireIdentity: "stable-app-principal-schedule-id-utc-minute",
+  productIngress: "sessions-or-workflows",
+  externalSideEffects: "app-owned",
+  historyProjection: "schedule-fire-events-plus-linked-product-projections",
+};
+const blueprintScheduleBoundaryAxes = Object.keys(blueprintScheduleBoundary);
+
+const blueprintRecipeLabel = (source) => source.file ?? "blueprint recipe";
+
+const parseBlueprintRecipe = (source, findings) => {
+  const label = blueprintRecipeLabel(source);
+  const match = /^---json\n([\s\S]*?)\n---\n?([\s\S]*)$/u.exec(source.content);
+  if (match === null) {
+    findings.push(
+      `${label}: blueprint recipe must start with JSON frontmatter delimited by ---json and ---`,
+    );
+    return undefined;
+  }
+  let frontmatter;
+  try {
+    frontmatter = JSON.parse(match[1]);
+  } catch (error) {
+    findings.push(`${label}: JSON frontmatter is invalid: ${error.message}`);
+    return undefined;
+  }
+  if (!isPlainRecord(frontmatter)) {
+    findings.push(`${label}: JSON frontmatter must be an object`);
+    return undefined;
+  }
+  return { file: source.file, frontmatter, body: match[2] };
+};
+
+const collectMarkerValues = (content, pattern) => {
+  const values = [];
+  for (const match of content.matchAll(pattern)) values.push(match[1]);
+  return values;
+};
+
+const requiredBlueprintActionSet = new Set(blueprintRecipeActions);
+
+const validateBlueprintLifecycleOwnership = ({ label, kind, frontmatter, body, findings }) => {
+  if (!blueprintLifecycleOwnershipKinds.has(kind)) return;
+  const ownership = frontmatter.lifecycleOwnership;
+  if (!isPlainRecord(ownership)) {
+    findings.push(`${label}: ${kind} recipe requires lifecycleOwnership object`);
+    return;
+  }
+
+  const actualAxes = Object.keys(ownership).sort((left, right) => left.localeCompare(right));
+  const expectedAxes = [...blueprintLifecycleOwnershipAxes].sort((left, right) =>
+    left.localeCompare(right),
+  );
+  if (actualAxes.join(",") !== expectedAxes.join(",")) {
+    findings.push(`${label}: lifecycleOwnership axes must be exactly ${expectedAxes.join(", ")}`);
+  }
+
+  for (const axis of blueprintLifecycleOwnershipAxes) {
+    const expectedOwner = blueprintLifecycleOwnership[axis];
+    if (ownership[axis] !== expectedOwner) {
+      findings.push(`${label}: lifecycleOwnership.${axis} must be ${expectedOwner}`);
+    }
+  }
+
+  if (!body.includes("## Lifecycle Ownership")) {
+    findings.push(`${label}: ${kind} recipe body must contain ## Lifecycle Ownership`);
+  }
+};
+
+const validateBlueprintChannelBoundary = ({ label, kind, frontmatter, body, findings }) => {
+  if (kind !== "channel") return;
+  const boundary = frontmatter.channelBoundary;
+  if (!isPlainRecord(boundary)) {
+    findings.push(`${label}: channel recipe requires channelBoundary object`);
+    return;
+  }
+
+  const actualAxes = Object.keys(boundary).sort((left, right) => left.localeCompare(right));
+  const expectedAxes = [...blueprintChannelBoundaryAxes].sort((left, right) =>
+    left.localeCompare(right),
+  );
+  if (actualAxes.join(",") !== expectedAxes.join(",")) {
+    findings.push(`${label}: channelBoundary axes must be exactly ${expectedAxes.join(", ")}`);
+  }
+
+  for (const axis of blueprintChannelBoundaryAxes) {
+    const expectedValue = blueprintChannelBoundary[axis];
+    if (boundary[axis] !== expectedValue) {
+      findings.push(`${label}: channelBoundary.${axis} must be ${expectedValue}`);
+    }
+  }
+
+  if (!body.includes("## Channel Boundary")) {
+    findings.push(`${label}: channel recipe body must contain ## Channel Boundary`);
+  }
+};
+
+const validateBlueprintScheduleBoundary = ({ label, kind, frontmatter, body, findings }) => {
+  if (kind !== "schedule") return;
+  const boundary = frontmatter.scheduleBoundary;
+  if (!isPlainRecord(boundary)) {
+    findings.push(`${label}: schedule recipe requires scheduleBoundary object`);
+    return;
+  }
+
+  const actualAxes = Object.keys(boundary).sort((left, right) => left.localeCompare(right));
+  const expectedAxes = [...blueprintScheduleBoundaryAxes].sort((left, right) =>
+    left.localeCompare(right),
+  );
+  if (actualAxes.join(",") !== expectedAxes.join(",")) {
+    findings.push(`${label}: scheduleBoundary axes must be exactly ${expectedAxes.join(", ")}`);
+  }
+
+  for (const axis of blueprintScheduleBoundaryAxes) {
+    const expectedValue = blueprintScheduleBoundary[axis];
+    if (boundary[axis] !== expectedValue) {
+      findings.push(`${label}: scheduleBoundary.${axis} must be ${expectedValue}`);
+    }
+  }
+
+  if (!body.includes("## Schedule Boundary")) {
+    findings.push(`${label}: schedule recipe body must contain ## Schedule Boundary`);
+  }
+};
+
+const validateBlueprintRecipe = (recipe, findings) => {
+  const { file, frontmatter, body } = recipe;
+  const id = frontmatter.id;
+  const kind = frontmatter.kind;
+  const title = frontmatter.title;
+  const summary = frontmatter.summary;
+  const primaryFile = frontmatter.primaryFile;
+  const appliesTo = frontmatter.appliesTo;
+  const upgradeGuide = frontmatter.upgradeGuide;
+  const label = file;
+
+  if (frontmatter.schemaVersion !== blueprintRecipeSchemaVersion) {
+    findings.push(`${label}: schemaVersion must be ${blueprintRecipeSchemaVersion}`);
+  }
+  if (typeof id !== "string" || !blueprintRecipeIdPattern.test(id)) {
+    findings.push(`${label}: id must be <kind>.<slug> for ${blueprintRecipeKinds.join(", ")}`);
+  }
+  if (typeof kind !== "string" || !blueprintRecipeKindSet.has(kind)) {
+    findings.push(`${label}: kind must be one of ${blueprintRecipeKinds.join(", ")}`);
+  }
+  if (typeof id === "string" && typeof kind === "string" && id.split(".")[0] !== kind) {
+    findings.push(`${label}: id prefix must match kind`);
+  }
+  if (typeof title !== "string" || title.trim().length === 0) {
+    findings.push(`${label}: title must be a non-empty string`);
+  }
+  if (typeof summary !== "string" || summary.trim().length === 0) {
+    findings.push(`${label}: summary must be a non-empty string`);
+  }
+  if (typeof primaryFile !== "string" || !blueprintRecipePrimaryFiles.has(primaryFile)) {
+    findings.push(
+      `${label}: primaryFile must be one of ${[...blueprintRecipePrimaryFiles].join(", ")}`,
+    );
+  }
+  if (
+    !Array.isArray(appliesTo) ||
+    appliesTo.length !== requiredBlueprintActionSet.size ||
+    new Set(appliesTo).size !== requiredBlueprintActionSet.size ||
+    appliesTo.some((action) => !requiredBlueprintActionSet.has(action))
+  ) {
+    findings.push(`${label}: appliesTo must be exactly ${blueprintRecipeActions.join(", ")}`);
+  }
+  if (upgradeGuide !== blueprintRecipeGuidePath) {
+    findings.push(`${label}: upgradeGuide must be ${blueprintRecipeGuidePath}`);
+  }
+  if (typeof id === "string" && blueprintRecipeIdPattern.test(id)) {
+    const [idKind, slug] = id.split(".");
+    const expectedPath = `blueprints/recipes/${idKind}/${slug}.md`;
+    if (file !== expectedPath) findings.push(`${label}: recipe path must be ${expectedPath}`);
+  }
+  validateBlueprintLifecycleOwnership({ label, kind, frontmatter, body, findings });
+  validateBlueprintChannelBoundary({ label, kind, frontmatter, body, findings });
+  validateBlueprintScheduleBoundary({ label, kind, frontmatter, body, findings });
+
+  if (typeof title === "string" && !body.includes(`# ${title}`)) {
+    findings.push(`${label}: body must contain # ${title}`);
+  }
+  for (const heading of ["## Boundary", "## Steps", "## Upgrade Guide"]) {
+    if (!body.includes(heading)) findings.push(`${label}: body must contain ${heading}`);
+  }
+
+  const primaryMarkers = collectMarkerValues(body, blueprintPrimaryFileMarkerPattern);
+  if (primaryMarkers.length !== 1) {
+    findings.push(`${label}: body must contain exactly one agentos:primary-file marker`);
+  } else if (primaryMarkers[0] !== primaryFile) {
+    findings.push(`${label}: primary-file marker must match frontmatter.primaryFile`);
+  }
+
+  for (const token of blueprintForbiddenTokens) {
+    if (body.includes(token))
+      findings.push(`${label}: blueprint recipe must not reference ${token}`);
+  }
+  for (const { label: patternLabel, pattern } of blueprintForbiddenPatterns) {
+    if (pattern.test(body)) {
+      findings.push(`${label}: blueprint recipe must not contain ${patternLabel}`);
+    }
+  }
+};
+
+export const blueprintRecipeFindingsForSources = ({ recipeSources, upgradeGuideContent }) => {
+  const findings = [];
+  if (!Array.isArray(recipeSources) || recipeSources.length === 0) {
+    findings.push("blueprints/recipes: at least one blueprint recipe is required");
+    return findings;
+  }
+  if (typeof upgradeGuideContent !== "string") {
+    findings.push(`${blueprintRecipeGuidePath}: upgrade guide is missing`);
+    return findings;
+  }
+
+  const recipes = [];
+  for (const source of recipeSources) {
+    if (
+      !isPlainRecord(source) ||
+      typeof source.file !== "string" ||
+      typeof source.content !== "string"
+    ) {
+      findings.push("blueprint recipe source must include file and content");
+      continue;
+    }
+    const recipe = parseBlueprintRecipe(source, findings);
+    if (recipe !== undefined) recipes.push(recipe);
+  }
+
+  /** @type {Set<string>} */
+  const recipeIds = new Set();
+  for (const recipe of recipes) {
+    validateBlueprintRecipe(recipe, findings);
+    const id = recipe.frontmatter.id;
+    if (typeof id !== "string") continue;
+    if (recipeIds.has(id)) findings.push(`${recipe.file}: duplicate blueprint recipe id ${id}`);
+    recipeIds.add(id);
+  }
+
+  const guideIds = collectMarkerValues(upgradeGuideContent, blueprintUpgradeMarkerPattern);
+  const guideIdCounts = new Map();
+  for (const id of guideIds) guideIdCounts.set(id, (guideIdCounts.get(id) ?? 0) + 1);
+  for (const [id, count] of guideIdCounts) {
+    if (count !== 1) findings.push(`${blueprintRecipeGuidePath}: duplicate upgrade marker ${id}`);
+    if (!recipeIds.has(id))
+      findings.push(`${blueprintRecipeGuidePath}: unknown upgrade marker ${id}`);
+  }
+  for (const id of recipeIds) {
+    if (!guideIdCounts.has(id)) {
+      findings.push(`${blueprintRecipeGuidePath}: missing upgrade marker ${id}`);
+    }
+  }
+
+  return findings.sort((left, right) => left.localeCompare(right));
+};
+
 export const createConvergenceSmokeChecks = ({
   fs,
   os,
@@ -16,6 +619,7 @@ export const createConvergenceSmokeChecks = ({
   checkGeneratedStaticTargetLinking,
   checkSpikeHygiene,
   moduleBucketRegistry,
+  workspacePackagePatterns,
   workspacePackageRecords,
   consumerFacingSpecifierFailures,
   packageUnitPublicSpecifiers,
@@ -34,10 +638,25 @@ export const createConvergenceSmokeChecks = ({
   const checkConvergenceBoundary = () => {
     checkClientBoundaries();
     checkGeneratedStaticTargetLinking();
+    checkBlueprintRecipes();
     checkSpikeHygiene();
     console.log("convergence boundary passed");
   };
 
+  const checkBlueprintRecipes = () => {
+    const recipeRoot = "blueprints/recipes";
+    const recipeFiles = walk(recipeRoot).filter((file) => file.endsWith(".md"));
+    const upgradeGuidePath = path.join(repoRoot, blueprintRecipeGuidePath);
+    const failures = blueprintRecipeFindingsForSources({
+      recipeSources: recipeFiles.map((file) => ({ file, content: read(file) })),
+      upgradeGuideContent: fs.existsSync(upgradeGuidePath)
+        ? read(blueprintRecipeGuidePath)
+        : undefined,
+    });
+    failIfAny("blueprint recipes", failures);
+    console.log(`blueprint recipes covered ${recipeFiles.length} recipe(s)`);
+  };
+
   const publicExportNames = (apiSource) =>
     new Set([
       ...manifestNames(path.join(repoRoot, apiSource), "Public exports"),
@@ -71,6 +690,14 @@ export const createConvergenceSmokeChecks = ({
 
     const surfacePackages = readJson("docs/surface.json").packages ?? [];
     const surfaceByName = new Map(surfacePackages.map((pkg) => [pkg.name, pkg]));
+    failures.push(
+      ...runtimePublicSurfaceFindings({
+        surfacePackage: surfaceByName.get("@agent-os/runtime"),
+        runtimePackageJson: readJson("packages/runtime/package.json"),
+        runtimeApiMarkdown: read("docs/api/runtime.md"),
+        cloudflarePublicBarrelSource: read("packages/runtime/src/cloudflare/index.ts"),
+      }),
+    );
     const retiredPackages = new Set(manifest.retiredPackages ?? []);
     for (const record of workspacePackageRecords()) {
       if (retiredPackages.has(record.name)) {
@@ -159,6 +786,7 @@ export const createConvergenceSmokeChecks = ({
   const checkCliSurface = () => {
     const failures = [];
     const rootPackage = readJson("package.json");
+    const workspacePatterns = workspacePackagePatterns();
     const records = workspacePackageRecords();
     const packageNames = new Set(records.map((record) => record.name));
     const surfacePackages = readJson("docs/surface.json").packages ?? [];
@@ -171,11 +799,8 @@ export const createConvergenceSmokeChecks = ({
       "tooling/ops-htmx/package.json",
     ];
 
-    if (
-      !Array.isArray(rootPackage.workspaces) ||
-      !rootPackage.workspaces.includes("packages/cli")
-    ) {
-      failures.push("package.json: workspaces must include packages/cli");
+    if (!workspacePatterns.includes("packages/cli")) {
+      failures.push("pnpm-workspace.yaml: packages must include packages/cli");
     }
     if (rootPackage.scripts?.agentos !== "node packages/cli/src/main.mjs") {
       failures.push("package.json: scripts.agentos must execute packages/cli/src/main.mjs");
@@ -581,8 +1206,28 @@ export const createConvergenceSmokeChecks = ({
         "const bindings = defineAgentBindings({ handlers: {} });",
         "if (!ABORT || !bindings || !LLM_WIRE_DESCRIPTOR_VERSION || !TRACE_CONTEXT_VERSION || !DISPATCH_INBOUND_ACCEPTED) throw new Error('missing core import');",
       ].join("\n");
+      const entryPath = path.join(dir, "entry.ts");
+      const outFile = path.join(dir, "entry.mjs");
+      fs.writeFileSync(entryPath, code);
       try {
-        execFileSync("bun", ["--eval", code], {
+        execFileSync(
+          "pnpm",
+          [
+            "exec",
+            "esbuild",
+            entryPath,
+            "--bundle",
+            "--platform=node",
+            "--format=esm",
+            `--outfile=${outFile}`,
+          ],
+          {
+            cwd: repoRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+          },
+        );
+        execFileSync(process.execPath, [outFile], {
           cwd: dir,
           encoding: "utf8",
           stdio: ["ignore", "pipe", "pipe"],
@@ -604,5 +1249,6 @@ export const createConvergenceSmokeChecks = ({
     checkCliSurface,
     checkConsumerImports,
     checkDogfoodSmoke,
+    checkBlueprintRecipes,
   };
 };