@forgecart/cli 2.202609221621.0 → 2.202609240732.0

package/templates/storefront/src/app/%5F%5Fforge_beacon/route.ts

@@ -25,12 +25,55 @@
 
 const BEACON_PORT = process.env.FORGE_BEACON_PORT ?? '3002';
 
+/**
+ * The revision the reporting page was SERVED at, lifted out of the forwarded
+ * body for the log line below, or `null` when the report is untagged.
+ *
+ * Reads the body it is ALREADY forwarding verbatim rather than re-deriving
+ * anything: the value was stamped into the document at render time, and this
+ * handler is a forwarder, not a second opinion. The parse is guarded because a
+ * malformed body must not change what this route does — the forward still
+ * happens and the client still gets its 204, exactly as before. `JSON.parse` is
+ * the one throw on this path and it carries no code to classify, which is why it
+ * is caught here and nowhere else (`instrumentation.ts` swallows its own boot
+ * failure in the same template for the same reason); judging the payload stays
+ * the receiver's job.
+ */
+function servedRevision(body: string): string | null {
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (typeof parsed !== 'object' || parsed === null) return null;
+    const value = (parsed as { atRevision?: unknown }).atRevision;
+    if (typeof value !== 'string' || value.length === 0) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
 export async function POST(request: Request): Promise<Response> {
   if (process.env.NODE_ENV !== 'development') {
     return new Response(null, { status: 404 });
   }
 
   const body = await request.text();
+  // Make the dev-server's output ring revision-attributable (#847): this line is
+  // written to the ring the supervisor retains and `TailServerLogs` serves, so a
+  // human or the recovery brain reading the ring can tell WHICH tree a
+  // browser-surfaced crash belongs to instead of guessing from timing.
+  //
+  // It deliberately carries the revision and NOTHING ELSE — no message, no stack,
+  // no route. The ambient scanner matches dev-server output case-insensitively
+  // against RUNTIME_ERROR_PATTERNS ('error:', 'typeerror', 'unhandled', …;
+  // `runtime-error-scanner.types.ts`), so echoing the reported message here would
+  // put the crash text INTO the stream that scanner reads and fold a second,
+  // independent ambient error for the very report already on its way to the
+  // receiver — a self-inflicted double-fire. An untagged report stays silent
+  // rather than logging a placeholder, which keeps today's output byte-identical
+  // for every producer that does not stamp (the server `onRequestError` path
+  // never reaches this route at all — it POSTs the receiver directly).
+  const revision = servedRevision(body);
+  if (revision !== null) console.log(`[forge-beacon browser rev=${revision}]`);
   // Forward server-side to the loopback receiver. A delivery failure is swallowed —
   // the beacon is a best-effort backstop, never a hard dependency of the page — but
   // the client still gets a clean 204 so it never retries against a flapping pod.

package/templates/storefront/src/app/layout.tsx

@@ -10,7 +10,9 @@ import { LocaleLink } from '../components/LocaleLink';
 import { CartProvider } from '../lib/cart-context';
 import { getRequestLocale } from '../lib/locale/request-binding';
 import { shellMetadata } from '../lib/seo/metadata';
+import { getSiteVerifications } from '../lib/seo/site-verification';
 import { getBrowserShopConfig } from '../lib/shop-config';
+import { FORGE_REVISION_META, resolveLiveRevision } from '../server/forge/live-revision';
 
 import './globals.css';
 
@@ -34,10 +36,43 @@ import './globals.css';
  * It reads the SAME resolution the layout body reads below — React's request
  * cache makes `getRequestLocale()` one channel read per request no matter how
  * many callers there are, so the floor costs nothing extra.
+ *
+ * The site-verification placements (#1530) are read on the same request cache
+ * and handed to the SAME composer, so `lib/seo/metadata.ts` stays the only
+ * thing in this template that turns a placement into a `<meta>`: the
+ * alternative — a hand-written tag in the markup below — would be a second
+ * emitter with its own idea of when a placement is servable. They ride the
+ * FLOOR rather than a route, because the verifier chooses which page it fetches
+ * and a tag on only some of them is a verification that works until it does not.
+ *
+ * It also carries the DEV-ONLY revision stamp (#847). The tag has to be written
+ * where the page is RENDERED, because that is the only moment that knows which
+ * tree the shopper is actually looking at: the browser beacon reads it back at
+ * throw time, so a promote landing between serve and throw can no longer make
+ * the report blame the new revision for the old one's crash. It rides
+ * `generateMetadata` rather than a `<meta>` in the JSX below because arbitrary
+ * head tags are what `other` is for, and the shell's own metadata contract then
+ * stays untouched — the stamp is spread ON TOP of `shellMetadata`'s answer and
+ * adds a key no SEO surface reads.
+ *
+ * Dev-gated at this call site, like every other file in the beacon path: the
+ * literal `NODE_ENV` check is what lets a production build eliminate the
+ * resolution entirely, so a deployed storefront emits no tag and leaks no
+ * revision. Unresolvable is a NORMAL answer and means no tag — the report then
+ * arrives untagged and the receiver keeps its existing behaviour.
  */
 export async function generateMetadata(): Promise<Metadata> {
   const { shopName, channelResolved } = await getRequestLocale();
-  return shellMetadata({ shopName, channelResolved });
+  const siteVerifications = await getSiteVerifications();
+  const shell = shellMetadata({ shopName, channelResolved, siteVerifications });
+  if (process.env.NODE_ENV !== 'development') return shell;
+  const revision = resolveLiveRevision();
+  if (revision === null) return shell;
+  // MERGED into the shell's `other`, never written over it: that key carries the
+  // site-verification placements (#1530), and a storefront pod serves through
+  // `npm run dev`, so an overwrite here would strip the provider's tag from
+  // every page its verifier can fetch.
+  return { ...shell, other: { ...shell.other, [FORGE_REVISION_META]: revision } };
 }
 
 /**

package/templates/storefront/src/components/ForgeErrorBeacon.tsx

@@ -23,6 +23,14 @@ import { useEffect } from 'react';
  * the page's own error boundary still renders. The full
  * browser → API route → pod → supervisor-fold path is exercised at the e2e layer,
  * not in this template.
+ *
+ * Every report carries the revision the PAGE WAS SERVED AT (#847), read out of the
+ * `forge-revision` meta tag the server wrote into this document rather than looked
+ * up fresh at throw time. That distinction is the entire point: a fresh lookup would
+ * answer whatever is live NOW, so a promote landing between serve and throw would
+ * make this report blame the new revision for the old one's crash — and the pod's
+ * same-revision fold would then mark a healthy tree DEGRADED. The tag cannot drift,
+ * because it was rendered with the markup that broke.
  */
 export function ForgeErrorBeacon() {
   useEffect(() => {
@@ -30,12 +38,35 @@ export function ForgeErrorBeacon() {
       return;
     }
 
+    /**
+     * The revision this document was SERVED at, or `undefined` when the server
+     * did not stamp one (production, or a pod that cannot resolve it — both
+     * normal). `'forge-revision'` is repeated here as a literal on purpose: the
+     * resolver lives in `src/server/forge/live-revision.ts`, which a client
+     * component must not import, so this is the same repeated-contract shape the
+     * `/__forge_beacon` URL already uses across this feature's producers.
+     *
+     * An absent tag, an absent attribute and an empty value all answer
+     * `undefined`, which `JSON.stringify` then omits from the body entirely —
+     * so an unstamped page sends exactly the payload it sent before, and the pod
+     * keeps its existing untagged behaviour instead of receiving a blank string
+     * it would have to interpret.
+     */
+    const readServedRevision = (): string | undefined => {
+      const content = document
+        .querySelector('meta[name="forge-revision"]')
+        ?.getAttribute('content');
+      if (!content) return undefined;
+      return content;
+    };
+
     const send = (message: string, stack?: string) => {
       const body = JSON.stringify({
         message,
         stack,
         route: window.location.pathname,
         source: 'browser',
+        atRevision: readServedRevision(),
       });
       // Same-origin POST; keepalive lets it survive a navigation/unload. A failed
       // delivery is intentionally swallowed — the beacon is a backstop signal, not

package/templates/storefront/src/instrumentation.ts

@@ -27,6 +27,11 @@
  * The hook NEVER throws out of itself: a failed delivery is swallowed (the beacon is a
  * best-effort backstop, never a hard dependency of the request), so a flapping receiver
  * can never mask or replace the underlying request error Next is already reporting.
+ *
+ * The error's own `code` rides along verbatim — a fact, never a verdict: a request
+ * that races a recompile evaluates Turbopack's stub for a module that no longer parses
+ * and throws `code: 'MODULE_UNPARSABLE'`, and the receiver reads that code to leave a
+ * BUILD failure to the build detectors instead of folding it as a render crash.
  */
 
 const BEACON_PORT = process.env.FORGE_BEACON_PORT ?? '3002';
@@ -86,10 +91,11 @@ export async function onRequestError(
     return;
   }
 
-  const err = error as { message?: string; digest?: string } | undefined;
+  const err = error as { message?: string; digest?: string; code?: unknown } | undefined;
   const body = JSON.stringify({
     message: typeof err?.message === 'string' ? err.message : String(error),
     digest: typeof err?.digest === 'string' ? err.digest : undefined,
+    code: typeof err?.code === 'string' ? err.code : undefined,
     route: request.path,
     routeType: context.routeType,
     source: 'server',

package/templates/storefront/src/lib/seo/metadata.ts

@@ -39,11 +39,42 @@ import { getPublicOrigin } from './public-origin';
  *    whose fields mean the opposite is a defect waiting to be written.
  */
 
+/**
+ * One site-verification placement, narrowed to what a `<meta>` tag needs
+ * (#1530).
+ *
+ * A structural subset of the SDK's `SeoSiteVerification`, for the same reason
+ * `SeoMetaRow` narrows `SeoMetaLanguage`: this module has to stay reachable
+ * from the template-spec project, which imports it by relative path and so
+ * cannot follow anything that pulls in `next` or the SDK. The request-time read
+ * that produces these lives in `site-verification.ts`, which can.
+ *
+ * `name` is the PROVIDER's own, always. A storefront that spelled one vendor's
+ * meta name into its source would serve that vendor and silently ignore every
+ * other one the merchant connects — and would have to be edited again for the
+ * next, which is precisely the thing a descriptor exists to avoid.
+ */
+export interface SiteVerificationMeta {
+  name: string;
+  content: string;
+}
+
+/**
+ * Bare `<meta name content>` pairs, keyed by name.
+ *
+ * The value is a LIST because Next emits one tag per element: two placements
+ * that happen to share a name — the same provider under two accounts — both
+ * reach the document, where a plain string would have kept whichever was folded
+ * last and dropped the other without a trace.
+ */
+export type SiteVerificationTags = Record<string, string[]>;
+
 /** The floor the root layout emits — no route, so no route-specific claims. */
 export interface ShellMetadata {
   title: string;
   description: string;
   robots?: RobotsDirective;
+  other?: SiteVerificationTags;
 }
 
 /**
@@ -76,11 +107,17 @@ export interface PageMetadata {
   alternates?: Alternates;
   openGraph?: OpenGraphMetadata;
   twitter?: TwitterMetadata;
+  other?: SiteVerificationTags;
 }
 
 export interface ShellMetadataInput extends DeploymentPosture {
   /** The merchant's shop name, or null/empty when unset. */
   shopName?: string | null;
+  /**
+   * What the channel's SEO providers need this deployment to serve (#1530),
+   * read per request by `site-verification.ts`. Absent or empty emits nothing.
+   */
+  siteVerifications?: readonly SiteVerificationMeta[];
 }
 
 export interface MetadataInput extends DeploymentPosture {
@@ -105,6 +142,18 @@ export interface MetadataInput extends DeploymentPosture {
   socialImage?: string | null;
   /** The content's own indexability — see `noindex.ts`. */
   contentIndexable?: boolean;
+  /**
+   * The same placements the shell emits (#1530) — for a route that has a
+   * reason of its own to set `other`.
+   *
+   * Next merges a page's metadata OVER the layout's one key at a time, so a
+   * page that sets `other` at all REPLACES the floor's, verification tags
+   * included. Passing them here is how such a route keeps them. Every route
+   * this template ships sets no `other` and therefore passes nothing, and
+   * inherits the shell's — absent means inherit, exactly as it does for
+   * `description` and `robots` above.
+   */
+  siteVerifications?: readonly SiteVerificationMeta[];
 }
 
 /**
@@ -202,12 +251,14 @@ export function buildShellMetadata({
   shopName,
   publicOrigin,
   channelResolved,
+  siteVerifications,
 }: ShellMetadataInput): ShellMetadata {
   const refuses = deploymentRefusesIndexing({ publicOrigin, channelResolved });
   return {
     title: pageTitle(null, shopName),
     description: SITE_DESCRIPTION,
     ...(refuses ? { robots: NOINDEX_ROBOTS } : {}),
+    ...verificationTags(siteVerifications),
   };
 }
 
@@ -250,6 +301,7 @@ export function buildMetadata(input: MetadataInput): PageMetadata {
     ...(noindex ? { robots: NOINDEX_ROBOTS } : {}),
     ...(alternates === undefined ? {} : { alternates }),
     ...socialTags({ ...input, title, description, alternates }),
+    ...verificationTags(input.siteVerifications),
   };
 }
 
@@ -321,3 +373,35 @@ function socialTags({
     twitter: { card: 'summary_large_image', ...shared },
   };
 }
+
+/**
+ * The verification tags, or nothing at all (#1530).
+ *
+ * The SINGLE place in this template where a placement becomes a `<meta>`, and
+ * both emitters above route through it — the shell, which is what every route
+ * inherits, and a page that sets `other` for its own reasons and would
+ * otherwise replace the shell's. Two spellings of one tag is how a document
+ * ends up serving a token the platform has already re-minted.
+ *
+ * Deliberately NOT Next's `metadata.verification` block. Every key in it is
+ * named after one named vendor, so which key a token landed in would be a
+ * decision this template makes about which provider the merchant uses — and a
+ * provider without a key of its own could not be served at all. `other` takes
+ * the name from the descriptor, which is the whole point of there being a
+ * descriptor.
+ *
+ * An empty list emits no `other` KEY rather than an empty object, for the
+ * reason stated above `buildMetadata`: a key present with a falsy value still
+ * wins Next's merge, so a page with no placements would blank the shell's.
+ */
+function verificationTags(
+  siteVerifications: readonly SiteVerificationMeta[] | undefined,
+): Pick<PageMetadata, 'other'> {
+  if (siteVerifications === undefined || siteVerifications.length === 0) return {};
+
+  const other: SiteVerificationTags = {};
+  for (const { name, content } of siteVerifications) {
+    other[name] = [...(other[name] ?? []), content];
+  }
+  return { other };
+}

package/templates/storefront/src/lib/seo/site-verification.ts

@@ -0,0 +1,98 @@
+import 'server-only';
+
+import { cache } from 'react';
+
+import { getShopClient } from '../forgecart';
+import type { SiteVerificationMeta } from './metadata';
+
+/**
+ * What the channel's SEO providers need this storefront to serve (#1530).
+ *
+ * A provider proves the merchant owns this address by asking them to place a
+ * token on it. The platform mints that token per account and per origin, and
+ * this read is the storefront's half of the handshake: it asks the shop API
+ * what to serve, and `metadata.ts` turns each descriptor into one
+ * `<meta name content>` tag. Nothing here knows which provider minted what —
+ * the NAME arrives in the descriptor, so a second provider is a server change
+ * and no template change at all.
+ *
+ * Only `META` placements are served. The mechanism rides in the descriptor
+ * precisely so that a provider verifying some other way — a DNS record, a file
+ * at a path this template does not route — cannot have its token silently
+ * rendered as a meta tag, which would be a placement that looks made and is
+ * not.
+ *
+ * PER REQUEST, and no further. React's `cache()` collapses the callers of one
+ * render into a single read; there is deliberately no TTL and no process memo
+ * above it. A verifier makes ONE fetch, and a token re-minted while a replica
+ * still serves a cached copy of the old one is a verification that fails with
+ * every part of the system reporting health — the same reason
+ * `sitemap-cache.ts`'s window is safe (a stale URL list costs a crawl) and one
+ * here would not be.
+ *
+ * Failure is ALWAYS an empty list, never a throw. This read happens inside the
+ * root layout's `generateMetadata`, structurally outside every Suspense
+ * boundary (D8), so a throw here is a 500 on every route of the store — and
+ * what is lost instead is one meta tag whose absence the platform already
+ * detects and retries on its next sync. An unconfigured scaffold reaches the
+ * same arm: `getShopClient()` throws when `.env` carries no coordinates, and
+ * the prewarm contract says a storefront with no configuration must SERVE.
+ */
+
+/** The answer whenever there is nothing honest to serve. */
+const NONE: readonly SiteVerificationMeta[] = [];
+
+/**
+ * The one mechanism this template can satisfy — a tag in the document it
+ * renders. Compared against the descriptor's own value rather than assumed.
+ */
+const META_METHOD = 'META';
+
+/**
+ * How long the document shell may wait for this read.
+ *
+ * The same bound, for the same reason, as the channel read in
+ * `locale/channel-locales-loader.ts`: the shell has no Suspense boundary above
+ * it, so an unbounded wait holds the whole document open with nothing to time
+ * it out. Past this the storefront serves without the tag, which is the lesser
+ * of the two failures by a wide margin.
+ */
+const VERIFICATION_READ_TIMEOUT_MS = 2_000;
+
+/**
+ * The placements this storefront must serve, for THIS request.
+ *
+ * Read through the generated SDK like every other shop-API call in the
+ * template — there are no hand-written query documents here, which is what
+ * keeps the storefront's reads and the API's schema from drifting apart.
+ *
+ * The request's own client is used rather than one pinned to the channel
+ * default: the answer is the same in every language, so the cheaper of two
+ * correct options wins, and that is the socket this render already has open.
+ */
+export const getSiteVerifications = cache(async (): Promise<readonly SiteVerificationMeta[]> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      readPlacements(),
+      new Promise<readonly SiteVerificationMeta[]>((resolve) => {
+        timer = setTimeout(() => {
+          resolve(NONE);
+        }, VERIFICATION_READ_TIMEOUT_MS);
+      }),
+    ]);
+  } catch {
+    // The template's sanctioned catch: an external SDK call, wrapped at its
+    // call site, exactly as `forgecart.ts#runAccountOperation` and
+    // `shop-session.ts` do. Nothing is swallowed that anyone here could act on
+    // — the platform's sync ladder is what observes an unserved placement.
+    return NONE;
+  } finally {
+    clearTimeout(timer);
+  }
+});
+
+async function readPlacements(): Promise<readonly SiteVerificationMeta[]> {
+  const { seoSiteVerifications } = await (await getShopClient()).seo.seoSiteVerifications();
+  return seoSiteVerifications.filter((placement) => placement.method === META_METHOD);
+}

package/templates/storefront/src/server/forge/live-revision.ts

@@ -0,0 +1,158 @@
+/**
+ * The revision this server is SERVING, for the dev-only error beacon (#847).
+ *
+ * A browser error report used to be stamped with whatever revision was live at
+ * the moment the pod RECEIVED it (`storefront-beacon.service.ts`, `atRevision:
+ * this.target.getLiveRevision()`). A promote that advances between serve and
+ * throw therefore made the report blame the NEW revision for the OLD one's
+ * crash, and the receiver's same-revision fold then marked a healthy tree
+ * DEGRADED. The cure is to resolve the revision where the page is RENDERED —
+ * here — stamp it into the HTML, and let the report carry it back.
+ *
+ * WHERE THE RAW VALUE COMES FROM (settled by ruling ANSWER-0425Z-agent-004):
+ * the pod's supervisor publishes the serving sha to a DERIVED, read-only file
+ * inside the workspace's `.forge/` island by the same act that re-publishes its
+ * runtime state, and this module reads that file per request. Explicitly NOT a
+ * beacon hop on the render path, and explicitly NOT an environment variable —
+ * one dev-server process outlives many promotes, so a value handed to it at
+ * spawn time could only ever name the revision it BOOTED at, which is this
+ * module's own bug reintroduced one layer down. The retired
+ * `.forge/liveRevision` sentinel (appendix design law 5, §7.3) is not that file
+ * and is not read here; see `FORGE_SERVING_REVISION_FILE` below.
+ *
+ * The split is still the shape of the feature:
+ *
+ *  - `parseLiveRevision` is PURE and fully specified by vectors. It owns the
+ *    whole question of what counts as a revision, independently of where the
+ *    raw value came from.
+ *  - `readLiveRevisionSource` is the ONE impure line — the file read, and
+ *    nothing else in the template touches the filesystem for this.
+ *
+ * FAIL OPEN, ALWAYS. Every unresolvable case answers `null`, which means no
+ * meta tag, which means an untagged report, which means the receiver keeps its
+ * existing behaviour (confirm probe included). A page must never fail to render
+ * because the revision is unknown, so there is no throw on this path: an
+ * unknown revision is an ordinary, expected state — every non-storefront pod,
+ * and every pod before its bootstrap primes the ref — not a fault.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The meta tag's `name`. The CONTRACT between this module (which resolves the
+ * value), `app/layout.tsx` (which emits the tag) and
+ * `components/ForgeErrorBeacon.tsx` (which reads it back out of the DOM at send
+ * time). The beacon is a CLIENT component and must not import a `src/server/`
+ * module, so it repeats the literal with a comment pointing here — the same way
+ * the `/__forge_beacon` URL is repeated across this feature's three producers
+ * rather than shared through an import.
+ */
+export const FORGE_REVISION_META = 'forge-revision';
+
+/**
+ * The workspace-relative path the pod's supervisor publishes the serving sha to.
+ *
+ * MIRRORS `SERVING_REVISION_FILE` in
+ * `app/workspace-manager/src/supervisor/workspace-supervisor.service.ts`, whose
+ * doc carries the full reasoning for the path — `.forge/` because that island is
+ * the board repo's ignore authority and a file anywhere else would dirty the
+ * serving tree on every publish, and NEITHER retired legacy path, both of which
+ * the pod's own bootstrap deletes at boot. It is repeated here instead of
+ * imported because this template is scaffolding DATA — copied verbatim into a
+ * merchant's project, with its own `package.json` and toolchain, outside that
+ * monorepo's build graph — exactly like the `/__forge_beacon` URL. Nothing in a
+ * compiler connects the two copies: a rename on either side would silently stop
+ * the file from being found and every report would go back to untagged, so
+ * `tool/storefront-template-spec/src/live-revision.spec.ts` compares them.
+ *
+ * Resolved against `process.cwd()`, which IS the workspace root the supervisor
+ * writes into: it spawns `npm run dev` with `cwd` = the configured workspace
+ * path (resolved in `process-supervisor.service.ts`, handed to the child in
+ * `managed-process.ts`), and `npm` runs the script from the package root without
+ * moving it. `lib/seo/scaffolded-routes.ts` already reads a workspace-relative
+ * path this way on a request path.
+ */
+export const FORGE_SERVING_REVISION_FILE = '.forge/serving-revision';
+
+/**
+ * A revision is a full git commit sha and nothing else: exactly 40 hex digits,
+ * case-insensitive, surrounding whitespace trimmed. That is precisely what the
+ * supervisor's source produces — `git rev-parse --verify refs/heads/serving^{commit}`
+ * (`board-git.service.ts`) — so anything else reaching here is not a revision
+ * and must not be stamped.
+ *
+ * The rejections are the load-bearing half, because a stamped non-sha is worse
+ * than no stamp at all: the receiver compares the payload's value to the live
+ * revision by EQUALITY to decide whether to fold without probing, so a
+ * placeholder that could also BE the live value would skip the probe on
+ * evidence that means nothing. `'unversioned'` is the concrete instance of that
+ * hazard — it is literally what the supervisor reports for a pod with no board
+ * repo, so an unversioned pod stamping `'unversioned'` would match itself and
+ * defeat the guard. Rejecting it here is what makes the receiver's equality
+ * check safe.
+ *
+ * @param raw the candidate revision, exactly as obtained from the source
+ * @returns the normalised lowercase sha, or `null` when `raw` is not one
+ */
+export function parseLiveRevision(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (!/^[0-9a-f]{40}$/i.test(trimmed)) return null;
+  return trimmed.toLowerCase();
+}
+
+/**
+ * Obtain the raw revision value — THE ONE impure line in this module.
+ *
+ * A plain read of {@link FORGE_SERVING_REVISION_FILE}, the file the pod's
+ * supervisor re-publishes on every serving advance. There is deliberately NO
+ * environment fallback: the ruling excluded one, and an env value read here
+ * would be strictly worse than nothing, because the only process that could
+ * supply it is the dev-server's own spawn — which happens once and then serves
+ * every later promote under the revision it started at.
+ *
+ * Read per CALL, never captured at module scope, for the same reason:
+ * a value snapshotted at first import would keep stamping the boot revision
+ * forever. `lib/seo/sitemap-cache.ts` carries the same getter-not-a-constant
+ * reasoning.
+ *
+ * SYNCHRONOUS, unlike `lib/seo/scaffolded-routes.ts`, which reads on a request
+ * path asynchronously and explains why. That reasoning does not transfer: it
+ * fans out over a directory of arbitrarily many JSON fragments, whereas this is
+ * ONE page-cached read of at most 41 bytes, sitting beside an awaited channel
+ * read in the same `generateMetadata` that dwarfs it. Going async would cost
+ * `resolveLiveRevision` its synchronous signature for nothing measurable.
+ *
+ * Every failure answers `null`, and the ordinary case IS a failure: the file is
+ * absent on every pod before its first publish, on a non-storefront workspace
+ * that publishes none, and in a merchant's own checkout of this template, where
+ * no supervisor exists at all. Absent, unreadable and garbage all mean the same
+ * thing here — no tag, an untagged report, the receiver's existing behaviour —
+ * so there is nothing worth distinguishing between them and nothing worth
+ * throwing over on a render path.
+ */
+export function readLiveRevisionSource(): string | null {
+  try {
+    return readFileSync(join(process.cwd(), FORGE_SERVING_REVISION_FILE), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The revision to stamp into this response, or `null` when it cannot be
+ * resolved. Composes the source and the acceptance rule and holds no policy of
+ * its own, so the ruling can move the source without touching any caller.
+ *
+ * The DEV-ONLY gate lives at the call site (`app/layout.tsx`), not here — the
+ * placement every other file in this feature uses (`ForgeErrorBeacon.tsx`,
+ * `app/%5F%5Fforge_beacon/route.ts` and `instrumentation.ts` each check
+ * `NODE_ENV` at their own top), which is what lets a production build
+ * dead-code-eliminate the whole path rather than merely reach a function that
+ * answers `null`.
+ */
+export function resolveLiveRevision(): string | null {
+  const raw = readLiveRevisionSource();
+  if (raw === null) return null;
+  return parseLiveRevision(raw);
+}