[jcombs-pointblue]

Why

Taking on an existing system means production and QA trees that have grown apart:

• drivers only one holds, for now or for good;
• drivers named differently;
• different servers, usually fewer outside production;
• jobs scheduled differently;
• hundreds of policy differences, some intended and some not.

Design and decisions D1–D6: docs/existing-environments.md.

What

• environments / planned on drivers (driver.xml), jobs, role-based entitlement policies and templates.
  • Overrides.apply leaves out what an environment doesn't get, so compare, plan, deploy and the gate all follow it.
  • A scoped request for an excluded driver is refused.
  • A deploy never deletes an environment's own copy of an excluded object, and the gate doesn't count it as drift.
  • Edit operations: driver.set environments|planned, and environments.set for several objects at once.
• Names per environment: drivers/<d>.name, applied through DriverSet.renameDriver, which rewrites the DN, the artifacts' owner and the links. Imports map names back with toTreeNames, and secrets answer to either name (Secrets.withNames).
• Server map: servers.<tree server's name> = <env server DN>.
  • Several tree servers can map onto one environment server; .prefer picks whose settings it takes.
  • Servers.foldPrimary turns a mapped primary's settings into the base the deploy writes.
  • ServerMap.toTree maps back on import.
  • New validation check: server-unmapped.
  • The key names the server, because the overrides file splits each line at its first =.
• Job keys: .job.<job>.schedule|disabled|trace-*.
• A new driver's server, chosen at deploy (--driver-server): manual start on that server, disabled everywhere else, after waiting for replication.
• vault.compare-envs (EnvironmentCompare):
  • objects only one side holds, marked expected or planned;
  • values, with the tree's own value;
  • likely renames, with feeds between environments flagged;
  • drift with a likely cause per change, and case-only DN differences kept apart;
  • known differences filtered out.
• Known differences: overrides/<env>.known.json, with known.accept / known.forget, matched by fingerprint.
• Import: keepOnImport keeps the tree's drivers and objects that an environment doesn't get, and --mark-new-drivers marks drivers new to the tree as that environment's.

Checked

• Tests: all 953 unit tests pass, plus bin/ci-portable.sh (71).
• New test classes: DriverEnvironmentsTest (11 tests) and ServerMapTest (5); PlanTest covers the runs-on choice.
• A customer's QA and production LDIF exports (local only, never committed):
  • 827 raw differences, sorted into likely causes;
  • three likely renames proposed correctly, one flagged as a feed;
  • with a server map, all job server differences go away.
• Live, read only, edir3 against edir2:
  • jobs differ only by server until edir2's servers are mapped, then "the same configuration";
  • a scoped dry-run plan to edir2 shows no differences.

Version 0.49.0 on the branch; release when merged.

🤖 Generated with Claude Code