Infrastructure Patches — site-specific env overlays via patch registries

[michael-herwig]

Problem

Enterprise environments need to layer site-specific configuration (corporate certificates, proxy settings, registry mirrors) on top of third-party packages without forking or rebuilding them. Package publishers can't anticipate every consumer's infrastructure requirements.

Proposed Solution

A client-configured patch registry model: infrastructure operators maintain a separate OCI registry containing lightweight patch descriptors that map packages to companion config packages. When OCX installs or executes a patched package, it co-installs the companions and composes their environment variables on top.

Key design decisions:

• No push access to upstream required — patches live in the infra operator's own registry, not alongside the source packages
• Companion packages are regular OCX packages — no new artifact types, no new install mechanics
• Unified dependency graph — patches are modeled as Patch edges in the same DAG as evelynn's Dependency edges, composed via a single Kahn's topological sort. No separate env composition phases.
• Override by design — companion env vars apply after the base package in topological order, so infrastructure intent naturally overrides publisher defaults (e.g., SSL_CERT_FILE pointing to the company CA bundle)
• Transitive companion dependencies — companion packages can declare their own dependencies, resolved transitively in the same graph
• GC works unchanged — back-references from companion objects to base package install symlinks; Kahn's-based GC collects unreferenced companions automatically

Example

# $OCX_HOME/config.toml
[patches]
registry = "internal.company.com/ocx-patches"

$ ocx exec ocx.sh/java:21 -- mvn build
# Resolves patches → co-installs zscaler-root cert bundle + JDK truststore config
# Environment composed in topological order:
#   glibc → gcc → java:21 → zscaler-root → jdk21-truststore
# SSL_CERT_FILE overridden by zscaler-root (patch) ✓

Status

Proposal / ADR only — no implementation yet. Looking for feedback on:

• The unified graph model (patches as edges vs. separate composition phase)
• Override intent semantics (ConstantTracker info vs. warn distinction)
• Patch descriptor format and rule matching
• Companion ordering when multiple patches target the same base package
• The artifacts/ symlink store for non-package OCI artifacts

Artifacts

• .claude/artifacts/adr_infrastructure_patches.md — full design record
• .claude/artifacts/research_infrastructure_patches_overlays.md — industry research (Nix overlays, Kustomize, OCI Referrers, Conda, Homebrew)

[github-actions]

Unit Test Results

584 tests  ±0   584 ✅ ±0   5s ⏱️ -1s
  3 suites ±0     0 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit 0ccde04. ± Comparison against base commit ba799c4.

[github-actions]

Acceptance Test Results

156 tests  ±0   156 ✅ ±0   32s ⏱️ ±0s
  1 suites ±0     0 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit 0ccde04. ± Comparison against base commit ba799c4.