@ultimat3/pwa 8.0.0 → 10.0.0

package/CLAUDE.md

@@ -10,11 +10,13 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Rule | Detail |
 |---|---|
 | `sw.js` | generated, never hand-written, never committed. No file in this package is a SW. |
-| Determinism | no `Date.now()`, no randomness, sort every collection. Same input → same bytes. |
+| Determinism | no `Date.now()`, no randomness, sort every collection. Same input → same bytes. `subscriptionState` took `now = Date.now()` and was the one exception; it takes a `Clock` `As of 2026-08-23`, so a frozen clock freezes this package too. |
+| Rule ORDER | most specific first, then the path. `ruleFor` in the emitted worker returns the FIRST pattern that matches and has no notion of specificity, so the sort IS the routing decision. Alphabetical, `:` (0x3A) and `*` (0x2A) sort before every letter: `/posts/:id` shadowed `/posts/new`, and one `/*` catch-all shadowed the whole table — every `PRECACHE_MANIFEST` entry downloaded at install and never looked up, and a cacheable route served `network-only`, which offline is the `/offline` document. Weights are `@ultimat3/render`'s `compilePattern` (literal 100, `:param` 10, `*` 1), **duplicated** because both packages are tier 4; a wildcard sorts last outright, because a sum over segments cannot say that `/` (0 segments) outranks `/*rest` (1). The shared home is `@ultimat3/core`'s `route-vocabulary.ts`. |
+| A generated header | names something that regenerates the file. `sw.js` said `regenerate: x build` and no `x build` target emits a service worker — `generateServiceWorker` has no caller anywhere in the tree — so it names the CALL until a build writes it. |
 | Route input | `PwaRoute` is a **structural** view of render's `RouteDescriptor`. Never import render. |
 | Strategy choice | derived from render mode via `MODE_STRATEGY`. Per-route override only. |
 | Precache revision | content hash. Never the build id — that re-downloads everything per deploy. |
