zlh-grind/CONSTRAINTS.md

Constraints – zlh-grind

This repository is strictly for decision tracking, constraints, and ground rules.
It is not an implementation repo.

---

Execution model constraints

• zlh-agent executes installer logic as embedded scripts.
• Embedded scripts must not rely on filesystem-relative paths ($0, dirname, etc.).
• Any shared logic must be executed in the same shell session as its callers.

---

Installer contract constraints

• Installers must be:
  • deterministic
  • artifact-driven
  • idempotent
  • strict (set -euo pipefail)
• All runtime installers require explicit environment projection:
  • RUNTIME_VERSION is mandatory
  • artifact naming may be customized via ARCHIVE_PREFIX
• Installers must not parse JSON or agent state files.

---

Responsibility boundaries

• API declares intent (runtime, version, container type).
• Agent translates intent into:
  • environment variables
  • filesystem operations
  • installer execution order
• Installers perform no orchestration or decision-making.

---

Anti-patterns (explicitly forbidden)

• Mega-installers that handle multiple runtimes via branching logic
• Package-manager–based installs (apt, nvm, pyenv, sdkman)
• Weakening installer strictness to accommodate agent bugs

---