@omega.js/desktop 0.53.0 → 0.54.1

package/dist/utils/build-pipeline.js

@@ -1,4 +1,4 @@
-// The build-mode pipeline shared by the `build`, `package`, and `publish` verbs.
+// The pipeline shared by the `build`, `package`, `publish` and `dev` verbs.
 //
 // The CLI verbs are canonical and the synced projectScripts are thin
 // `omega <verb>` aliases, so a verb must run the pipeline ITSELF and never
@@ -10,8 +10,8 @@
 // Libraries
 const { execute } = require('node-powertools');
 
-function gulpCommand(task) {
-  return `npm run gulp -- ${task}`;
+function gulpCommand(task, args = []) {
+  return `npm run gulp -- ${[task, ...args].join(' ')}`;
 }
 
 // Default step implementations — required lazily so requiring a plan never
@@ -30,7 +30,7 @@ const RUNNERS = {
   'ship-keys': () => require('./ship-keys.js').assertShipKeys(),
   // `strict` rides the STEP: publish declares it (#891), a bare verb does not.
   'validate-certs': (options, step) => require('../commands/validate-certs.js')({ ...options, strict: step.strict === true || options.strict === true }),
-  gulp: (options, step) => execute(gulpCommand(step.task), { log: true }),
+  gulp: (options, step) => execute(gulpCommand(step.task, step.args), { log: true }),
 };
 
 async function runPipeline(plan, options, runners) {

package/dist/utils/runner-env.js

@@ -35,6 +35,8 @@
 const fs   = require('fs');
 const os   = require('os');
 const path = require('path');
+const { envLine, assertEnvReadsBack } = require('../vendor/config/index.js');
+const { setEnvLines } = require('../vendor/devkit/env-lines.js');
 
 // Runner files live under %LOCALAPPDATA%\omega-runner — a per-user path that
 // doesn't need admin to read/write. Set OMEGA_RUNNER_HOME to override.
@@ -308,37 +310,20 @@ function ensureRunnerEnvFile(home) {
   return true;
 }
 
-// Write values into the file IN PLACE: an existing `KEY=` line (commented or
-// not) is replaced, a key the file never had is appended. Comments and order
-// survive, so the file stays the one a person reads.
+// Write values into the file IN PLACE through devkit's setEnvLines: a key's
+// first line or `# KEY=""` placeholder takes the new line and later ones drop,
+// so dotenv reads the new value; a key the file never had is appended. Comments
+// and order survive, so the file stays the one a person reads.
 function writeRunnerEnvValues(home, values) {
-  // Every value double-quoted, the one .env quoting rule this repo writes
-  // everywhere. dotenv reads a double-quoted value back verbatim and has no
-  // escape for a `"` inside one, so a value carrying one cannot be written at
-  // all: refuse it — naming the key and the character — before the file is
-  // touched, rather than save a value that reads back wrong.
-  const serialize = (key, value) => `${key}="${value}"`;
-  for (const [key, value] of Object.entries(values)) {
-    if (String(value).includes('"')) {
-      throw new Error(`${key} contains a double quote (") — a .env value cannot carry one. Remove it, then set ${key} again.`);
-    }
-  }
+  // envLine is the one .env serializer; it refuses, naming the key, a value
+  // dotenv would read back changed, before the file is touched.
+  const lineFor = Object.fromEntries(Object.entries(values).map(([key, value]) => [key, envLine(key, value)]));
 
   ensureRunnerEnvFile(home);
-  const file  = runnerEnvFile(home);
-  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
-  const seen  = new Set();
-
-  const out = lines.map((line) => {
-    const m = /^\s*#?\s*([A-Z][A-Z0-9_]*)\s*=/.exec(line);
-    if (!m || !(m[1] in values) || seen.has(m[1])) return line;
-    seen.add(m[1]);
-    return serialize(m[1], String(values[m[1]]));
-  });
-  for (const [key, value] of Object.entries(values)) {
-    if (!seen.has(key)) out.push(serialize(key, String(value)));
-  }
-  fs.writeFileSync(file, out.join('\n').replace(/\n*$/, '\n'));
+  const file    = runnerEnvFile(home);
+  const content = setEnvLines(fs.readFileSync(file, 'utf8'), lineFor);
+  assertEnvReadsBack(content, values);
+  fs.writeFileSync(file, content);
   return file;
 }
 

package/dist/vendor/config/company.js

@@ -44,6 +44,9 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const JSON5 = require('json5');
+const Logger = require('../devkit/logger.js');
+
+const logger = new Logger('company');
 
 // The company TREE inside the parent brand's repo, and the file an off-laptop
 // run reads the resolved layer from: GENERATED beside the brand config by the
@@ -62,13 +65,16 @@ const REGISTRY_FILE = 'brands.json';
 // it visible").
 const SELF = 'self';
 
-// The legacy stamp #677 retired, warned about where an owner still carries one.
-const RETIRED_MARKER = path.join('.omega', 'company.json');
+// The `company` keys the LOADER fills: never typed, always resolved.
+const RESOLVED_COMPANY_KEYS = ['name', 'url', 'images'];
 
 // One warning per company id per process: a missing parent is a state a whole
 // build runs in, never a per-call event.
 const warned = new Set();
 
+// One warning per process for a registry file that is there but will not parse.
+let warnedUnreadable = false;
+
 /**
  * The machine home OMEGA keeps its per-machine state in. `OMEGA_HOME` moves it
  * (the test lanes point it at a temp dir so a fixture never writes a real line).
@@ -118,6 +124,17 @@ function readRegistry() {
   return readJson(registryFile()) || {};
 }
 
+/**
+ * A registry line's root when it is on this machine now, else null: the ONE
+ * test both the reader and the write's prune apply, so a line the reader would
+ * resolve is never a line the prune drops.
+ * @param {object} line - A registry line.
+ * @returns {string|null}
+ */
+function liveRoot(line) {
+  return line && typeof line.root === 'string' && isDir(line.root) ? line.root : null;
+}
+
 /**
  * Record (or refresh) ONE brand's line in the machine registry, which is what
  * every `loadConfig()` does for the brand it just loaded: the map of where the
@@ -130,7 +147,13 @@ function readRegistry() {
  *
  * A write also PRUNES the lines whose root is gone: the file is a map of what
  * is on this machine, so a brand that was deleted or moved (and re-recorded
- * under its new root) leaves nothing behind to resolve into.
+ * under its new root) leaves nothing behind to resolve into. A line whose root
+ * is on disk is never pruned (`liveRoot`, the reader's own test).
+ *
+ * A registry file that is THERE but will not parse is never rewritten: writing
+ * over it would keep one line and drop every other brand. The write itself is
+ * a rename of a finished temp file, so a racing reader never sees half a file.
+ * Every write logs its caller and the kept and pruned ids at debug level.
  *
  * @param {object} entry - The brand's own facts.
  * @param {string} entry.id - `brand.id` (the key).
@@ -143,7 +166,17 @@ function recordBrand({ id, root, name, url }) {
   if (!id || !root) return false;
 
   try {
-    const registry = readRegistry();
+    const file = registryFile();
+    const registry = fs.existsSync(file) ? readJson(file) : {};
+
+    if (!registry) {
+      if (!warnedUnreadable) {
+        warnedUnreadable = true;
+        logger.warn(`Machine registry ${file} does not parse: left as it is, no brand recorded. Delete it and any omega verb rebuilds it.`);
+      }
+      return false;
+    }
+
     const current = registry[id];
     const line = { root, name: name || null, url: url || null };
 
@@ -153,10 +186,15 @@ function recordBrand({ id, root, name, url }) {
 
     registry[id] = { ...line, updatedAt: new Date().toISOString() };
 
-    const live = Object.fromEntries(Object.entries(registry).filter(([, entry]) => entry && isDir(entry.root)));
+    const live = Object.fromEntries(Object.entries(registry).filter(([, entry]) => liveRoot(entry)));
+    const pruned = Object.keys(registry).filter((key) => !(key in live));
 
     fs.mkdirSync(omegaHome(), { recursive: true });
-    fs.writeFileSync(registryFile(), `${JSON.stringify(live, null, 2)}\n`);
+    const temp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, `${JSON.stringify(live, null, 2)}\n`);
+    fs.renameSync(temp, file);
+
+    logger.debug(`Registry write by ${process.argv[1] || process.argv0} (pid ${process.pid}): kept [${Object.keys(live).join(', ')}], pruned [${pruned.join(', ')}]`);
     return true;
   } catch {
     return false;
@@ -271,13 +309,6 @@ function resolveCompany(brandRoot, brandConfig) {
   const webhooks = !(config.company && config.company.webhooks === false);
   const reply = (facts) => answer({ ...facts, webhooks });
 
-  // A brand still carrying the retired stamp hears about it once: the folder it
-  // points at is not read any more, by anything.
-  if (root && fs.existsSync(path.join(root, RETIRED_MARKER)) && !warned.has(RETIRED_MARKER)) {
-    warned.add(RETIRED_MARKER);
-    console.warn(`${path.join(root, RETIRED_MARKER)} is retired (#677): delete it, and name the company with company: { id: '<parent brand.id>' } in omega.json5.`);
-  }
-
   // No company: the brand IS the whole entity, so the company facts are its own
   // and every reader works without a fallback.
   if (!id) {
@@ -290,7 +321,7 @@ function resolveCompany(brandRoot, brandConfig) {
   }
 
   const line = readRegistry()[id];
-  const parentRoot = line && typeof line.root === 'string' && isDir(line.root) ? line.root : null;
+  const parentRoot = liveRoot(line);
 
   if (parentRoot) {
     const parentBrand = (readBrandConfig(parentRoot) || {}).brand || {};
@@ -347,4 +378,5 @@ module.exports = {
   COMPANY_DIR,
   COMPANY_RESOLVED_FILE,
   COMPANY_SELF: SELF,
+  RESOLVED_COMPANY_KEYS,
 };

package/dist/vendor/config/defaults.js

@@ -27,6 +27,8 @@
  * brand config is a copy that drifts from the thing it came from.
  */
 
+const { isDeepStrictEqual } = require('node:util');
+
 const { SHARED_SCHEMA, TARGET_SCHEMAS } = require('./schema.js');
 const { isPlainObject } = require('./merge.js');
 
@@ -59,6 +61,12 @@ function defaultRules(target) {
   return rules.filter(hasDefault);
 }
 
+/**
+ * Set a value at a dot-path, creating the objects on the way.
+ * @param {object} target
+ * @param {string} dotted
+ * @param {*} value
+ */
 function setAtPath(target, dotted, value) {
   const names = dotted.split('.');
   const leaf = names.pop();
@@ -127,13 +135,26 @@ function defaultComments(target) {
   return comments;
 }
 
-function collectMissing(defaults, present, prefix, target, found) {
-  for (const [key, value] of Object.entries(defaults)) {
+/**
+ * What filling `present` from `incoming` does, key by key, never overwriting:
+ * a path `present` lacks is ADDED at its highest missing point (one block,
+ * not one edit per key inside it), and a path `present` already answers
+ * differently is KEPT. An equal value is neither.
+ * @param {object} incoming - The values on offer.
+ * @param {object} present - The authored config they would fill.
+ * @returns {{ added: Array<{ path: string, value: * }>, kept: Array<{ path: string, value: *, incoming: * }> }}
+ */
+function planMerge(incoming, present) {
+  return collectPlan(incoming, present, '', { added: [], kept: [] });
+}
+
+function collectPlan(incoming, present, prefix, plan) {
+  for (const [key, value] of Object.entries(incoming)) {
     const dotted = prefix ? `${prefix}.${key}` : key;
     const authored = isPlainObject(present) && Object.prototype.hasOwnProperty.call(present, key);
 
     if (!authored) {
-      found.push({ path: dotted, value });
+      plan.added.push({ path: dotted, value });
       continue;
     }
 
@@ -141,11 +162,13 @@ function collectMissing(defaults, present, prefix, target, found) {
     // A brand that authored anything else at this path (a scalar, false, null)
     // made a decision: never dive in, never overwrite.
     if (isPlainObject(value) && isPlainObject(present[key])) {
-      collectMissing(value, present[key], dotted, target, found);
+      collectPlan(value, present[key], dotted, plan);
+    } else if (!isDeepStrictEqual(value, present[key])) {
+      plan.kept.push({ path: dotted, value: present[key], incoming: value });
     }
   }
 
-  return found;
+  return plan;
 }
 
 /**
@@ -167,7 +190,7 @@ function missingDefaults(config, target) {
   // copy to drift ([#793](https://github.com/Omega-JS-Stack/omega/issues/793))
   const writable = defaultsFrom(defaultRules(target).filter(isMaterialized));
 
-  return collectMissing(writable, config || {}, '', target, []);
+  return planMerge(writable, config || {}).added;
 }
 
-module.exports = { schemaDefaults, missingDefaults, defaultComments, defaultRules };
+module.exports = { schemaDefaults, missingDefaults, defaultComments, defaultRules, planMerge, setAtPath };

package/dist/vendor/config/edit.js

@@ -579,12 +579,23 @@ function applyConfigEdits(source, edits, { comments = {} } = {}) {
  * @param {{ dryRun?: boolean, comments?: Object<string, string> }} [options]
  * @returns {{ path: string, changed: boolean, applied: string[] }}
  */
-function writeConfigValues(projectDir, edits, { dryRun = false, comments = {} } = {}) {
+function writeConfigValues(projectDir, edits, options) {
   const configPath = resolveConfigPath(projectDir);
   if (!configPath) {
     throw new Error(`No ${FILE_NAME} found under ${projectDir} — cannot write config values`);
   }
 
+  return writeConfigFileValues(configPath, edits, options);
+}
+
+/**
+ * writeConfigValues on one named omega file (an overlay, a target's own file).
+ * @param {string} configPath - The file to edit.
+ * @param {Object<string, *>} edits - Dot-path → value.
+ * @param {{ dryRun?: boolean, comments?: Object<string, string> }} [options]
+ * @returns {{ path: string, changed: boolean, applied: string[] }}
+ */
+function writeConfigFileValues(configPath, edits, { dryRun = false, comments = {} } = {}) {
   const source = fs.readFileSync(configPath, 'utf8');
   const applied = pendingEdits(JSON5.parse(source), edits).map(([path]) => path);
   // Every writeback also normalizes top-level key order (comments travel
@@ -748,12 +759,23 @@ function applyConfigRemovals(source, paths) {
  * @param {{ dryRun?: boolean }} [options]
  * @returns {{ path: string, changed: boolean, removed: string[] }}
  */
-function removeConfigValues(projectDir, paths, { dryRun = false } = {}) {
+function removeConfigValues(projectDir, paths, options) {
   const configPath = resolveConfigPath(projectDir);
   if (!configPath) {
     throw new Error(`No ${FILE_NAME} found under ${projectDir} — cannot remove config values`);
   }
 
+  return removeConfigFileValues(configPath, paths, options);
+}
+
+/**
+ * removeConfigValues on one named omega file (an overlay, a target's own file).
+ * @param {string} configPath - The file to edit.
+ * @param {string[]} paths - Dot-paths to delete.
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ path: string, changed: boolean, removed: string[] }}
+ */
+function removeConfigFileValues(configPath, paths, { dryRun = false } = {}) {
   const source = fs.readFileSync(configPath, 'utf8');
   const parsed = JSON5.parse(source);
   const removed = paths.filter((path) => getAtPath(parsed, path) !== undefined);
@@ -766,4 +788,4 @@ function removeConfigValues(projectDir, paths, { dryRun = false } = {}) {
   return { path: configPath, changed: next !== source, removed };
 }
 
-module.exports = { applyConfigEdits, writeConfigValues, applyConfigRemovals, removeConfigValues, parseRoot };
+module.exports = { applyConfigEdits, writeConfigValues, writeConfigFileValues, applyConfigRemovals, removeConfigValues, removeConfigFileValues, parseRoot };

package/dist/vendor/config/env-delivery.js

@@ -54,7 +54,7 @@ const WORKFLOW_OWNED_KEYS = ['GH_TOKEN', 'CLOUDFLARE_TOKEN', 'NODE_VERSION', 'NO
 
 // Rendered in place of the block when a target delivers nothing, so the
 // generated region is always a valid, self-explaining line of YAML.
-const EMPTY_BLOCK = '# (no CI-delivered keys for this target — the next omega verb regenerates this block)';
+const EMPTY_BLOCK = '# (no CI-delivered keys for this target: the next omega verb regenerates this block)';
 
 // What a target's generated workflow carries in the runner env, per target.
 //

package/dist/vendor/config/env-schema.js

@@ -874,12 +874,9 @@ const ENV_SCHEMA = [
     description: 'Edge Add-ons API key the publish request authenticates with.',
   },
 
-  // No test-lane credentials live here any more
-  // ([#819](https://github.com/Omega-JS-Stack/omega/issues/819), Ian
-  // 2026-09-13): web, desktop and extension each test their own sign-in
-  // against a persona the backend emulator seeds, so a suite never asks a
-  // brand for a key. The pair that used to sit here is retired outright
-  // (env-retired.js carries both rows); #904 owns the replacement.
+  // No test-lane credentials live here: web, desktop and extension each sign
+  // in as a persona the backend emulator seeds, so a suite never asks a brand
+  // for a key. The retired pair's rows are @omega.js/manager's migrate table.
 
   {
     name:        'OMEGA_FONTAWESOME_ROOT',

package/dist/vendor/config/env.js

@@ -32,7 +32,6 @@ const path = require('node:path');
 const { findBrandRoot } = require('./load.js');
 const { resolveCompany } = require('./company.js');
 const { ENV_SCHEMA, envFileGroups, envSchemaEntry } = require('./env-schema.js');
-const { assertNoRetiredEnvKeys } = require('./env-retired.js');
 // The one vocabulary lives with the one environment module (#817); this file
 // re-exports it so the .env overlay names and the runtime answer stay one list.
 const { ENV_ENVIRONMENTS } = require('./environment.js');
@@ -322,11 +321,8 @@ function reloadEnv(startDir, { target, environment = envEnvironment() } = {}) {
 /**
  * Parse one .env file into a plain map. Missing files read as empty.
  *
- * The ONE place a `.env` layer is read, so it is also where a RETIRED key is
- * refused ([#893](https://github.com/Omega-JS-Stack/omega/issues/893)): there
- * is no dual-read, so a line for a key that moved into config is a value
- * nothing consults, and both readers below (the process cascade and the
- * artifact composer) fail on it naming the move.
+ * The layer is OPEN: an .env may carry keys outside omega, so a key nothing
+ * reads (a retired one included) is simply unread. `omega migrate` names those.
  *
  * @param {string|null} envPath
  * @returns {Object<string, string>} Parsed key → value.
@@ -334,10 +330,7 @@ function reloadEnv(startDir, { target, environment = envEnvironment() } = {}) {
 function parseEnvFile(envPath) {
   if (!envPath || !fs.existsSync(envPath)) return {};
 
-  const parsed = require('dotenv').parse(fs.readFileSync(envPath, 'utf8'));
-  assertNoRetiredEnvKeys(parsed, envPath);
-
-  return parsed;
+  return require('dotenv').parse(fs.readFileSync(envPath, 'utf8'));
 }
 
 /**
@@ -441,34 +434,53 @@ function composeTargetEnv({ targetDir, target, environment = envEnvironment() })
 }
 
 /**
- * Serialize one value as a double-quoted .env line — the serializer SSOT every
- * writeback rides (this composer, the manager's brand .env writeback and
- * scaffold stub). Backslashes, quotes and newlines escape so a multi-line blob
- * stays line-safe (dotenv expands `\n` back on read).
+ * Throw unless dotenv reads every given value back from `content` exactly as
+ * given. The error names the keys, never a value.
+ *
+ * @param {string} content - .env content holding the written lines.
+ * @param {Object<string, string>} values - The values those lines must carry.
+ */
+function assertEnvReadsBack(content, values) {
+  const parsed = require('dotenv').parse(content);
+  const changed = Object.keys(values).filter((key) => parsed[key] !== String(values[key]));
+  if (changed.length === 0) return;
+
+  throw new Error(`.env: the value of ${changed.join(', ')} would not read back unchanged from KEY="value" (dotenv expands a literal \\n or \\r, a quote followed by # ends the value, and a trailing backslash can run into the next line)`);
+}
+
+/**
+ * Serialize one value as a double-quoted .env line, the serializer SSOT every
+ * writeback rides. The value goes in raw (dotenv reads `"`, `\`, `'`, `#` back
+ * unchanged); a real newline or carriage return becomes `\n` / `\r`, which
+ * dotenv expands back. A value dotenv would read back changed, such as a
+ * literal backslash-n or backslash-r, throws naming the key only.
  *
  * @param {string} key - Env var name.
  * @param {string} value - Value to serialize.
  * @returns {string} `KEY="value"`.
  */
 function envLine(key, value) {
-  const escaped = String(value)
-    .replace(/\\/g, '\\\\')
-    .replace(/"/g, '\\"')
-    .replace(/\n/g, '\\n');
+  const raw = String(value).replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+  const line = `${key}="${raw}"`;
+  assertEnvReadsBack(line, { [key]: value });
 
-  return `${key}="${escaped}"`;
+  return line;
 }
 
 /**
- * Serialize composed values as .env content — one envLine per key.
+ * Serialize composed values as .env content, one envLine per key. The whole
+ * file is judged too: a value ending in a backslash can carry dotenv's read
+ * into the next line, which no single line shows.
  *
  * @param {Object<string, string>} values
  * @returns {string} The file content, newline-terminated.
  */
 function serializeEnv(values) {
   const lines = Object.entries(values).map(([key, value]) => envLine(key, value));
+  const content = `${lines.join('\n')}\n`;
+  assertEnvReadsBack(content, values);
 
-  return `${lines.join('\n')}\n`;
+  return content;
 }
 
-module.exports = { loadEnv, reloadEnv, ENV_ENVIRONMENTS, envEnvironment, resolveEnvChain, envLayerFiles, loadEnvChain, loadEnvRoots, applyDeliverAs, composeTargetEnv, envLine, serializeEnv };
+module.exports = { loadEnv, reloadEnv, ENV_ENVIRONMENTS, envEnvironment, resolveEnvChain, envLayerFiles, loadEnvChain, loadEnvRoots, applyDeliverAs, composeTargetEnv, assertEnvReadsBack, envLine, serializeEnv };

package/dist/vendor/config/index.js

@@ -23,19 +23,17 @@ const { TARGETS, CUSTOM_TARGET_TYPE, isCustomTargetEntry, BACKEND_PROJECT_TYPES,
 const { clientConfig, CLIENT_FACT_KEYS } = require('./client-config.js');
 const { deepMerge } = require('./merge.js');
 const { findSecretKeys, SECRET_KEY_PATTERN } = require('./secrets.js');
-const { findRetiredKeys, RETIRED_KEYS, RETIRED_PATHS } = require('./retired-keys.js');
 const { chosenProvider } = require('./providers.js');
-const { validateConfig, runSchema, formatErrors, resolvedBrandHost } = require('./validate.js');
-const { loadConfig, composeTargetConfig, hasOmegaConfig, resolveConfigPath, getEnabledTargets, findBrandRoot, findBrandConfigPath, resolveBrandRoot, FILE_NAME, CONFIG_LOCATIONS } = require('./load.js');
+const { validateConfig, undeclaredPaths, undeclaredAuthoredPaths, runSchema, formatErrors, resolvedBrandHost } = require('./validate.js');
+const { loadConfig, composeTargetConfig, hasOmegaConfig, resolveConfigPath, overlayPath, getEnabledTargets, findBrandRoot, findBrandConfigPath, resolveBrandRoot, FILE_NAME, CONFIG_LOCATIONS } = require('./load.js');
 const { ENV_ENVIRONMENTS, ENVIRONMENT_VAR, getEnvironment, isDevelopment, isProduction, isTesting, setEnvironment, buildLaneEnvironment } = require('./environment.js');
-const { loadEnv, reloadEnv, envEnvironment, resolveEnvChain, envLayerFiles, loadEnvChain, loadEnvRoots, applyDeliverAs, composeTargetEnv, envLine, serializeEnv } = require('./env.js');
+const { loadEnv, reloadEnv, envEnvironment, resolveEnvChain, envLayerFiles, loadEnvChain, loadEnvRoots, applyDeliverAs, composeTargetEnv, assertEnvReadsBack, envLine, serializeEnv } = require('./env.js');
 const { ENV_SCHEMA, ENV_GROUPS, DELIVERY_MODES, envFileGroups, envSchemaEntry, envKeysForTarget, generatedEnvKeys, requiredEnvKeys, envKeysByGroup } = require('./env-schema.js');
 const { WORKFLOW_OWNED_KEYS, deliveredKeys, workflowSecretKeys, envFileKeys, artifactEnvValues, bakeKeys, bakeSourceKeys, publishSecretKeys, renderSecretsBlock, renderEnvFileKeys } = require('./env-delivery.js');
 const { checkEnvRules } = require('./env-rules.js');
-const { RETIRED_ENV_KEYS, findRetiredEnvKeys, assertNoRetiredEnvKeys } = require('./env-retired.js');
 const { resolveCompany, recordBrand, readRegistry, registryFile, COMPANY_DIR, COMPANY_RESOLVED_FILE, COMPANY_SELF } = require('./company.js');
-const { applyConfigEdits, writeConfigValues, applyConfigRemovals, removeConfigValues } = require('./edit.js');
-const { schemaDefaults, missingDefaults, defaultComments } = require('./defaults.js');
+const { applyConfigEdits, writeConfigValues, writeConfigFileValues, applyConfigRemovals, removeConfigValues, removeConfigFileValues } = require('./edit.js');
+const { schemaDefaults, missingDefaults, defaultComments, planMerge, setAtPath } = require('./defaults.js');
 const { applyCanonicalOrder, CANONICAL_TOP_LEVEL_ORDER } = require('./order.js');
 const { resolveSeedMode } = require('./seed.js');
 const { resolveHook, loadHook } = require('./hooks.js');
@@ -55,6 +53,7 @@ module.exports = {
   composeTargetConfig,
   hasOmegaConfig,
   resolveConfigPath,
+  overlayPath,
   getEnabledTargets,
   findBrandRoot,
   findBrandConfigPath,
@@ -101,6 +100,7 @@ module.exports = {
   composeTargetEnv,
 
   // The .env serializer SSOT — every writeback renders through these
+  assertEnvReadsBack,
   envLine,
   serializeEnv,
 
@@ -136,13 +136,6 @@ module.exports = {
   // `requiredWhen`; every consumer calls it, none keeps its own if
   checkEnvRules,
 
-  // The .env half of the retired-key register (#893): a key that moved into
-  // config fails the layer that still declares it, naming the move. Every
-  // `.env` read goes through parseEnvFile, so nothing can miss the check
-  RETIRED_ENV_KEYS,
-  findRetiredEnvKeys,
-  assertNoRetiredEnvKeys,
-
   // The ONE company resolver (#677): `company: { id }` in, the company's public
   // facts plus its tree on this machine out. The config chain, the .env chain,
   // owner hooks and the desktop signing tree all inherit through its `file()`,
@@ -162,8 +155,10 @@ module.exports = {
   // Writeback (comment-preserving edits + canonical top-level key order)
   applyConfigEdits,
   writeConfigValues,
+  writeConfigFileValues,
   applyConfigRemovals,
   removeConfigValues,
+  removeConfigFileValues,
   applyCanonicalOrder,
   CANONICAL_TOP_LEVEL_ORDER,
 
@@ -171,6 +166,8 @@ module.exports = {
   // heal list the manage walk materializes into a brand's omega.json5
   schemaDefaults,
   missingDefaults,
+  planMerge,
+  setAtPath,
   defaultComments,
 
   // Layer-aware consumer seeding (brand target = no local-layer config at all)
@@ -244,6 +241,8 @@ module.exports = {
 
   // Validation
   validateConfig,
+  undeclaredPaths,
+  undeclaredAuthoredPaths,
   runSchema,
   formatErrors,
 
@@ -254,9 +253,6 @@ module.exports = {
 
   findSecretKeys,
   SECRET_KEY_PATTERN,
-  findRetiredKeys,
-  RETIRED_KEYS,
-  RETIRED_PATHS,
 
   // The one provider shape (#425) — `role.providers.<provider>`, where key
   // presence is the pick and `false` is the deliberate off switch

package/dist/vendor/config/load.js

@@ -66,7 +66,7 @@ const path = require('node:path');
 const JSON5 = require('json5');
 
 const { deepMerge, isPlainObject } = require('./merge.js');
-const { resolveCompany, recordBrand } = require('./company.js');
+const { resolveCompany, recordBrand, RESOLVED_COMPANY_KEYS } = require('./company.js');
 const { findSecretKeys } = require('./secrets.js');
 const { validateConfig } = require('./validate.js');
 const { TARGETS } = require('./schema.js');
@@ -134,10 +134,22 @@ function resolveOverlayEnvironment(environment, fallback) {
 function resolveOverlayPath(basePath, environment) {
   if (!basePath || !environment) return null;
 
-  const overlay = path.join(path.dirname(basePath), `${path.basename(FILE_NAME, '.json5')}.${environment}.json5`);
+  const overlay = overlayPath(basePath, environment);
   return fs.existsSync(overlay) ? overlay : null;
 }
 
+/**
+ * The ONE spelling of a layer's environment overlay: `omega.<environment>.json5`
+ * beside its base file, whether or not either exists. Every reader and writer
+ * of an overlay names it through here.
+ * @param {string} basePath - The layer's omega.json5 path.
+ * @param {string} environment - One of ENV_ENVIRONMENTS.
+ * @returns {string} Absolute overlay path.
+ */
+function overlayPath(basePath, environment) {
+  return path.join(path.dirname(basePath), `${path.basename(FILE_NAME, '.json5')}.${environment}.json5`);
+}
+
 /**
  * Cheap probe: does this project have an omega.json5 at all? Frameworks use it
  * to fail soft in non-consumer dirs (seeded-empty config); tooling uses it as
@@ -301,10 +313,6 @@ function stripTargets(config) {
   return shared;
 }
 
-// The `company` keys the LOADER fills (#677): authored, they would be
-// overwritten at every load, so an author hears about it at the file.
-const RESOLVED_COMPANY_KEYS = ['name', 'url', 'images'];
-
 /**
  * The company keys nobody types, refused where a human writes them: the BRAND
  * file and the COMPANY file (#677). The local layer is deliberately exempt,
@@ -737,4 +745,4 @@ function composeTargetConfig(projectDir, target, options) {
   return { config, files: { local: localPath, brand: brandPath, company: companyPath } };
 }
 
-module.exports = { loadConfig, composeTargetConfig, hasOmegaConfig, resolveConfigPath, getEnabledTargets, findBrandRoot, findBrandConfigPath, resolveBrandRoot, FILE_NAME, CONFIG_LOCATIONS, TARGET_SUBDIRS };
+module.exports = { loadConfig, composeTargetConfig, hasOmegaConfig, resolveConfigPath, overlayPath, getEnabledTargets, findBrandRoot, findBrandConfigPath, resolveBrandRoot, FILE_NAME, CONFIG_LOCATIONS, TARGET_SUBDIRS };