-| Precache KEY | the bare URL, always. The revision addresses the FETCH (`?v=<hash>`), never the key: every strategy looks an entry up with `caches.match(req)` and `ignoreSearch` defaults to `false`, so an entry left keyed under `?v=` is a permanent miss — offline serves the fallback document instead of the precached page, and online every precached byte is downloaded twice. `addAll` still does the fetching, because its all-or-nothing failure is what stops a half-populated precache from activating; the install block only re-keys what it stored. `service-worker.test.ts` executes the emitted `sw.js` against stub `caches`/`fetch` rather than asserting its text. |
+| Precache KEY | the bare URL, always. The revision addresses the FETCH (`?v=<hash>`), never the key: every strategy looks an entry up with `caches.match(req)` and `ignoreSearch` defaults to `false`, so an entry left keyed under `?v=` is a permanent miss — offline serves the fallback document instead of the precached page, and online every precached byte is downloaded twice. `addAll` still does the fetching, because its all-or-nothing failure is what stops a half-populated precache from activating; the install block only re-keys what it stored. `service-worker-runtime.test.ts` executes the emitted `sw.js` against stub `caches`/`fetch` rather than asserting its text. |
 | Precache FETCH | the revision is appended with `?` or `&`, picked per entry. `PrecacheAsset.url` is public API and a bundler emits `?v=<hash>` of its own, so a fixed `?` built `...?locale=en?v=<rev>`; `addAll` is all-or-nothing, so one non-200 there means `install` rejects and the worker never activates at all. |
 | SW scope | `assertScope` refuses a relative `swPath`. `lastIndexOf('/')` on `sw.js` is `-1`, so the directory was `''` and `scope.startsWith('')` passed for every scope — the check waved through exactly the config most likely to be wrong. |
 | HTML sinks | one escaper: `escapeAttribute` from `@ultimat3/seo` (tier 1, and the only one reachable — render's `html.ts` is tier 4, sideways). `appleTouchLinks` and `renderThemeColorMeta` interpolate app config into attributes; both escape. Never a second escaper here. |
@@ -22,6 +24,8 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Cache names | always `cacheNamespace(buildId, kind)`. An unkeyed cache name is a rejected change. |
 | Offline fallback | `requireOfflineFallback` runs inside `generateServiceWorker`. Never optional. |
 | Capabilities | gate the manifest member **and** the SW block, where the capability has one. Disabled → zero bytes. `push`, `backgroundSync` and `badging` emit worker code; `shareTarget`, `fileHandlers` and `protocolHandlers` are **manifest-only** — the OS delivers to a route the app already serves — and their `CAPABILITY_SW_MARKERS` list is empty, which `service-worker.test.ts` checks in both directions: every declared marker is in the worker when its capability is on, none is when they are all off. `shareTarget` named `/_x/share-target` there while no block emitted it. |
+| `AppUpdateAvailable` | declares exactly the fields the emitted `activate` block posts, and no more. `version-skew.test.ts` reads the literal back out of the generated source and compares it to a fixture typed `Required<AppUpdateAvailable>` — a field added to the interface stops compiling, a field added to the worker fails the assertion. It declared five and posted two until 9.0.0; the three extra described a forced reload nothing performed. |
+| Forced reload | **not a capability of this package.** `updateSignal`/`updatePolicy` computed `forced`/`deadlineAt` with no runtime caller and were deleted in 9.0.0. The two runtimes holding both build ids are BELOW this one — `http`'s `ctx.clientBuildId` (tier 2), `sync`'s `update-available` frame (tier 3) — so neither could ever have called into tier 4 to act on one. The app renders its own affordance; the framework never navigates a client. |
 | Outbox | queue lives in `@ultimat3/realtime`. This package only registers the sync trigger. |
 | Push strings | i18n keys only, rendered per subscriber locale. Never a literal. |
 | Push URLs | `PushPayload.url` is a PATH and `WindowClient.url` is absolute, so `notificationclick` resolves against `self.location.origin` before comparing. Unresolved, the focus-existing-tab loop matched nothing and every tap opened a second window. |

package/README.md

@@ -38,13 +38,14 @@ and the app dies with a blank screen and no error anyone can act on.
 | Client → server | every SW-proxied request carries `x-ultimate-build` |
 | Retention | `retentionPlan(deploys, keep)` keeps the last N deploys' assets alive (default 3) |
 | Stale client | gets `AppUpdateAvailable`, never a 404 |
-| Forced reload | only for `forceOn` reasons, only after `graceMs` (default 6h) |
+| Forced reload | none. This package never navigates a client — the app decides what to do with the message |
 | Preview deploys | cache names are `x-<kind>-<buildId>`, so a branch build cannot poison production |
 
 ```ts
-detectSkew(clientBuildId, serverBuildId);   // 'current' | 'stale' | 'unknown'
-updateSignal({ clientBuildId, serverBuildId, policy: updatePolicy() });
-// → { type: 'AppUpdateAvailable', from, to, forced, deadlineAt }
+// The generated worker posts this to every page it controls, on activation — and this is the
+// whole message, which `version-skew.test.ts` holds the interface to.
+// { type: 'AppUpdateAvailable', to: BUILD_ID }
+detectSkew(clientBuildId, message.to); // 'current' | 'stale' | 'unknown'
 ```
 
 `unknown` means no id was sent — a first load or a crawler — and is never treated as stale.
@@ -87,7 +88,7 @@ capability nothing implements.
 | `generateServiceWorker` | `sw.js` from the route table; deterministic for identical input |
 | `strategyFor`, `MODE_STRATEGY`, `cacheFirst`, … | the four strategies + the mapping table |
 | `buildPrecacheManifest` | precache entries (url + content-hash revision), size warnings |
-| `buildId`, `detectSkew`, `retentionPlan`, `updatePolicy`, `updateSignal` | version skew |
+| `buildId`, `detectSkew`, `retentionPlan` | version skew |
 | `generateWebManifest` | the manifest + `theme-color` metas for both schemes |
 | `planIcons`, `requireSourceIcon`, `maskableSafeZone` | icons and splashes from one source |
 | `BuiltinImagePipeline` | renders that plan: one square PNG per entry, deterministic |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "8.0.0",
+  "version": "10.0.0",
   "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "8.0.0",
-    "@ultimat3/seo": "8.0.0"
+    "@ultimat3/core": "10.0.0",
+    "@ultimat3/seo": "10.0.0"
   }
 }

package/src/background-sync.ts

