# ZAKON — Lockfile Portability in Production Linux Containers

# ZAKON — Lockfile Portability in Production Linux Containers

**Status:** ACTIVE
**Created:** 2026-07-28
**Origin:** Bilko MC #9616 / #9619 — 4-iteration CI repair exposed macOS-generated lockfile drift in Linux Docker builds.
**Applies to:** Bilko, Drop, Tok, and any ALAI Node workspace deployed in Linux containers.

## Rule

Every deployable Node lockfile (`package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`) for Bilko/Drop/Tok MUST be regenerated inside the same Linux base image used by the production Dockerfile before it is committed for a container deploy.

Do not trust a lockfile generated on macOS for a Linux container build. Optional native dependencies are platform-specific.

## Required Procedure

1. Identify the production Dockerfile and its Node base image.
2. Run lockfile regeneration inside that exact base image or a materially identical Linux variant.
3. Remove stale host artifacts before install.
4. Commit the regenerated lockfile with evidence that Linux optional packages are present.

Example for Bilko web (`apps/web/Dockerfile` currently uses the Node production build context):

```bash
docker run --rm -v "$PWD:/work" -w /work node:20-bookworm-slim bash -c \
  "rm -rf node_modules package-lock.json && npm install --workspaces --legacy-peer-deps"
```

If the Dockerfile base image changes, the command must change with it.

## Acceptance Evidence

A task/PR that changes or relies on a Node lockfile for container deploy must include:

- Docker base image used for regeneration.
- Exact regeneration command.
- Clean command exit code.
- Lockfile diff showing Linux platform optional dependencies when applicable.
- Local Docker build success before remote CI dispatch; see `~/system/rules/zakon-local-docker-build.md`.

## Blockers

Block the task before push/dispatch if:

- The lockfile was regenerated on macOS only.
- The base image used for regeneration does not match the production Dockerfile.
- The lockfile diff removes Linux optional/native packages without a documented reason.
- The agent cannot state where the production Dockerfile is.

## Why

MC #9619 found that darwin-generated lockfiles omitted Linux optional packages such as native watcher/bundler variants. Cloud/CI builds then failed inside Linux containers even though local macOS installs passed.

## Related Standards

- `~/system/rules/zakon-ci-stub-types-contract.md`
- `~/system/rules/zakon-local-docker-build.md`
- Bilko `BUILD-BLUEPRINT.md` §11 and §14
- Bilko `DEPLOY-MAP.md` historical GCP gotchas