Runtime BOM and Dependency Versions

Learn which dependency versions your deployed backend uses and how gencow runtime keeps local development aligned.

Your deployed backend runs inside a Gencow runtime, which provides specific versions of its managed dependencies. The Runtime BOM (bill of materials) is the list of those packages and versions for a runtime release.

Locally installed copies of managed packages are not used by the deployed backend. The hosted runtime supplies its own versions. Installing or pinning a different managed version locally does not replace the hosted version.

For example, if your local installation has @gencow/core version 0.1.45 and the selected runtime provides 0.1.47, the deployed backend uses 0.1.47, not your local 0.1.45 copy. Local development may therefore behave differently. Aligning dependency versions helps reduce these differences; it does not guarantee identical application behavior.

This applies to managed backend dependencies, not every dependency in your app.

Local and hosted versions

• Local installations follow your project's declarations and lockfile. Local development runs on your computer; see Local Development.
• Cloud development (gencow dev) and hosted deployments use the runtime's BOM versions for managed packages. A declaration in your app does not select a different hosted version of a managed package.
• App-owned dependencies outside the managed set remain your application's responsibility.
• A deployment keeps its selected runtime release. New deploys and redeploys target the current published release; inspecting a newer BOM does not change an existing deployment.

Run gencow runtime show to see the managed package set and exact versions for your target. Do not assume that every package installed locally is managed by Gencow.

Managed packages

The managed dependency set includes:

• @gencow/core
• drizzle-orm
• better-auth
• hono
• zod
• postgres
• ai
• @ai-sdk/openai
• @ai-sdk/provider
• @ai-sdk/provider-utils

Versions are deliberately not listed here because they change between runtime releases. Use gencow runtime show to see the exact package versions provided by your target.

Reading the comparison table

The lockfile is not a measurement of the current node_modules directory. You can have an up-to-date lockfile and an incomplete or outdated installation.

Unknown means a trustworthy direct resolution is unavailable, not that versions match. Missing, unreadable, malformed or stale locks can cause this. Workspace links, aliases and other non-registry references may also be unverifiable. Read-only checks do not guess a parent workspace importer or install packages to fill in missing evidence.

Older versions are labeled by their major, minor, patch or prerelease difference. Newer local versions are labeled Newer than hosted runtime, not stale. Different build metadata can have the same SemVer precedence without being an exact version match.

Inspect and check

Run these commands from your local app directory, using a CLI authenticated to the intended Gencow target (gencow login if needed):

gencow runtime list
gencow runtime show
gencow runtime check

Commands default to the current published runtime. To inspect or align with another retained release, pass its ID from runtime list, for example gencow runtime show <releaseId>. Selecting a release for these commands does not redeploy your app or change its pinned runtime.

runtime check compares direct locked versions with the BOM, not whether a declaration range permits the hosted version. It reports any differences or explains when a resolution cannot be verified.

Matching latest resolutions pass and print one short line. A compatible range with an older locked version still differs. These checks do not install dependencies, query the package registry or change project files. If the authenticated target cannot provide the BOM, the CLI reports a diagnosis rather than substituting local package metadata.

For scripting and machine-readable output, see the CLI Reference.

Safely align local dependencies

gencow runtime sync --install automatically updates your local project and installs dependencies using the rules below. It does not update the hosted runtime, replace its managed packages or redeploy your app.

First preview the changes, then explicitly apply them:

gencow runtime sync --dry-run --install
gencow runtime sync --install
gencow runtime check

• Sync aligns ordinary managed declarations with the selected BOM and preserves existing latest and workspace: declarations. Unrelated dependencies are not BOM-pinned.
• --install explicitly refreshes selected managed latest resolutions and installs dependencies using the approved pinned pnpm version, even when no manifest edits are needed.
• A preserved latest follows the package registry's tag. It may resolve newer than the BOM; sync does not downgrade it merely to make runtime check pass. Review your intended declaration and target release if you need exact alignment.
• Without --install, sync does not perform the full dependency installation. It is not proof that node_modules is synchronized.
• --dry-run performs no file writes or package-manager operations.

