{"record":{"id":"323d1814a8f43867","repo":"halo-dev/halo","slug":"root-snapshot-version-must-be-stable-semver","errorCode":null,"errorMessage":"${root} snapshot version must be stable semver.","messagePattern":"(.+?) snapshot version must be stable semver\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"ui/packages/ui-plugin-bundler-kit/src/runtime-snapshot.ts","lineNumber":186,"sourceCode":"    newerThanHost: compare(resolvedVersion, parsedHostVersion) > 0,\n    differentMajor: resolvedVersion.major !== parsedHostVersion.major,\n  };\n}\n\nexport function isSharedPackageRoot(value: string): value is SharedPackageRoot {\n  return sharedPackageRootSet.has(value);\n}\n\nfunction validateSnapshotEntry(\n  root: SharedPackageRoot,\n  value: unknown\n): HostRuntimeSnapshotEntry {\n  if (\n    !isRecord(value) ||\n    typeof value.version !== \"string\" ||\n    !parseStableVersion(value.version)\n  ) {\n    throw new Error(`${root} snapshot version must be stable semver.`);\n  }\n  if (\n    !Array.isArray(value.exports) ||\n    value.exports.length === 0 ||\n    value.exports.some(\n      (exportName) =>\n        typeof exportName !== \"string\" || !/^[$A-Z_a-z][$\\w]*$/.test(exportName)\n    ) ||\n    new Set(value.exports).size !== value.exports.length\n  ) {\n    throw new Error(`${root} snapshot exports must be unique identifiers.`);\n  }\n  if (\n    !isRecord(value.runtime) ||\n    typeof value.runtime.bridge !== \"string\" ||\n    !/^[a-z0-9-]+$/.test(value.runtime.bridge) ||\n    typeof value.runtime.global !== \"string\" ||\n    !/^[$A-Z_a-z][$\\w]*$/.test(value.runtime.global) ||","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/halo-dev/halo/blob/d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8/ui/packages/ui-plugin-bundler-kit/src/runtime-snapshot.ts#L168-L204","documentation":"Thrown by validateSnapshotEntry when a host runtime snapshot entry's 'version' field is missing, non-string, or not a stable (non-prerelease) semver. These snapshots are the built-in truth tables shipped inside @halo-dev/ui-plugin-bundler-kit (rawHaloHostRuntimeSnapshots, frozen at module load via validateHaloHostRuntimeSnapshot). The check enforces that every snapshot pins a concrete released Halo dependency version so ESM builds compare against real targets.","triggerScenarios":"Fires at import time of runtime-snapshot.ts when HALO_HOST_RUNTIME_SNAPSHOTS is constructed, if any entry in the bundled runtime-snapshots data has a version like '2.0.0-beta.1', 'latest', '' , or a non-string. Not user-data driven; it guards the kit's own data file.","commonSituations":"A maintainer edits runtime-snapshots source data and accidentally saves a prerelease tag or a malformed version; a bad merge/rebase into the bundler kit snapshots; a downstream fork that regenerates snapshots without stripping prerelease suffixes.","solutions":["If you maintain a fork of the kit, audit runtime-snapshots.ts and ensure every entry.version is a stable MAJOR.MINOR.PATCH (no -alpha/-rc/-beta).","Update @halo-dev/ui-plugin-bundler-kit to the upstream release whose snapshots passed validation.","Reproduce the failing entry by importing HALO_HOST_RUNTIME_SNAPSHOTS in a scratch script and patch the offending version in the snapshot source."],"exampleFix":"// before (runtime-snapshots data)\n{ haloVersion: \"2.26.0\", packages: { vue: { version: \"3.4.0-rc.1\", ... } } }\n\n// after\n{ haloVersion: \"2.26.0\", packages: { vue: { version: \"3.4.0\", ... } } }","handlingStrategy":"validation","validationCode":"import { parse } from \"semver\";\nfunction assertStableSnapshotVersion(root: string, version: unknown) {\n  const v = typeof version === \"string\" ? parse(version) : null;\n  if (!v || v.prerelease.length > 0) {\n    throw new Error(`${root} snapshot version must be stable semver, got ${String(version)}.`);\n  }\n}","typeGuard":"import { parse } from \"semver\";\nfunction isStableVersion(value: unknown): value is string {\n  if (typeof value !== \"string\") return false;\n  const v = parse(value);\n  return v !== null && v.prerelease.length === 0;\n}","tryCatchPattern":null,"preventionTips":["Treat runtime snapshot data files as version-controlled artifacts; never hand-edit a version to a prerelease.","Run the snapshot validation in a unit test (the kit already calls validateHaloHostRuntimeSnapshot at import).","Upgrade the bundler kit rather than patching snapshot versions locally."],"tags":["build","esm","snapshot","semver","bundler-kit"],"backgroundTag":null,"analyzedSha":"d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8","analyzedAt":"2026-08-14T00:18:38.915Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}