@omega.js/desktop 0.50.0 → 0.52.0

package/dist/utils/url-helpers.js

@@ -11,6 +11,10 @@
 // callers normally pass NO argument. An explicit `environment` arg is an override
 // (used mainly by tests to pin a specific environment's mapping).
 
+// The missing-fact error is the ONE shared one (#834). Its module requires
+// nothing, so it rides the renderer bundle exactly as this file does.
+const { devFactMissing } = require('../vendor/config/dev-facts.js');
+
 // Guarded the way @omega.js/extension's twin is: the renderer bundle is a
 // browser context, and only the Node-side contexts (main, preload, build, the
 // test harness) carry the resolved-port env channel.
@@ -20,14 +24,9 @@ function envPort(name) {
     : undefined;
 }
 
-// The classic dev WEBSITE ORIGIN: a lockstep copy of @omega.js/config's
-// CLASSIC_DEV_ORIGIN, which is the SSOT. This module is attached in the RENDERER
-// too (src/renderer.js), so it rides the browser bundle and cannot require that
-// Node-only package (fs, net, json5); @omega.js/client mirrors the same constant
-// for the same reason. The build suite pins this copy to the config package's
-// value, so a drift fails a test instead of a user
-// ([#747](https://github.com/Omega-JS-Stack/omega/issues/747)).
-const CLASSIC_DEV_ORIGIN = 'https://localhost:4000';
+// The step that writes the resolved dev map into this surface's artifact, named
+// in every missing-fact error below (#834).
+const DEV_FACT_WRITER = "@omega.js/desktop's bundle task, from the live stack's ports file plus the OMEGA_*_PORT env channel";
 
 // One local port, from whichever channel this context has: the env var first
 // (the CLI that booted the stack publishes it, N7), then the `dev.ports` map
@@ -35,10 +34,26 @@ const CLASSIC_DEV_ORIGIN = 'https://localhost:4000';
 // parent env, so a bumped emulator port reaches it only that way
 // ([#745](https://github.com/Omega-JS-Stack/omega/issues/745)). Same helper,
 // same order as @omega.js/extension's src/utils/url-helpers.js.
+//
+// There is no third step any more (#834): the classic numbers used to be
+// hand-typed here as a last resort for "a build made with no stack up", which
+// is a guess about a port nothing identity-checks. A miss is loud instead.
 function localPort(context, envName, name) {
   return envPort(envName) || context?.config?.dev?.ports?.[name];
 }
 