@@ -14,6 +14,7 @@
  * `UltimateError` does everywhere else in the framework.
  */
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { PwaSyncFlushFailedError, PwaSyncIncompleteError } from './errors';
 import { BUILD_ID_HEADER } from './version-skew';
 
@@ -54,11 +55,13 @@ export interface BackgroundSyncOptions {
 export const DEFAULT_FLUSH_ENDPOINT = '/_x/outbox/flush';
 
 /**
- * Where the emitted class sends a reader. The same host `./errors.ts` documents these two codes
- * at — retyped here because the SW builds its URL from the code at throw time, and
- * `background-sync.test.ts` asserts the two halves still agree.
+ * Where the emitted class sends a reader — `@ultimat3/core`'s `ERROR_DOCS_URL`, interpolated into
+ * the worker source rather than restated, because a URL retyped in a generated string is a second
+ * constant that drifts silently. One page for every code, not one per code: `wiki/` is the
+ * framework's only public documentation surface and a code lives there in a table row, which has no
+ * anchor. `background-sync.test.ts` asserts the emitted value still equals what the registry says.
  */
-const SYNC_DOCS_BASE = 'https://ultimate.dev/errors/';
+const SYNC_DOCS = ERROR_DOCS_URL;
 
 /**
  * The generated realm's own coded error, as source. Small on purpose — this ships in `sw.js` — and
@@ -70,7 +73,7 @@ const SYNC_DOCS_BASE = 'https://ultimate.dev/errors/';
 const SYNC_ERROR_CLASS = `
 class PwaSyncError extends Error{
   constructor(code,cause,fix){
-    const docs=${JSON.stringify(SYNC_DOCS_BASE)}+code;
+    const docs=${JSON.stringify(SYNC_DOCS)};
     super(code+': '+cause+'\\n  fix:   '+fix+'\\n  docs:  '+docs);
     this.name='PwaSyncError';this.code=code;this.cause=cause;this.fix=fix;this.docs=docs;
   }
@@ -92,7 +95,9 @@ ${SYNC_ERROR_CLASS}
 async function flushOutbox(){
   const res=await fetch(FLUSH_ENDPOINT,{method:'POST',headers:{${JSON.stringify(BUILD_ID_HEADER)}:BUILD_ID}});
   if(!res.ok)throw new PwaSyncError(${JSON.stringify(PwaSyncFlushFailedError.code)},'outbox flush POST '+FLUSH_ENDPOINT+' returned '+res.status,'curl -i -X POST '+FLUSH_ENDPOINT+' — @ultimat3/realtime must mount it and answer 2xx');
-  const body=await res.json().catch(()=>({remaining:0}));
+  // ||{} rather than a default inside the catch: json() on a 200 body of null RESOLVES with null,
+  // so the catch never fires and body.remaining raised inside waitUntil instead of refusing coded.
+  const body=(await res.json().catch(()=>null))||{};
   if(body.remaining>0)throw new PwaSyncError(${JSON.stringify(PwaSyncIncompleteError.code)},'outbox flush at '+FLUSH_ENDPOINT+' left '+body.remaining+' mutation(s) queued','x dev --role sync   # drain the outbox, or raise pwa.backgroundSync.retry.maxAttempts in app.config.ts');
 }
 self.addEventListener('sync',(event)=>{

package/src/errors.ts

@@ -46,7 +46,12 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(PWA_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-const docsFor = (code: PwaErrorCode): string => `https://ultimate.dev/errors/${code}`;
+// No `docs:` on the subclasses below. `UltimateError` fills it from `describeErrorCode(code).docs`,
+// which is `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
+// `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE ROW,
+// which has no anchor. The `https://ultimate.dev/errors/<code>` links this file built until 9.x
+// answered 404, host included, on every error it has ever thrown; restating the replacement here
+// would be the same constant in eight places waiting to drift again.
 
 /** No `app/offline.tsx`. You cannot ship a PWA that has nothing to show offline. */
 export class PwaNoOfflineFallbackError extends UltimateError {
@@ -56,7 +61,6 @@ export class PwaNoOfflineFallbackError extends UltimateError {
       code: PwaNoOfflineFallbackError.code,
       cause,
       fix,
-      docs: docsFor(PwaNoOfflineFallbackError.code),
     });
   }
 }
