Coordinating Layer Order Across Independently Deployed Apps

/* The contract, as the shell declares it today. */
@layer reset, vendor, base, theme, ds, apps, utilities, overrides;

{
  "name": "@org/cascade-contract",
  "version": "3.0.0",
  "//": "WHY semver on a CSS contract: a reorder changes behaviour for every consumer, which is exactly what a major version is for — even though no exported symbol changed.",
  "layers": ["reset", "vendor", "base", "theme", "ds", "apps", "utilities", "overrides"],
  "appOrder": ["catalog", "search", "checkout", "account"]
}

/* ADDITIVE — safe. A new band after the last one only adds priority above
   everything that already exists, so no existing relationship changes.
   @layer …, utilities, overrides, experiments;   ← minor version */

/* MOVE — breaking. Relationships between existing rules change, and the
   symptom is a visual regression rather than a build failure.
   @layer reset, vendor, …    →    @layer vendor, reset, …   ← major */

/* REMOVE — breaking, and silently so. Any app still writing into the deleted
   name creates it implicitly at the END of the stack, where it now outranks
   everything. This is the most dangerous of the three. ← major */

1. Shell deploys contract 3.1.0        — the new band exists but is empty
2. Remotes upgrade at their own pace   — each writes into it when ready
3. Old band deprecated in 3.2.0        — declared but documented as legacy
4. Telemetry confirms zero writers     — see Step 4
5. Shell deploys 4.0.0                 — the old band is removed

// WHY shell-first: a remote writing into a layer the shell has not declared
// creates it implicitly at the END of the stack, above everything. The
// reverse order — remote first — is the one that produces an incident.

// packages/cascade-contract/src/verify.js
// WHY sample rather than run on every load: the walk is cheap but not free,
// and a mismatch affects every session equally, so 1% finds it immediately.
import contract from '../contract.json' assert { type: 'json' };

export function reportLayerOrder({ sampleRate = 0.01, report } = {}) {
  if (Math.random() > sampleRate) return;

  const names = [];
  const walk = (rules) => {
    for (const r of rules) {
      const kind = r.constructor.name;
      if (kind === 'CSSLayerStatementRule') names.push(...r.nameList);
      else if (kind === 'CSSLayerBlockRule') {
        if (r.name) names.push(r.name);
        walk(r.cssRules);
      } else if (r.cssRules) walk(r.cssRules);
    }
  };
  for (const s of document.styleSheets) {
    try { walk(s.cssRules); } catch { /* cross-origin */ }
  }

  const actual = [...new Set(names)];
  const topLevel = actual.filter((n) => !n.includes('.'));
  const unexpected = topLevel.filter((n) => !contract.layers.includes(n));
  const ordered = contract.layers.filter((n) => topLevel.includes(n));

  // WHY compare the FILTERED expected list: an app that has not deployed yet
  // legitimately leaves a declared band unused, and that is not a mismatch.
  const drift = JSON.stringify(ordered) !==
                JSON.stringify(topLevel.filter((n) => contract.layers.includes(n)));

  if (unexpected.length || drift) {
    report?.({ event: 'cascade_contract_mismatch', expected: contract.layers,
               actual: topLevel, unexpected, version: contract.version });
  }
}

// Paste into the console on production. Compare against contract.layers.
[...document.styleSheets].flatMap((s) => {
  try { return [...s.cssRules]; } catch { return []; }
}).filter((r) => r.constructor.name === 'CSSLayerStatementRule')
  .flatMap((r) => r.nameList).filter((n) => !n.includes('.'));

// packages/cascade-contract/contract.json — the single versioned artefact.
{
  "version": "3.1.0",
  "layers": ["reset", "vendor", "base", "theme", "ds", "apps",
             "utilities", "overrides"],
  "appOrder": ["catalog", "search", "checkout", "account"],
  "deprecated": {
    "legacy-ds": {
      "since": "3.1.0",
      "removeIn": "4.0.0",
      "replacement": "ds",
      "note": "still declared so writes from un-upgraded remotes land in the reviewed position rather than creating a new top-level layer"
    }
  }
}

// packages/cascade-contract/src/index.js
import contract from '../contract.json' assert { type: 'json' };

/** WHY generated: the shell's CSS and the contract cannot drift when one is
 *  produced from the other at build time. */
export function layerStatements() {
  const top = [...contract.layers,
               ...Object.keys(contract.deprecated ?? {})].join(', ');
  const apps = contract.appOrder.map((id) => `apps.${id}`).join(', ');
  return `@layer ${top};\n@layer ${apps};\n`;
}

/** WHY a runtime check rather than only a build check: the shell and the
 *  remotes are built separately, so the only place the combination exists is
 *  a real browser session. */
export function verifyLiveOrder({ sampleRate = 0.01, report } = {}) {
  if (Math.random() > sampleRate) return;

  const seen = [];
  const walk = (rules) => {
    for (const r of rules) {
      const kind = r.constructor.name;
      if (kind === 'CSSLayerStatementRule') seen.push(...r.nameList);
      else if (kind === 'CSSLayerBlockRule') {
        if (r.name) seen.push(r.name);
        walk(r.cssRules);
      } else if (r.cssRules) walk(r.cssRules);
    }
  };
  for (const s of document.styleSheets) {
    try { walk(s.cssRules); } catch { /* cross-origin sheet — skip */ }
  }

  const known = new Set([...contract.layers,
                         ...Object.keys(contract.deprecated ?? {})]);
  const topLevel = [...new Set(seen)].filter((n) => !n.includes('.'));
  const unexpected = topLevel.filter((n) => !known.has(n));

  // WHY report even when nothing is wrong is NOT done: a quiet check that
  // only speaks on failure keeps the signal readable on a dashboard.
  if (unexpected.length) {
    report?.({
      event: 'cascade_contract_mismatch',
      contractVersion: contract.version,
      unexpectedLayers: unexpected,
      observedOrder: topLevel,
    });
  }
}