+// The same read, REQUIRED: the one every URL getter below uses, because every
+// one of them is answering with a real local address or not at all.
+function requiredPort(context, envName, name) {
+  const port = localPort(context, envName, name);
+
+  if (!port) {
+    throw devFactMissing(`dev port for \`${name}\``, DEV_FACT_WRITER);
+  }
+
+  return port;
+}
+
 function getFunctionsUrl(environment) {
   const env = environment || this.getEnvironment();
   const projectId = this?.config?.cloud?.config?.projectId;
@@ -51,7 +66,7 @@ function getFunctionsUrl(environment) {
   // same three-step chain getApiUrl() walks: the OMEGA_*_PORT env channel (N7),
   // then the baked map, then the classic default.
   if (env === 'development' || env === 'testing') {
-    const port = localPort(this, 'OMEGA_FUNCTIONS_PORT', 'functions') || 5001;
+    const port = requiredPort(this, 'OMEGA_FUNCTIONS_PORT', 'functions');
     return `http://localhost:${port}/${projectId}/us-central1`;
   }
 
@@ -64,12 +79,13 @@ function getApiUrl(environment) {
   // Local for development OR testing; production otherwise. Mirrors
   // @omega.js/backend's getApiUrl (N7): a resolved OMEGA_HTTPS_PORT means
   // `mgr serve`'s mkcert proxy is up (https); otherwise plain http to the
-  // hosting emulator (env port, baked port, or classic 5002).
+  // hosting emulator (env port, then baked port). Neither resolved is a broken
+  // build, not a case to assume the classic 5002 through (#834).
   if (env === 'development' || env === 'testing') {
     const httpsPort = localPort(this, 'OMEGA_HTTPS_PORT', 'https');
     return httpsPort
       ? `https://localhost:${httpsPort}`
-      : `http://localhost:${localPort(this, 'OMEGA_HOSTING_PORT', 'hosting') || 5002}`;
+      : `http://localhost:${requiredPort(this, 'OMEGA_HOSTING_PORT', 'hosting')}`;
   }
 
   // Prod: api.<brand host>. Mirrors @omega.js/client.getApiUrl. Never derive
@@ -89,9 +105,10 @@ function getApiUrl(environment) {
 // ([#262](https://github.com/Omega-JS-Stack/omega/issues/262)): the baked
 // `dev.origin` the live website published (scheme, host AND port, the complete
 // fact) wins, else a port from the usual chain (OMEGA_WEBSITE_PORT, then the baked
-// `dev.ports.website`) composed over https, else the classic dev origin. The scheme
-// is https because `omega dev` fronts its public port with the mkcert proxy by
-// default, so a port alone can never say it
+// `dev.ports.website`) composed over https. There is no classic-origin fallback
+// any more (#834): a wrong dev origin fails as a silent connection refusal. The
+// scheme is https because `omega dev` fronts its public port with the mkcert
+// proxy by default, so a port alone can never say it
 // ([#747](https://github.com/Omega-JS-Stack/omega/issues/747)).
 // Prod → `config.brand.url`. Use this whenever app code wants to link out to "the
 // website" (Help → Website tray/menu items, "Open in browser," billing portal
@@ -106,8 +123,7 @@ function getWebsiteUrl(environment) {
       return origin;
     }
 
-    const port = localPort(this, 'OMEGA_WEBSITE_PORT', 'website');
-    return port ? `https://localhost:${port}` : CLASSIC_DEV_ORIGIN;
+    return `https://localhost:${requiredPort(this, 'OMEGA_WEBSITE_PORT', 'website')}`;
   }
 
   const url = this?.config?.brand?.url;
@@ -160,8 +176,8 @@ function attachTo(Manager) {
 
 module.exports = {
   attachTo,
-  CLASSIC_DEV_ORIGIN,
   localPort,
+  requiredPort,
   getFunctionsUrl,
   getApiUrl,
   getWebsiteUrl,

package/dist/vendor/config/bundle-id.js

@@ -0,0 +1,53 @@
+/**
+ * Bundle-identifier policy — reverse-DNS ids derived from the brand's web
+ * identity (Ian 2026-07-14: the prefix is the reverse domain, autoset at
+ * onboarding from the parent company when one exists, else the brand's own
+ * url).
+ *
+ *   deriveBundleIdPrefix('https://itwcreativeworks.com')   → 'com.itwcreativeworks'
+ *   deriveBundleIdPrefix('https://playground.omegajs.dev') → 'dev.omegajs.playground'
+ *   composeBundleId('com.itwcreativeworks', 'daily-build')
+ *     → 'com.itwcreativeworks.daily.build'
+ *
+ * Sanitization keeps ids legal on BOTH stores: Apple allows hyphens but
+ * Android package segments don't, so domain labels drop non-alphanumerics
+ * and brand-id hyphens become dots (each id word is its own segment).
+ */
+
+/**
+ * Reverse-DNS prefix from a company/brand url, or null when the url does
+ * not parse. `www.` is dropped; every other hostname label survives (a
+ * subdomain brand derives a subdomain-scoped prefix).
+ *
+ * @param {string} url - http(s) url (brand.url shape)
+ * @returns {string|null}
+ */
+function deriveBundleIdPrefix(url) {
+  let hostname;
+  try {
+    hostname = new URL(url).hostname;
+  } catch {
+    return null;
+  }
+
+  const labels = hostname
+    .replace(/^www\./, '')
+    .split('.')
+    .map((label) => label.toLowerCase().replace(/[^a-z0-9]/g, ''))
+    .filter(Boolean);
+
+  return labels.length > 0 ? labels.reverse().join('.') : null;
+}
+
+/**
+ * Full bundle identifier: prefix + the brand id with hyphens as dots.
+ *
+ * @param {string} prefix - reverse-DNS prefix (config or derived)
+ * @param {string} brandId - brand.id ('daily-build')
+ * @returns {string}
+ */
+function composeBundleId(prefix, brandId) {
+  return `${prefix}.${String(brandId).toLowerCase().replace(/-+/g, '.')}`;
+}
+
+module.exports = { deriveBundleIdPrefix, composeBundleId };

package/dist/vendor/config/client-config.js

@@ -0,0 +1,141 @@
+/**
+ * client-config.js: the ONE browser-safe subset of a resolved config
+ * ([#894](https://github.com/Omega-JS-Stack/omega/issues/894)).
+ *
+ * Three surfaces bake a config into an artifact a browser can read: web's page
+ * chrome, desktop's renderer bundle, and every extension bundle. Each one used
+ * to decide what may go public on its own, three different ways (desktop
+ * shipped the WHOLE resolved config, the extension kept a hand-written allow
+ * list, web wired a subset together in its engine and its foot include), so a
+ * new public value had to be added in three places and every one of them could
+ * be the place it leaked.
+ *
+ * This is that decision, once. The schema's `CLIENT_SECTIONS` says which
+ * sections a browser may see (and how much of each), the list below says which
+ * BUILD FACTS ride beside them, and nothing else leaves the build. All three
+ * bakes call this and wrap the answer identically:
+ *
+ *   OMEGA_BUILD_JSON = { config: clientConfig(resolved), package, mode, license, builtAt }
+ *
+ * Secrets are a loud failure, not a filter: a secret-shaped key inside a
+ * section that is about to ship means the resolved config carried one at all,
+ * which loadConfig() and validateConfig() already refuse. A value a build is
+ * SANCTIONED to bake (`publicAtRest`, docs/shared/config.md) comes from .env
+ * and is added by that build after this gate, never carried through it.
+ */
+
+const { CLIENT_SECTIONS } = require('./schema.js');
+const { findSecretKeys } = require('./secrets.js');
+const { resolveWinbackOffer } = require('./winback.js');
+
+// The per-build facts a surface composes ON TOP of the resolved config before
+// baking it. They are not config sections (nothing authors them in
+// omega.json5): each is a fact about the artifact, spelled the same on every
+// surface so one read answers everywhere.
+//
+//   runtime      'web' | 'browser-extension' | 'electron'
+//   environment  the build's verdict ('development' | 'testing' | 'production')
+//   version      the target's own package version, the release tag every error
+//                report carries as `<brand.id>@<version>` (#380)
+//   buildTime    the build stamp (ms)
+//   target       WHICH target this artifact IS, by name (#887)
+//   url          this target's own resolved public url (#588)
+//   dev          the local stack's resolved map: ports + the sibling website's
+//                origin, development builds only (#300/#262). The extension's
+//                live-reload port rides here too (#896), the one home of a
+//                local-stack number.
+const CLIENT_FACT_KEYS = ['runtime', 'environment', 'version', 'buildTime', 'target', 'url', 'dev'];
+
+/**
+ * Copy exactly `paths` out of a section (dot-paths, deep).
+ * @param {*} section - the resolved section value.
+ * @param {string[]} paths - dot-paths inside it.
+ * @returns {object|undefined} the picked sub-tree, or undefined when it is empty.
+ */
+function pickPaths(section, paths) {
+  if (!section || typeof section !== 'object') {
+    return undefined;
+  }
+
+  const picked = {};
+  let found = false;
+
+  for (const path of paths) {
+    const keys = path.split('.');
+    let source = section;
+    let missing = false;
+
+    for (const key of keys) {
+      if (!source || typeof source !== 'object' || !(key in source)) {
+        missing = true;
+        break;
+      }
+      source = source[key];
+    }
+    if (missing) continue;
+
+    let cursor = picked;
+    for (const key of keys.slice(0, -1)) {
+      cursor[key] = cursor[key] || {};
+      cursor = cursor[key];
+    }
+    cursor[keys[keys.length - 1]] = source;
+    found = true;
+  }
+
+  return found ? picked : undefined;
+}
+
+/**
+ * The subset of a resolved config a browser may see.
+ * @param {object} [resolved] - a resolved config (Manager.getConfig() output),
+ *   with this build's facts composed onto it.
+ * @returns {object} the blob every browser surface bakes as OMEGA_BUILD_JSON.config.
+ * @throws {Error} when a section that is about to ship carries a secret-shaped key.
+ */
+function clientConfig(resolved) {
+  const source = resolved || {};
+  const client = {};
+
+  for (const key of CLIENT_FACT_KEYS) {
+    if (key in source) client[key] = source[key];
+  }
+
+  for (const [section, rule] of Object.entries(CLIENT_SECTIONS)) {
+    if (!(section in source)) continue;
+
+    const value = rule === true ? source[section] : pickPaths(source[section], rule);
+    if (value === undefined) continue;
+
+    client[section] = value;
+  }
+
+  // A secret in here is not a value to drop: it is a config that should never
+  // have loaded, so it fails the build at the one place that would have
+  // published it.
+  const secrets = findSecretKeys(client);
+  if (secrets.length) {
+    throw new Error(
+      `[@omega.js/config] refusing to bake a browser config carrying secret-shaped keys: ${secrets.join(', ')}. `
+      + 'Secrets live in .env, never in config/omega.json5 (docs/shared/config.md).',
+    );
+  }
+
+  // The one home of the cancel-flow save offer's default (#268) is
+  // @omega.js/config, so the browser is handed the RESOLVED offer: the dialog a
+  // customer reads and the coupon the backend creates can never name different
+  // numbers.
+  if (client.payment) {
+    client.payment = { ...client.payment, winback: resolveWinbackOffer(client.payment) };
+  }
+
+  // Never an alias of the resolved config: what a bake stamps into an artifact
+  // cannot be something a later build step can still mutate. A JSON round trip
+  // and not structuredClone, because JSON is what a bake CAN carry: a page's
+  // resolved config arrives through a template data cascade that hangs
+  // functions and accessors off it, and those drop out here rather than
+  // crashing the build.
+  return JSON.parse(JSON.stringify(client));
+}
+
+module.exports = { clientConfig, CLIENT_FACT_KEYS };

package/dist/vendor/config/company.js

@@ -1,31 +1,350 @@
 /**
- * The company layer's ONE discovery rule.
+ * The company layer's ONE resolver
+ * ([#677](https://github.com/Omega-JS-Stack/omega/issues/677)).
  *
- * A brand managed by a company workspace carries `.omega/company.json` at its
- * root (stamped idempotently by company manage runs) pointing at the company
- * root. Everything that cascades — the config chain (load.js), the .env chain
- * (env.js), owner hooks (hooks.js) — resolves the company root through here,
- * so the stamp is read exactly one way.
+ * A brand joins its company with ONE typed key, outside `brand` (Ian
+ * 2026-09-12: "brand key is for things about this brand, and the
+ * parent/company/organization key is OUTSIDE of that"):
+ *
+ *   company: { id: 'itw-creative-works' }   // a sub-brand: the parent's brand.id
+ *   company: { id: 'self' }                 // the company brand itself
+ *
+ * The resolver fills that SAME object at load (`{ id, name, url, images,
+ * webhooks }`), so one name carries one shape at every level and no reader
+ * needs a fallback: a brand with no `company` key resolves to `{ id: null,
+ * name: brand.name, url: brand.url, images: {}, webhooks: true }`.
+ *
+ * `webhooks` is the one key beside `id` a brand TYPES (#677): `false` says the
+ * provider ACCOUNT is somebody else's and the manage walk never repoints its
+ * one account-level webhook. It is the brand's own statement, so it is read
+ * from the brand config at every branch, never from the company.
+ *
+ * The COMPANY TREE is a `company/` folder INSIDE the parent brand's repo,
+ * shaped like a brand (`company/config/omega.json5`, `company/.env`,
+ * `company/.omega/certificates/apple/`). Inheritance is ONE rule: a
+ * brand-level file the child lacks resolves from the parent's `company/` at the
+ * same relative path, through `file(relPath)`. Everything that cascades (the
+ * config chain in load.js, the .env chain in env.js, owner hooks in hooks.js,
+ * the desktop signing tree) asks that one function, so a NEW kind of inherited
+ * file costs zero code.
+ *
+ * WHERE the parent lives on this machine is a cache, never configuration: the
+ * machine registry `~/.omega/brands.json` (`OMEGA_HOME` overrides the home),
+ * keyed by `brand.id`, which every loadConfig() refreshes for its own brand.
+ * Nobody maintains it, and a parent that has never been loaded here is simply
+ * inheritance-off with one loud line.
+ *
+ * OFF-LAPTOP the tree never travels: the machine that dispatches a deploy
+ * resolves the company and writes `config/company-resolved.json5` beside the
+ * brand config (@omega.js/devkit's deploy snapshot), and a runner reads that
+ * generated layer instead of a registry it has no lines in.
  */
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
+const JSON5 = require('json5');
 
-// A brand's pointer at its company root.
-const COMPANY_MARKER = path.join('.omega', 'company.json');
+// 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
+// deploy snapshot, which is the only place a brand-wide generated file can sit
+// and still ride a mirror (git cannot re-include a path under an excluded
+// directory, and every brand ignores `.omega/` whole).
+const COMPANY_DIR = 'company';
+const COMPANY_RESOLVED_FILE = path.join('config', 'company-resolved.json5');
+
+// The machine registry: brand id to { root, name, url, updatedAt }. One file,
+// no other company-shaped state.
+const REGISTRY_FILE = 'brands.json';
+
+// `company: { id: 'self' }` is the company brand itself, kept visible on
+// purpose (Ian 2026-09-12: "dont retire parent field for parent brands, i like
+// 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');
+
+// 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();
 
 /**
- * The company root a brand points at via its .omega/company.json marker.
- * @param {string} brandRoot
- * @returns {string|null} Absolute company root, or null when unstamped/unreadable.
+ * 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).
+ * @returns {string} Absolute path.
  */
-function readCompanyRoot(brandRoot) {
+function omegaHome() {
+  return process.env.OMEGA_HOME || path.join(os.homedir(), '.omega');
+}
+
+/**
+ * The machine registry file.
+ * @returns {string} Absolute path to `<home>/brands.json`.
+ */
+function registryFile() {
+  return path.join(omegaHome(), REGISTRY_FILE);
+}
+
+/**
+ * Parse a JSON/JSON5 file, tolerantly: this whole module is a CACHE plus a
+ * parent's own public facts, and neither may ever fail a brand's load.
+ * @param {string} file - Absolute path.
+ * @returns {object|null} The parsed object, or null.
+ */
+function readJson(file) {
   try {
-    const marker = JSON.parse(fs.readFileSync(path.join(brandRoot, COMPANY_MARKER), 'utf8'));
-    return typeof marker.root === 'string' && marker.root ? marker.root : null;
+    const parsed = JSON5.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
   } catch {
     return null;
   }
 }
 
-module.exports = { readCompanyRoot, COMPANY_MARKER };
+/**
+ * A brand root's authored omega.json5.
+ * @param {string|null} root - Brand root.
+ * @returns {object|null}
+ */
+function readBrandConfig(root) {
+  return root ? readJson(path.join(root, 'config', 'omega.json5')) : null;
+}
+
+/**
+ * The whole machine registry.
+ * @returns {Object<string, { root: string, name: string, url: string, updatedAt: string }>}
+ */
+function readRegistry() {
+  return readJson(registryFile()) || {};
+}
+
+/**
+ * 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
+ * brands are on this machine maintains itself.
+ *
+ * IDEMPOTENT: a line whose root, name and url already match is left untouched
+ * (`updatedAt` is not churn). It NEVER throws: a read-only home, a racing
+ * writer, or a machine with no home directory at all is a registry that misses,
+ * which is inheritance-off, never a failed load.
+ *
+ * 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.
+ *
+ * @param {object} entry - The brand's own facts.
+ * @param {string} entry.id - `brand.id` (the key).
+ * @param {string} entry.root - The brand root on this machine.
+ * @param {string} [entry.name] - `brand.name`.
+ * @param {string} [entry.url] - `brand.url`.
+ * @returns {boolean} True when a line was written.
+ */
+function recordBrand({ id, root, name, url }) {
+  if (!id || !root) return false;
+
+  try {
+    const registry = readRegistry();
+    const current = registry[id];
+    const line = { root, name: name || null, url: url || null };
+
+    if (current && current.root === line.root && (current.name || null) === line.name && (current.url || null) === line.url) {
+      return false;
+    }
+
+    registry[id] = { ...line, updatedAt: new Date().toISOString() };
+
+    const live = Object.fromEntries(Object.entries(registry).filter(([, entry]) => entry && isDir(entry.root)));
+
+    fs.mkdirSync(omegaHome(), { recursive: true });
+    fs.writeFileSync(registryFile(), `${JSON.stringify(live, null, 2)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The generated layer an off-laptop run reads: what the dispatching machine
+ * resolved, written beside the brand config and carried by the deploy snapshot.
+ * @param {string|null} brandRoot
+ * @returns {{ config: object, company: object }|null}
+ */
+function readResolvedLayer(brandRoot) {
+  const generated = brandRoot ? readJson(path.join(brandRoot, COMPANY_RESOLVED_FILE)) : null;
+  return generated && generated.company ? generated : null;
+}
+
+/** A directory that is really there. */
+function isDir(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The one line a missing parent prints, once per company id per process.
+ * @param {string} id
+ */
+function warnMissing(id) {
+  if (warned.has(id)) return;
+  warned.add(id);
+  console.warn(`Company ${id} is not on this machine: inheritance off. Clone it and run any omega verb inside it once.`);
+}
+
+/**
+ * The company tree (`<root>/company`), when the root has one.
+ * @param {string|null} root
+ * @returns {string|null}
+ */
+function companyDir(root) {
+  const dir = root ? path.join(root, COMPANY_DIR) : null;
+  return dir && isDir(dir) ? dir : null;
+}
+
+/**
+ * The wordmark a company hands its brands: the company brand's OWN wordmark.
+ * @param {object} brand - A brand block.
+ * @returns {{ wordmark?: string }}
+ */
+function wordmarkOf(brand) {
+  const wordmark = brand && brand.images ? brand.images.wordmark : null;
+  return wordmark ? { wordmark } : {};
+}
+
+/**
+ * The resolver's answer, built around ONE inheritance rule.
+ * @param {object} facts - The company's id/name/url/images/root, the brand's
+ *   own `webhooks` statement, plus the generated layer's config when there is
+ *   no tree to read one from.
+ * @returns {object} The resolveCompany() shape.
+ */
+function answer({ id = null, name = null, url = null, images = {}, root = null, config = null, configFile = null, webhooks = true }) {
+  const dir = companyDir(root);
+
+  // The WHOLE inheritance rule: a brand-level file the child lacks resolves
+  // from the parent's company/ at the same relative path. Nothing per-kind.
+  const file = (relPath) => {
+    const candidate = dir && relPath ? path.join(dir, relPath) : null;
+    return candidate && fs.existsSync(candidate) ? candidate : null;
+  };
+
+  const layerFile = configFile || file(path.join('config', 'omega.json5'));
+
+  return {
+    id,
+    name: name || null,
+    url: url || null,
+    images: images || {},
+    // Typed boolean, default true: only an explicit `false` opts out.
+    webhooks: webhooks !== false,
+    root: root || null,
+    dir,
+    file,
+    // The company CONFIG layer itself, already parsed: read from the parent's
+    // company/config/omega.json5 here, handed over by the generated layer on a
+    // runner.
+    config: config || (layerFile ? readJson(layerFile) : null),
+    configFile: layerFile || null,
+  };
+}
+
+/**
+ * The company a brand belongs to, filled from its typed `company.id`.
+ *
+ * @param {string} brandRoot - The brand (or standalone-project) root.
+ * @param {object} [brandConfig] - The brand's authored config, when the caller
+ *   already has it (loadConfig does); read from the brand root otherwise.
+ * @returns {{ id: string|null, name: string|null, url: string|null, images: object, webhooks: boolean, root: string|null, dir: string|null, file: Function, config: object|null, configFile: string|null }}
+ *   `root` is the parent brand's root ON THIS MACHINE (null = inheritance off),
+ *   `file(relPath)` that path inside the parent's `company/` when it exists.
+ */
+function resolveCompany(brandRoot, brandConfig) {
+  const root = brandRoot ? path.resolve(brandRoot) : null;
+  const config = brandConfig || readBrandConfig(root) || {};
+  const brand = config.brand || {};
+  const id = config.company && typeof config.company.id === 'string' ? config.company.id.trim() : '';
+
+  // The brand's OWN statement, on every branch: whose provider account the
+  // manage walk may repoint (#677). Never the company's to answer.
+  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) {
+    return reply({ id: null, name: brand.name, url: brand.url });
+  }
+
+  // The company brand itself: its own company/ tree, its own public facts.
+  if (id === SELF) {
+    return reply({ id: SELF, name: brand.name, url: brand.url, images: wordmarkOf(brand), root });
+  }
+
+  const line = readRegistry()[id];
+  const parentRoot = line && typeof line.root === 'string' && isDir(line.root) ? line.root : null;
+
+  if (parentRoot) {
+    const parentBrand = (readBrandConfig(parentRoot) || {}).brand || {};
+
+    return reply({
+      id,
+      name: parentBrand.name || line.name,
+      url: parentBrand.url || line.url,
+      images: wordmarkOf(parentBrand),
+      root: parentRoot,
+    });
+  }
+
+  // Off this laptop: what the dispatching machine resolved rides beside the
+  // brand config. Never a tree, so `file()` answers null for everything.
+  const generated = readResolvedLayer(root);
+  if (generated) {
+    const company = generated.company || {};
+    return reply({
+      id: company.id || id,
+      name: company.name,
+      url: company.url,
+      images: company.images || {},
+      config: generated.config || {},
+      configFile: path.join(root, COMPANY_RESOLVED_FILE),
+    });
+  }
+
+  // A config that already CARRIES the facts: composeTargetConfig freezes the
+  // resolved company into a target's upload (the deployed backend has no
+  // registry, no company tree and no brand walk-up above it), so what the
+  // dispatching machine resolved is the answer here. A human never authors
+  // these keys: the loader refuses them in a brand file.
+  const frozen = config.company || {};
+  if (frozen.name || frozen.url || frozen.images) {
+    return reply({ id, name: frozen.name, url: frozen.url, images: frozen.images || {} });
+  }
+
+  // Known in the registry but the folder is gone: the cached public facts still
+  // stand, the tree does not.
+  if (line) {
+    return reply({ id, name: line.name, url: line.url });
+  }
+
+  warnMissing(id);
+  return reply({ id });
+}
+
+module.exports = {
+  resolveCompany,
+  recordBrand,
+  readRegistry,
+  registryFile,
+  COMPANY_DIR,
+  COMPANY_RESOLVED_FILE,
+  COMPANY_SELF: SELF,
+};