@@ -69,7 +73,6 @@ export class PwaIconMissingError extends UltimateError {
       code: PwaIconMissingError.code,
       cause,
       fix,
-      docs: docsFor(PwaIconMissingError.code),
     });
   }
 }
@@ -82,7 +85,6 @@ export class PwaManifestInvalidError extends UltimateError {
       code: PwaManifestInvalidError.code,
       cause,
       fix,
-      docs: docsFor(PwaManifestInvalidError.code),
     });
   }
 }
@@ -95,7 +97,6 @@ export class BuildIdMissingError extends UltimateError {
       code: BuildIdMissingError.code,
       cause,
       fix,
-      docs: docsFor(BuildIdMissingError.code),
     });
   }
 }
@@ -108,7 +109,6 @@ export class SwScopeInvalidError extends UltimateError {
       code: SwScopeInvalidError.code,
       cause,
       fix,
-      docs: docsFor(SwScopeInvalidError.code),
     });
   }
 }
@@ -125,7 +125,6 @@ export class PwaStrategyExhaustedError extends UltimateError {
       code: PwaStrategyExhaustedError.code,
       cause: `no cached response and the network failed for "${input.cacheName}"`,
       fix: 'pass options.fallback to staleWhileRevalidate(request, env, options), or set pwa.offline.fallback in app.config.ts',
-      docs: docsFor(PwaStrategyExhaustedError.code),
     });
   }
 }
@@ -144,7 +143,6 @@ export class PwaSyncFlushFailedError extends UltimateError {
       code: PwaSyncFlushFailedError.code,
       cause,
       fix,
-      docs: docsFor(PwaSyncFlushFailedError.code),
     });
   }
 }
@@ -157,7 +155,6 @@ export class PwaSyncIncompleteError extends UltimateError {
       code: PwaSyncIncompleteError.code,
       cause,
       fix,
-      docs: docsFor(PwaSyncIncompleteError.code),
     });
   }
 }
@@ -170,7 +167,6 @@ export class NotImplementedError extends UltimateError {
       code: NotImplementedError.code,
       cause,
       fix,
-      docs: docsFor(NotImplementedError.code),
     });
   }
 }

package/src/index.ts

@@ -137,17 +137,18 @@ export {
   staleWhileRevalidate,
   strategyFor,
 } from './strategies';