Read any failure's retry precondition and next action. If dependency-file synchronization fails, the CLI restores the original manifest and lockfile; node_modules may be partially changed. Do not assume the installation is usable until a successful install completes. These local dependency commands do not change the hosted database or current serving app.

Doctor may plan or synchronize managed declarations depending on your configuration and flags. It does not implicitly perform the explicit latest refresh/install action, and its declaration/sync policy is separate from runtime check's lock-alignment result.

Why a deployment warning appears

For example, a project with an older locked version can show this warning. The versions and correlation ID below are illustrative; your output reflects your project and runtime.

  ⚠ ════════════════════════════════════════════════════════════
Managed dependency declaration policy warning. It does not block deployment
Package      | package.json | Locked | Runtime BOM | Locked vs BOM
-------------+--------------+--------+-------------+---------------
@gencow/core | 0.1.45       | 0.1.45 | 0.1.47      | Patch mismatch
Local development may behave differently from hosted deployments because dependency versions differ.
Aligning local dependencies with the Runtime BOM helps keep behavior consistent.
Preview: gencow runtime sync --dry-run --install
Refresh and install: gencow runtime sync --install (preserves latest declarations).
Inspect: gencow runtime show
Compare: gencow runtime check
Learn more: https://docs.gencow.com/docs/guides/runtime-bom
Correlation ID: deploy_example
════════════════════════════════════════════════════════════

Here, the local lockfile records an older @gencow/core version, while the deployed backend uses the version in Runtime BOM. Previewing and applying the suggested sync updates and installs your local dependency to align with the hosted version. The correlation ID identifies the deployment operation; it is not a dependency version.

The warning compares the app's declarations with the managed runtime and shows available lockfile observations. It recommends alignment because local development may behave differently from hosted deployments when dependency versions differ.

This warning does not rewrite local dependency files or decide the deployment's outcome. Normal deployment effects still apply: read the command's final success or failure result. Accepted BOM warnings with complete, matching lockfile observations are quiet. Unknown or incomplete warning details remain visible so missing evidence is not mistaken for a match. Keep the displayed correlation ID when investigating an operation.

When latest still has an older locked version

latest is a registry tag, not a continuously updating installation. For example:

1. You install @gencow/core when the registry's latest is 0.1.45. Your declaration stays latest, but pnpm-lock.yaml records the resolved version 0.1.45.
2. Time passes. A newer version is published. In this example, both the registry's latest tag and the current hosted Runtime BOM now point to 0.1.47.
3. Your lockfile still records 0.1.45. Keeping latest in package.json does not automatically refresh that resolution; an ordinary or frozen install can reuse it.

The warning then shows latest as the declaration and the older version as the resolution:

  ⚠ ════════════════════════════════════════════════════════════
Managed dependency declaration policy warning. It does not block deployment
Package      | package.json | Locked | Runtime BOM | Locked vs BOM
-------------+--------------+--------+-------------+---------------
@gencow/core | latest       | 0.1.45 | 0.1.47      | Patch mismatch
Local development may behave differently from hosted deployments because dependency versions differ.
Aligning local dependencies with the Runtime BOM helps keep behavior consistent.
Preview: gencow runtime sync --dry-run --install
Refresh and install: gencow runtime sync --install (preserves latest declarations).
Inspect: gencow runtime show
Compare: gencow runtime check
Learn more: https://docs.gencow.com/docs/guides/runtime-bom
Correlation ID: deploy_latest_example
════════════════════════════════════════════════════════════

Preview with gencow runtime sync --dry-run --install, then run gencow runtime sync --install to explicitly refresh the managed tag resolution and install dependencies. Your declaration stays latest; you do not need to replace it with an exact version just to refresh the lockfile.

The warning compares the lockfile with the Runtime BOM, not a live lookup of the registry's latest tag. They happen to match in this illustration, but the registry tag can be newer than the hosted BOM. The versions and correlation ID above are examples, not current values.

A warning is not a policy rejection

A policy rejection is different from this accepted warning. If the command reports MANAGED_BOM_MISMATCH and says deployment was blocked, review the incompatible declarations, state impact and next action. Do not repeatedly deploy unchanged declarations against the same runtime and rejection policy.

For additional deployment behavior, see Deployment.