@omega.js/manager 0.1.0

package/dist/vendor/account/features.js

@@ -0,0 +1,220 @@
+/**
+ * features.js — the ONE reading of the features contract
+ * ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)).
+ *
+ * A feature is DEFINED once, in the config's top-level `features` catalog:
+ *
+ *   features: {
+ *     saves:   { name: 'Saves', icon: 'feather', definition: '…',
+ *                usage: { pace: 'daily', mirror: ['teams'] } },
+ *     support: { name: 'Priority support', icon: 'headset' },
+ *   }
+ *
+ * A `usage` block makes the entry COUNTED (metered per user); an entry without
+ * one is a PERK, never counted. Each product then names only its VALUE:
+ * `features: { saves: 100, support: true }` — a number on a counted feature
+ * (the MONTHLY limit, -1 unlimited), true/false/a string on a perk.
+ *
+ * This module is the shared home of every derivation both sides make from
+ * those two halves plus a user's stored counters — the backend's `consume`
+ * gate and the browser's account page must never disagree about what a user's
+ * limit is:
+ *   - the EFFECTIVE limit, where an admin-written `usage.overrides.<feature>`
+ *     on the user doc wins over the plan's number;
+ *   - the DAY share, `ceil(limit / days in this month)`, so a monthly quota
+ *     cannot be burned on day one (pacing is the default; `pace: false` opts
+ *     out to a plain monthly counter);
+ *   - the two counters a counted feature carries per user, month and day.
+ *
+ * -1 is the unlimited sentinel everywhere it can appear: a limit, a day share,
+ * and a remaining count.
+ */
+
+// Where a user's counters and overrides live on the account document.
+const USAGE_KEY = 'usage';
+const OVERRIDES_KEY = 'overrides';
+
+/**
+ * Is this catalog entry COUNTED? A `usage` block is what meters a feature;
+ * everything else is a perk the plan either includes or does not.
+ * @param {object} entry - a top-level `features` catalog entry
+ * @returns {boolean}
+ */
+function isCountedFeature(entry) {
+  return !!(entry && typeof entry === 'object' && entry.usage && typeof entry.usage === 'object' && !Array.isArray(entry.usage));
+}
+
+/**
+ * Is this feature paced by day? Pacing is the DEFAULT on every counted
+ * feature; `usage: { pace: false }` opts out to a plain monthly counter.
+ * @param {object} entry - a catalog entry
+ * @returns {boolean}
+ */
+function isPacedFeature(entry) {
+  return isCountedFeature(entry) && entry.usage.pace !== false;
+}
+
+/**
+ * The document kinds a counted feature's counters mirror onto, declared in the
+ * catalog rather than at the call site.
+ * @param {object} entry - a catalog entry
+ * @returns {string[]} the declared kinds, or []
+ */
+function featureMirrors(entry) {
+  return isCountedFeature(entry) && Array.isArray(entry.usage.mirror) ? entry.usage.mirror : [];
+}
+
+/**
+ * Days in the month the given date falls in.
+ * @param {Date} [date] - defaults to now
+ * @returns {number}
+ */
+function daysInMonth(date) {
+  const d = date || new Date();
+  return new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate();
+}
+
+/**
+ * A month limit's share of ONE day: ceil(limit / days in this month), so a
+ * quota of 100 in a 31-day month allows 4 a day and never 100 on the 1st.
+ * Unlimited stays unlimited; nothing stays nothing.
+ * @param {number} limit - the effective MONTHLY limit (-1 unlimited)
+ * @param {Date} [date] - the day being paced, defaults to now
+ * @returns {number} the day's share (-1 unlimited)
+ */
+function dayShare(limit, date) {
+  if (!Number.isFinite(limit) || limit === 0) return 0;
+  if (limit < 0) return -1;
+  return Math.ceil(limit / daysInMonth(date));
+}
+
+/**
+ * The per-user override for a feature, when the account carries one. Written
+ * by admins only (the user doc's `usage` key is a framework field the security
+ * rules deny a client), and it WINS over the plan's number — extra credits
+ * granted to one account, not a second pricing tier.
+ * @param {object} account - the user document
+ * @param {string} id - feature id
+ * @returns {number|null} the override, or null when there is none
+ */
+function featureOverride(account, id) {
+  const value = account && account[USAGE_KEY] && account[USAGE_KEY][OVERRIDES_KEY]
+    ? account[USAGE_KEY][OVERRIDES_KEY][id]
+    : undefined;
+
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * What a product promises for one feature: its raw value from the product's
+ * `features` map. A product that never names the feature promises nothing.
+ * @param {object} product - a `payment.products` entry
+ * @param {string} id - feature id
+ * @returns {*} the value, or undefined
+ */
+function productFeatureValue(product, id) {
+  const values = product && product.features;
+  return values && typeof values === 'object' && !Array.isArray(values) ? values[id] : undefined;
+}
+
+/**
+ * The counters a user carries for one feature. The stored shape is
+ * `usage.<id>.{ monthly, daily, total, last }` — monthly and daily are the two
+ * the gate reads, total never resets, last records when it moved.
+ * @param {object} account - the user document
+ * @param {string} id - feature id
+ * @returns {{ monthly: number, daily: number, total: number }}
+ */
+function featureCounters(account, id) {
+  const stored = (account && account[USAGE_KEY] && account[USAGE_KEY][id]) || {};
+  const read = (key) => (typeof stored[key] === 'number' && Number.isFinite(stored[key]) ? stored[key] : 0);
+
+  return { monthly: read('monthly'), daily: read('daily'), total: read('total') };
+}
+
+/**
+ * How many of a limit are left, given what is used. Unlimited stays unlimited.
+ * @param {number} limit - the limit (-1 unlimited)
+ * @param {number} used - the counter
+ * @returns {number} what remains (-1 unlimited), never below zero
+ */
+function remaining(limit, used) {
+  if (limit < 0) return -1;
+  return Math.max(0, limit - used);
+}
+
+/**
+ * Resolve ONE feature against a catalog, a product and an account: everything
+ * a gate or an account page needs to speak about it in one object.
+ *
+ * @param {string} id - feature id
+ * @param {object} options
+ * @param {object} [options.catalog] - the top-level `features` catalog
+ * @param {object} [options.product] - the account's resolved product
+ * @param {object} [options.account] - the user document (counters + overrides)
+ * @param {Date} [options.now] - the day being paced, defaults to now
+ * @returns {object} { id, name, icon, definition, counted, paced, mirror,
+ *   value, limit, planLimit, override, used, left, total,
+ *   day: { limit, used, left } }
+ */
+function resolveFeature(id, options) {
+  options = options || {};
+
+  const entry = (options.catalog || {})[id] || null;
+  const counted = isCountedFeature(entry);
+  const value = productFeatureValue(options.product, id);
+  const counters = featureCounters(options.account, id);
+  const override = featureOverride(options.account, id);
+
+  const planLimit = counted && typeof value === 'number' ? value : 0;
+  const limit = counted && override !== null ? override : planLimit;
+  const paced = isPacedFeature(entry);
+  const dayLimit = paced ? dayShare(limit, options.now) : -1;
+
+  return {
+    id: id,
+    name: (entry && entry.name) || id,
+    icon: (entry && entry.icon) || null,
+    definition: (entry && entry.definition) || null,
+    counted: counted,
+    paced: paced,
+    mirror: featureMirrors(entry),
+    value: counted ? limit : value,
+    limit: limit,
+    planLimit: planLimit,
+    override: override,
+    used: counters.monthly,
+    left: remaining(limit, counters.monthly),
+    total: counters.total,
+    day: {
+      limit: dayLimit,
+      used: counters.daily,
+      left: remaining(dayLimit, counters.daily),
+    },
+  };
+}
+
+/**
+ * Resolve every feature the catalog defines, in CATALOG order — the row order
+ * every surface renders (pricing rows, account bars).
+ * @param {object} options - same options as resolveFeature
+ * @returns {object[]} one resolved feature per catalog entry
+ */
+function resolveFeatures(options) {
+  options = options || {};
+
+  return Object.keys(options.catalog || {}).map((id) => resolveFeature(id, options));
+}
+
+module.exports = {
+  isCountedFeature,
+  isPacedFeature,
+  featureMirrors,
+  featureOverride,
+  featureCounters,
+  productFeatureValue,
+  daysInMonth,
+  dayShare,
+  resolveFeature,
+  resolveFeatures,
+};

package/dist/vendor/account/index.js

@@ -0,0 +1,53 @@
+/**
+ * @omega.js/account — the single source of truth for the OMEGA user/account schema.
+ *
+ * Today the account shape lives in two drifted places: @omega.js/backend's
+ * src/manager/helpers/user.js (canonical — schema engine + tokens) and
+ * @omega.js/client's DEFAULT_ACCOUNT in modules/auth.js (hand-rolled deep-merge,
+ * missing flags/activity/personal branches and `everPaid`). This package
+ * unifies them; each framework becomes a thin wrapper (@omega.js/backend keeps its
+ * `new User(Manager, settings).properties` API, @omega.js/client keeps
+ * `resolveAccount(rawData, firebaseUser)`).
+ *
+ * resolveAccount(data, options):
+ *   options.generators — { uuid, randomId, apiKey } value generators for the
+ *     '$uuid'/'$randomId'/'$apiKey' schema tokens. @omega.js/backend injects real ones
+ *     (uuid v4, Utilities().randomId, uid-generator); the frontend passes none
+ *     and the fields resolve to null (real values always come from the backend).
+ *   options.user — optional auth-user overlay ({ uid, email }): fills
+ *     account.auth identity when the doc doesn't carry it (@omega.js/client's
+ *     resolveAccount(rawData, firebaseUser) semantic).
+ */
+const USER_SCHEMA = require('./schema.js');
+const { resolve } = require('./engine.js');
+const resolveSubscription = require('./subscription.js');
+const features = require('./features.js');
+
+function resolveAccount(data, options) {
+  options = options || {};
+
+  // Time context — byte-identical to @omega.js/backend's node-powertools timestamps:
+  // powertools.timestamp(d, { output: 'string' }) === d.toISOString(),
+  // powertools.timestamp(d, { output: 'unix' }) === floor(ms / 1000).
+  const now = new Date();
+  const ctx = {
+    generators: options.generators || {},
+    now: now.toISOString(),
+    nowUNIX: Math.floor(now.getTime() / 1000),
+    oldDate: new Date(0).toISOString(),
+    oldDateUNIX: 0,
+  };
+
+  const account = resolve(USER_SCHEMA, data || {}, ctx);
+
+  // Auth-user overlay (frontend semantic): identity from the signed-in Firebase
+  // user when the stored doc doesn't already carry it
+  if (options.user) {
+    account.auth.uid = account.auth.uid || options.user.uid || null;
+    account.auth.email = account.auth.email || options.user.email || null;
+  }
+
+  return account;
+}
+
+module.exports = { USER_SCHEMA, resolveAccount, resolveSubscription, ...features };

package/dist/vendor/account/schema.js

@@ -0,0 +1,272 @@
+/**
+ * USER_SCHEMA — the canonical OMEGA user/account schema (pure data, no logic).
+ *
+ * Extracted verbatim from @omega.js/backend's src/manager/helpers/user.js, which is
+ * the authoritative shape (@omega.js/client's DEFAULT_ACCOUNT had drifted from it).
+ *
+ * Each leaf field is { type, default, nullable }
+ * Special keys:
+ *   $passthrough  — preserve all existing keys from input, don't strip unknowns
+ *   $template     — shape applied to every dynamic key in a $passthrough object
+ *   '$template'   — (string value) reference to parent's $template
+ *   '$timestamp'  — shorthand for { timestamp, timestampUNIX } defaulting to epoch
+ *   '$timestamp:now' — same but defaults to current time
+ *   '$uuid', '$randomId', '$apiKey', '$oldDate' — resolved at runtime (generators
+ *   are injected by the host — see engine.js; absent generators resolve to null)
+ */
+
+/**
+ * One attribution TOUCH — a single visit's campaign context, shared by
+ * `attribution.first` and `attribution.last`
+ * ([#384](https://github.com/Omega-JS-Stack/omega/issues/384)). `tags` holds the
+ * utm set and `clickIds` the ad-platform click ids (fbclid/gclid/…), both
+ * passthrough because the platforms keep adding params. The schema is read-only
+ * to the engine, so one object serves both slots.
+ */
+const ATTRIBUTION_TOUCH = {
+  tags: { $passthrough: true },
+  clickIds: { $passthrough: true },
+  referrer: { type: 'string', default: null, nullable: true },
+  url: { type: 'string', default: null, nullable: true },
+  page: { type: 'string', default: null, nullable: true },
+  timestamp: { type: 'string', default: null, nullable: true },
+};
+
+const USER_SCHEMA = {
+  auth: {
+    uid: { type: 'string', default: null, nullable: true },
+    email: { type: 'string', default: null, nullable: true },
+    temporary: { type: 'boolean', default: false },
+  },
+  subscription: {
+    product: {
+      id: { type: 'string', default: 'basic' },
+      name: { type: 'string', default: 'Basic' },
+    },
+    status: { type: 'string', default: 'active' },
+    expires: '$timestamp',
+    trial: {
+      claimed: { type: 'boolean', default: false },
+      expires: '$timestamp',
+      // How the trial ENDED: 'converted' | 'lapsed' | null (still running, or never
+      // answered). `claimed` says only that a trial happened — a converted trial and a
+      // lapsed one carry identical dates — so this is the one stored conversion signal.
+      // Stamped by the trial-lapse sweep once the provider confirms which it was.
+      outcome: { type: 'string', default: null, nullable: true },
+    },
+    cancellation: {
+      pending: { type: 'boolean', default: false },
+      date: '$timestamp',
+    },
+    payment: {
+      provider: { type: 'string', default: null, nullable: true },
+      orderId: { type: 'string', default: null, nullable: true },
+      resourceId: { type: 'string', default: null, nullable: true },
+      frequency: { type: 'string', default: null, nullable: true },
+      price: { type: 'number', default: 0 },
+      startDate: '$timestamp',
+      updatedBy: {
+        event: {
+          name: { type: 'string', default: null, nullable: true },
+          id: { type: 'string', default: null, nullable: true },
+        },
+        date: '$timestamp',
+      },
+    },
+    // The discount riding the subscription right now
+    // ([#325](https://github.com/Omega-JS-Stack/omega/issues/325)). Shaped as a
+    // discount-codes validate() RESULT — the one shape the whole payment stack
+    // already speaks — so the billing card reads exactly what the apply route
+    // wrote, and neither side learns a second spelling. `valid: false` (the
+    // default) IS "no discount": absent and denied read the same everywhere.
+    //
+    // Both shapes are always present and default to 0, unlike a fresh validate()
+    // result which omits the one it is not: this node is MERGED onto a document
+    // that may already carry a discount, and a percent claim landing on a stored
+    // amount would otherwise be read as the older, wrong number.
+    //
+    // `source` is what makes it safe to read as a CLAIM. Today only the winback
+    // claim writes this node; a code typed at checkout will set the same node
+    // when checkout starts writing it, and a winback pitch suppressed by someone
+    // else's promo is an offer silently withheld — so the node says which system
+    // applied it ('winback' | 'checkout'), and only 'winback' is the claimed
+    // signal the cancel flow gates on.
+    //
+    // `resourceId` is the subscription the discount was applied TO, stamped at
+    // claim time ([#333](https://github.com/Omega-JS-Stack/omega/issues/333)).
+    // It is what makes the node clearable: the unified webhook write carries no
+    // discount key, so a merge preserves this node forever, and a customer who
+    // churned and resubscribed carried a spent claim into the NEW subscription,
+    // where `source: 'winback'` reads as "already claimed" and silently retires
+    // an offer the backend would grant again. The webhook pipeline compares the
+    // stamp against the subscription each event is about and CLEARS the node
+    // (back to these defaults) on a mismatch: a new subscription is a clean
+    // slate. An unstamped node (written before the stamp existed) is read as
+    // belonging to the subscription it is found on, because nothing can prove
+    // otherwise and no live discount is ever taken away on a guess, and the
+    // pipeline stamps it there, so it clears on the next resubscribe like any
+    // other.
+    discount: {
+      valid: { type: 'boolean', default: false },
+      code: { type: 'string', default: null, nullable: true },
+      percent: { type: 'number', default: 0 },
+      amount: { type: 'number', default: 0 },
+      duration: { type: 'string', default: null, nullable: true },
+      source: { type: 'string', default: null, nullable: true },
+      resourceId: { type: 'string', default: null, nullable: true },
+    },
+  },
+  roles: {
+    $passthrough: true,
+    admin: { type: 'boolean', default: false },
+    betaTester: { type: 'boolean', default: false },
+    developer: { type: 'boolean', default: false },
+  },
+  flags: {
+    $passthrough: true,
+    signupProcessed: { type: 'boolean', default: false },
+  },
+  affiliate: {
+    code: { type: 'string', default: '$randomId' },
+    referrals: { type: 'array', default: [] },
+  },
+  metadata: {
+    created: '$timestamp:now',
+    updated: '$timestamp:now',
+  },
+  activity: {
+    geolocation: {
+      ip: { type: 'string', default: null, nullable: true },
+      continent: { type: 'string', default: null, nullable: true },
+      country: { type: 'string', default: null, nullable: true },
+      region: { type: 'string', default: null, nullable: true },
+      city: { type: 'string', default: null, nullable: true },
+      latitude: { type: 'number', default: 0 },
+      longitude: { type: 'number', default: 0 },
+    },
+    client: {
+      language: { type: 'string', default: null, nullable: true },
+      mobile: { type: 'boolean', default: false },
+      device: { type: 'string', default: null, nullable: true },
+      platform: { type: 'string', default: null, nullable: true },
+      browser: { type: 'string', default: null, nullable: true },
+      vendor: { type: 'string', default: null, nullable: true },
+      runtime: { type: 'string', default: null, nullable: true },
+      userAgent: { type: 'string', default: null, nullable: true },
+      url: { type: 'string', default: null, nullable: true },
+    },
+  },
+  api: {
+    clientId: { type: 'string', default: '$uuid' },
+    privateKey: { type: 'string', default: '$apiKey' },
+  },
+  // The documents this account owns, by KIND: `{ teams: ['team-abc'] }`
+  // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)). A counted
+  // feature's catalog entry names the kinds its counters mirror onto
+  // (`usage: { mirror: ['teams'] }`), and this is what resolves a kind to real
+  // document paths — so a mirror is declared once in config instead of
+  // re-derived at every call site. Server-written like `usage`: a client that
+  // could write it could point another account's counters at its own doc.
+  owns: {
+    $passthrough: true,
+  },
+  usage: {
+    $passthrough: true,
+    // Admin-granted extra credits, feature id → number
+    // ([#647](https://github.com/Omega-JS-Stack/omega/issues/647)). Declared
+    // HERE so the sibling `$template` never resolves it as a counter block:
+    // it is a map of limits, not a map of counts. `usage` is a framework field
+    // the security rules deny every client, so an override can only ever be
+    // server-written — which is what makes it trustworthy as a limit.
+    overrides: { $passthrough: true },
+    $template: {
+      monthly: { type: 'number', default: 0 },
+      daily: { type: 'number', default: 0 },
+      total: { type: 'number', default: 0 },
+      // When the counter last moved. The old `id` field went with the retired
+      // `increment(name, value, { id })` option (#647): nothing writes it now,
+      // and a schema field nothing fills reads as a fact that is always null.
+      last: {
+        timestamp: { type: 'string', default: '$oldDate' },
+        timestampUNIX: { type: 'number', default: 0 },
+      },
+    },
+  },
+  personal: {
+    birthday: '$timestamp',
+    gender: { type: 'string', default: null, nullable: true },
+    location: {
+      country: { type: 'string', default: null, nullable: true },
+      region: { type: 'string', default: null, nullable: true },
+      city: { type: 'string', default: null, nullable: true },
+      postalCode: { type: 'string', default: null, nullable: true },
+      street: { type: 'string', default: null, nullable: true },
+    },
+    name: {
+      first: { type: 'string', default: null, nullable: true },
+      last: { type: 'string', default: null, nullable: true },
+    },
+    company: {
+      name: { type: 'string', default: null, nullable: true },
+      position: { type: 'string', default: null, nullable: true },
+    },
+    telephone: {
+      countryCode: { type: 'number', default: 0 },
+      national: { type: 'number', default: 0 },
+    },
+  },
+  connections: {
+    $passthrough: true,
+  },
+  attribution: {
+    affiliate: {
+      code: { type: 'string', default: null, nullable: true },
+      timestamp: { type: 'string', default: null, nullable: true },
+      url: { type: 'string', default: null, nullable: true },
+      page: { type: 'string', default: null, nullable: true },
+    },
+    // The touch model: `first` is the visit that first brought the user here,
+    // written once and never overwritten; `last` is the newest TAGGED visit. No
+    // expiry — the timestamps carry any read-time lookback window. Replaces the
+    // single `utm` blob outright (no dual-read).
+    first: ATTRIBUTION_TOUCH,
+    last: ATTRIBUTION_TOUCH,
+  },
+  // The tracking-consent snapshot the client captured, stored verbatim: passthrough
+  // because this layer never interprets it — the consent module owns its shape. NOT
+  // the same thing as `consent` below, which is the legal/marketing decision.
+  trackingConsent: {
+    $passthrough: true,
+  },
+  consent: {
+    legal: {
+      status: { type: 'string', default: 'revoked' },
+      grantedAt: {
+        timestamp: { type: 'string', default: null, nullable: true },
+        timestampUNIX: { type: 'number', default: null, nullable: true },
+        source: { type: 'string', default: null, nullable: true },
+        ip: { type: 'string', default: null, nullable: true },
+        text: { type: 'string', default: null, nullable: true },
+      },
+    },
+    marketing: {
+      status: { type: 'string', default: 'revoked' },
+      grantedAt: {
+        timestamp: { type: 'string', default: null, nullable: true },
+        timestampUNIX: { type: 'number', default: null, nullable: true },
+        source: { type: 'string', default: null, nullable: true },
+        ip: { type: 'string', default: null, nullable: true },
+        text: { type: 'string', default: null, nullable: true },
+      },
+      revokedAt: {
+        timestamp: { type: 'string', default: null, nullable: true },
+        timestampUNIX: { type: 'number', default: null, nullable: true },
+        source: { type: 'string', default: null, nullable: true },
+        ip: { type: 'string', default: null, nullable: true },
+        text: { type: 'string', default: null, nullable: true },
+      },
+    },
+  },
+};
+
+module.exports = USER_SCHEMA;

package/dist/vendor/account/subscription.js

@@ -0,0 +1,38 @@
+/**
+ * resolveSubscription — extracted verbatim from @omega.js/backend's User.resolveSubscription
+ * (the superset: @omega.js/client's drifted copy lacked `everPaid`).
+ *
+ * Resolves calculated subscription fields that require derivation logic.
+ * Raw data (product.id, status, trial, cancellation) is on the account directly.
+ * Returns: { plan, active, trialing, cancelling, everPaid }
+ * - plan: the plan ID the user effectively has access to RIGHT NOW ('basic' if cancelled/suspended)
+ * - active: user has active access (active, trialing, or cancelling)
+ * - trialing: user is in an active trial (status is 'active' but trial hasn't expired)
+ * - cancelling: cancellation is pending (status is 'active' but cancellation.pending is true)
+ * - everPaid: user has had a paid subscription at some point (payment.startDate exists)
+ */
+function resolveSubscription(account) {
+  const subscription = (account?.subscription || account?.properties?.subscription) || {};
+  const productId = subscription.product?.id || 'basic';
+
+  let trialing = false;
+  let cancelling = false;
+
+  if (productId !== 'basic' && subscription.status === 'active') {
+    trialing = !!(subscription.trial?.claimed
+      && subscription.trial?.expires?.timestampUNIX > Math.floor(Date.now() / 1000));
+    cancelling = !trialing && !!subscription.cancellation?.pending;
+  }
+
+  const active = (productId !== 'basic' && subscription.status === 'active');
+
+  return {
+    plan: active ? productId : 'basic',
+    active,
+    trialing,
+    cancelling,
+    everPaid: (subscription.payment?.startDate?.timestampUNIX || 0) > 0,
+  };
+}
+
+module.exports = resolveSubscription;

package/dist/vendor/config/company.js

@@ -0,0 +1,31 @@
+/**
+ * The company layer's ONE discovery rule.
+ *
+ * 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.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// A brand's pointer at its company root.
+const COMPANY_MARKER = path.join('.omega', 'company.json');
+
+/**
+ * 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.
+ */
+function readCompanyRoot(brandRoot) {
+  try {
+    const marker = JSON.parse(fs.readFileSync(path.join(brandRoot, COMPANY_MARKER), 'utf8'));
+    return typeof marker.root === 'string' && marker.root ? marker.root : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { readCompanyRoot, COMPANY_MARKER };