+// The forced-reload half of this module is gone as of 9.0.0 — `updateSignal`, `updatePolicy`,
+// `DEFAULT_GRACE_MS`, `ForceReason`, `UpdatePolicy`, `UpdatePolicyInput`, `UpdateSignalInput`.
+// It computed `forced`/`deadlineAt` for a client-side reload no code in the framework performed,
+// from a caller that never existed. What remains is what runs: an id, a comparison, a retention
+// plan, and the message the generated worker really posts.
 export type {
   AppUpdateAvailable,
   BuildIdInput,
   Deploy,
   DeployChannel,
-  ForceReason,
   RetentionPlan,
   SkewState,
-  UpdatePolicy,
-  UpdatePolicyInput,
-  UpdateSignalInput,
 } from './version-skew';
 export {
   APP_UPDATE_AVAILABLE,
@@ -156,9 +157,6 @@ export {
   BUILD_ID_META,
   buildId,
   cacheNamespace,
-  DEFAULT_GRACE_MS,
   detectSkew,
   retentionPlan,
-  updatePolicy,
-  updateSignal,
 } from './version-skew';

package/src/push.ts

@@ -6,6 +6,9 @@
  * is a real bug that users report as "the app is broken".
  */
 
+import type { Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
+
 export interface VapidConfig {
   readonly publicKey: string;
   /** `mailto:` or an https URL — required by the spec, checked by every push service. */
@@ -30,13 +33,21 @@ export interface PushSubscriptionRecord {
 
 export type SubscriptionState = 'active' | 'expired' | 'gone';
 
-/** A 404/410 from the push service means the subscription is dead — delete it, don't retry. */
+/**
+ * A 404/410 from the push service means the subscription is dead — delete it, don't retry.
+ *
+ * `clock`, never `Date.now()`: this package's boundary says `Determinism | no Date.now()` without
+ * qualification, and an injectable default is still a wall-clock read living in the module. Every
+ * other "now" in the framework goes through a `Clock`, so a caller freezing time freezes this too
+ * rather than having to know that one function takes epoch milliseconds instead.
+ */
 export function subscriptionState(
   record: PushSubscriptionRecord,
   lastStatus: number | null,
-  now = Date.now(),
+  clock: Clock = systemClock,
 ): SubscriptionState {
   if (lastStatus === 404 || lastStatus === 410) return 'gone';
+  const now = clock.now().getTime();
   if (record.expirationTime !== null && record.expirationTime <= now) return 'expired';
   return 'active';
 }

package/src/service-worker.ts

@@ -84,10 +84,56 @@ export function assertScope(swPath: string, scope: string): void {
   }
 }
 
+const segmentsOf = (path: string): readonly string[] =>
+  path.split('/').filter((segment) => segment.length > 0);
+
+/**
+ * How specifically a path claims a URL: a literal segment beats a `:param`, which beats a `*`.
+ * The weights are `@ultimat3/render`'s `compilePattern`, verbatim (100 / 10 / 1), so the service
+ * worker and the server rank the same pathname the same way.
+ *
+ * DUPLICATED, not imported: `render` and `pwa` are both tier 4 and a sideways import is a build
+ * error. The shared home is `@ultimat3/core`'s `route-vocabulary.ts` — tier 0, already the owner of
+ * `RENDER_MODES` / `OFFLINE_STRATEGIES` / `HYDRATE_STRATEGIES` for exactly this reason — and moving
+ * it there is the follow-up this comment exists to name.
+ */
+function specificityOf(path: string): number {
+  return segmentsOf(path).reduce((total, segment) => {
+    if (segment.startsWith('*')) return total + 1;
+    if (segment.startsWith(':')) return total + 10;
+    return total + 100;
+  }, 0);
+}
+
+/**
+ * A catch-all is a FALLBACK, and it sorts behind every rule that is not one — a second key, because
+ * a sum over segments cannot say it. `/` has no segments and so scores 0, while `/*rest` scores 1:
+ * on specificity alone a single root catch-all outranks the home page, and with it every precached
+ * entry in the table. The rule this expresses is the one a reader already assumes — a pattern that
+ * matches everything answers only what nothing else claimed.
+ */
+const hasWildcard = (path: string): boolean =>
+  segmentsOf(path).some((segment) => segment.startsWith('*'));
+
+/**
+ * Ordered MOST SPECIFIC FIRST, because the emitted `ruleFor` returns the first pattern that
+ * matches and has no notion of specificity of its own. Sorted alphabetically it did not: `:` (0x3A)
+ * and `*` (0x2A) both sort before every letter, so `/posts/:id` shadowed `/posts/new` and a single
+ * `/*` catch-all shadowed the entire table — every entry in `PRECACHE_MANIFEST` downloaded at
+ * install and then never looked up, and a route the app declared cacheable served `network-only`,
+ * which offline is the `/offline` document.
+ *
+ * The path stays as the tie-break, so the emitted file is still byte-identical for identical input.
+ */
 export function routeRules(routes: readonly PwaRoute[]): readonly RouteRule[] {
   return [...routes]
     .filter((route) => route.surface !== 'api')
-    .sort((a, b) => a.path.localeCompare(b.path))
+    .sort(
+      (a, b) =>
+        Number(hasWildcard(a.path)) - Number(hasWildcard(b.path)) ||
+        specificityOf(b.path) - specificityOf(a.path) ||
+        a.path.localeCompare(b.path),
+    )
     .map((route) => {
       const strategy = strategyFor(route);
       return {
@@ -175,8 +221,13 @@ export function generateServiceWorker(
 }
 
 function header(buildId: string): string {
+  // `regenerate:` names the CALL, not a command: `x build` emits no service worker — nothing in
+  // the tree calls `generateServiceWorker` at all — so the line sent whoever found this file in a
+  // diff to a command that would leave it exactly as they found it. It becomes `x build` on the day
+  // the build actually writes this file, and not before.
   return `// GENERATED by @ultimat3/pwa from the route table — do not edit.
-// build: ${buildId}   regenerate: x build`;
+// build: ${buildId}
+// regenerate: generateServiceWorker(routes, config, buildId) from @ultimat3/pwa`;
 }
 
 function constants(

package/src/version-skew.ts

@@ -5,7 +5,9 @@
  *
  *   immutable build id per deploy → the client sends it on every request →
  *   old builds' assets are retained for N deploys → a stale client gets
- *   `AppUpdateAvailable`, never a 404 → forced reload only after a grace period.
+ *   `AppUpdateAvailable`, never a 404.
+ *
+ * The app decides what to do with that message. This package never navigates a client.
  */
 
 import { BuildIdMissingError } from './errors';
@@ -115,73 +117,23 @@ export function detectSkew(
   return clientBuildId === serverBuildId ? 'current' : 'stale';
 }
 
-export type ForceReason = 'security' | 'breaking-protocol' | 'never';
-
-export interface UpdatePolicyInput {
-  /** How long a stale client may keep running before the reload is forced. */
-  readonly graceMs?: number;
-  readonly forceOn?: readonly ForceReason[];
-}
-
-export interface UpdatePolicy {
-  readonly graceMs: number;
-  readonly forceOn: readonly ForceReason[];
-  shouldForce(reason: ForceReason, staleForMs: number): boolean;
-}
-
-export const DEFAULT_GRACE_MS = 6 * 60 * 60 * 1000;
-
-export function updatePolicy(input: UpdatePolicyInput = {}): UpdatePolicy {
-  const graceMs = input.graceMs ?? DEFAULT_GRACE_MS;
-  const forceOn = input.forceOn ?? ['security'];
-  return {
-    graceMs,
-    forceOn,
-    // A security patch still respects the grace window; it just does not wait forever.
-    shouldForce: (reason, staleForMs) => forceOn.includes(reason) && staleForMs >= graceMs,
-  };
-}
-
 /**
- * The client-side contract. The SW posts this to every controlled page; the app shows an
- * unobtrusive "refresh to update" affordance and reloads on the user's terms — unless
- * `forced`, in which case it reloads at `deadlineAt`.
+ * The client-side contract, and the whole of it: what the generated worker posts to every page it
+ * controls on activation. The page compares `to` against its own `BUILD_ID_META` — `detectSkew`
+ * is that comparison — and renders its own "refresh to update" affordance.
+ *
+ * It declared `from`, `forced` and `deadlineAt` too, for a forced reload after a grace period that
+ * NOTHING performed: `updateSignal`/`updatePolicy` computed the three and had no runtime caller,
+ * and `x deploy --critical`, the flag that was to have set the reason, was removed in 4.0.0 for
+ * being read by nobody. The two runtimes that hold both build ids cannot call into this package
+ * anyway — `http`'s `ctx.clientBuildId` (tier 2) and `sync`'s `update-available` frame (tier 3)
+ * are both BELOW `pwa`, and imports only go down. `version-skew.test.ts` holds this interface to
+ * the literal the worker emits, so the two can no longer differ.
  */
 export interface AppUpdateAvailable {
   readonly type: 'AppUpdateAvailable';
-  readonly from: string;
+  /** The build the worker that posted this was generated for. */
   readonly to: string;
-  readonly forced: boolean;
-  /** Epoch milliseconds after which the client reloads itself. Null when not forced. */
-  readonly deadlineAt: number | null;
 }
 
 export const APP_UPDATE_AVAILABLE = 'AppUpdateAvailable' as const;
-
-export interface UpdateSignalInput {
-  readonly clientBuildId: string | null | undefined;
-  readonly serverBuildId: string;
-  readonly policy: UpdatePolicy;
-  readonly reason?: ForceReason;
-  readonly staleForMs?: number;
-  readonly now?: number;
-}
-
-/** Null when the client is current or unknown — no signal, no nag. */
-export function updateSignal(input: UpdateSignalInput): AppUpdateAvailable | null {
-  const state = detectSkew(input.clientBuildId, input.serverBuildId);
-  if (state !== 'stale') return null;
-
-  const reason = input.reason ?? 'never';
-  const staleForMs = input.staleForMs ?? 0;
-  const forced = input.policy.shouldForce(reason, staleForMs);
-  const now = input.now ?? Date.now();
-
-  return {
-    type: APP_UPDATE_AVAILABLE,
-    from: String(input.clientBuildId),
-    to: input.serverBuildId,
-    forced,
-    deadlineAt: forced ? now : null,
-  };
-}