@konneal/engine 0.2.21 → 0.2.23

package/dist/{chunk-YTWPZE5O.js → chunk-HYI32HMI.js}

@@ -1,33 +1,3 @@
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function __require() {
-  try {
-    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-  } catch (e) {
-    throw mod = 0, e;
-  }
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-
 // workers/worker_public/src/profile.gen.ts
 var PROFILE = {
   "publisher": {
@@ -176,8 +146,6 @@ function P() {
 }
 
 export {
-  __commonJS,
-  __toESM,
   setProfile,
   P
 };

package/dist/{chunk-COKARI7O.js → chunk-IOZAZA7Y.js}

@@ -1,10 +1,10 @@
 import {
   DATASETS,
   datasetAllowed
-} from "./chunk-RESCBSX6.js";
+} from "./chunk-434NRPSS.js";
 import {
   P
-} from "./chunk-YTWPZE5O.js";
+} from "./chunk-HYI32HMI.js";
 
 // workers/worker_public/src/requestScope.ts
 function licenseDeclared() {

package/dist/{chunk-SLZ4TZNO.js → chunk-PZLYPUYJ.js}

@@ -7,24 +7,24 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "./chunk-DGFJUA2C.js";
+} from "./chunk-HXWDVAVN.js";
 import {
   corsHeaders,
   err,
   json,
   readJson,
   validateQuery
-} from "./chunk-BV7IKH3N.js";
+} from "./chunk-FYGJDJPN.js";
 import {
   entitlementScope,
   standardKeysFrom
-} from "./chunk-COKARI7O.js";
+} from "./chunk-IOZAZA7Y.js";
 import {
   LIMITS,
   MODELS,
   num,
   sha256Hex
-} from "./chunk-RESCBSX6.js";
+} from "./chunk-434NRPSS.js";
 
 // workers/worker_public/src/search.ts
 async function handleSearch(env, ctx, req, tier, key) {

package/dist/{chunk-FNJ457SE.js → chunk-RZ3UZVRR.js}

@@ -1,6 +1,6 @@
 import {
   P
-} from "./chunk-YTWPZE5O.js";
+} from "./chunk-HYI32HMI.js";
 
 // workers/worker_public/src/refusal.ts
 function refusalAnswer() {

package/dist/livedata.d.ts

@@ -12,10 +12,9 @@ export interface LiveDataConfig {
     clientSecret?: string;
 }
 export declare function liveDataConfig(env: any): LiveDataConfig | null;
-/** Retain the sign-in's OP access token for the session's exchange
- *  window (the OP token's own TTL, minus a small margin). Called ONCE
- *  per sign-in from the auth callback; the token never persists past
- *  the window. */
+export declare function retainRefreshToken(env: any, sessionRaw: string, refreshToken: string): Promise<void>;
+export declare function readRefreshToken(env: any, sessionRaw: string): Promise<string | null>;
+export declare function dropRefreshToken(env: any, sessionRaw: string): Promise<void>;
 export declare function retainOpAccessToken(env: any, sessionRaw: string, opAccessToken: string, expiresInSec: number): Promise<void>;
 /** Drop the retained subject + the cached exchanged token (the sign-out
  *  closes the window deliberately, never by expiry alone). */

package/dist/oidc-refresh.d.ts

@@ -0,0 +1,19 @@
+import type { SessionClaims } from "./session";
+export interface RenewedSession {
+    claims: Omit<SessionClaims, "iat" | "exp">;
+    refreshToken: string;
+}
+export type RenewOutcome = {
+    kind: "ok";
+    renewed: RenewedSession;
+} | {
+    kind: "revoked";
+} | {
+    kind: "unavailable";
+};
+export declare function renewSessionClaims(env: any, cfg: {
+    issuer: string;
+    clientId: string;
+    clientSecret?: string;
+    sessionSecret: string;
+}, session: SessionClaims, sessionRaw: string): Promise<RenewOutcome>;

package/dist/oidc.d.ts

@@ -37,6 +37,7 @@ export declare function buildAuthorizationUrl(metadata: OidcMetadata, params: {
 export interface OidcTokenResponse {
     id_token: string;
     access_token?: string;
+    refresh_token?: string;
     token_type?: string;
     expires_in?: number;
 }

package/dist/refresh-core.d.ts

@@ -0,0 +1,28 @@
+import type { OidcIdTokenClaims, OidcTokenResponse } from "./oidc.ts";
+import type { SessionClaims } from "./session";
+export interface OidcMetadata {
+    token_endpoint: string;
+    jwks_uri: string;
+}
+export type RefreshResult = {
+    kind: "ok";
+    token: OidcTokenResponse;
+} | {
+    kind: "refused";
+} | {
+    kind: "unavailable";
+};
+/** The refresh grant's backchannel: the same shape as the code
+ *  exchange's POST (the OP's WAF wants the issuer's own origin), with
+ *  the three outcomes the renewal policy needs — a 400 is the OP
+ *  REFUSING (revocation, expiry: dead), a network throw is
+ *  unavailability (keep the session, retry next load). */
+export declare function refreshGrant(meta: OidcMetadata, cfg: {
+    clientId: string;
+    clientSecret?: string;
+}, refreshToken: string): Promise<RefreshResult>;
+/** The fresh session claims from the refresh grant's ID token. The sub
+ *  MUST match (a different account is a provisioning error, never an
+ *  update); every profile field falls back to the standing session's so
+ *  a claim the OP omits never erases what the user already had. */
+export declare function renewedSessionClaims(session: SessionClaims, claims: OidcIdTokenClaims): Omit<SessionClaims, "iat" | "exp"> | null;

package/dist/search-OJ776DMH.js

@@ -0,0 +1,12 @@
+import {
+  handleSearch
+} from "./chunk-PZLYPUYJ.js";
+import "./chunk-HXWDVAVN.js";
+import "./chunk-FYGJDJPN.js";
+import "./chunk-RZ3UZVRR.js";
+import "./chunk-IOZAZA7Y.js";
+import "./chunk-434NRPSS.js";
+import "./chunk-HYI32HMI.js";
+export {
+  handleSearch
+};

package/dist/worker_mcp/src/index.js

@@ -1,11 +1,11 @@
 import {
   authenticate
-} from "../../chunk-BV7IKH3N.js";
-import "../../chunk-RESCBSX6.js";
+} from "../../chunk-FYGJDJPN.js";
+import "../../chunk-434NRPSS.js";
 import {
   P,
   setProfile
-} from "../../chunk-YTWPZE5O.js";
+} from "../../chunk-HYI32HMI.js";
 
 // workers/worker_mcp/src/index.ts
 var PROTOCOL_VERSION = "2025-06-18";

package/dist/worker_public/src/config.js

@@ -16,8 +16,8 @@ import {
   roleModel,
   sha256Hex,
   today
-} from "../../chunk-RESCBSX6.js";
-import "../../chunk-YTWPZE5O.js";
+} from "../../chunk-434NRPSS.js";
+import "../../chunk-HYI32HMI.js";
 export {
   DATASETS,
   LIMITS,

package/dist/worker_public/src/index.js

@@ -1,13 +1,13 @@
 import {
   handleSearch
-} from "../../chunk-SLZ4TZNO.js";
+} from "../../chunk-PZLYPUYJ.js";
 import {
   checkQuoteAnchors,
   handleAsk,
   handleMemories,
   scoreJudge,
   standardForDocNumber
-} from "../../chunk-EE6V6X6D.js";
+} from "../../chunk-GZZWHWGM.js";
 import {
   buildMessages,
   citations,
@@ -29,7 +29,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "../../chunk-DGFJUA2C.js";
+} from "../../chunk-HXWDVAVN.js";
 import {
   authenticate,
   corsHeaders,
@@ -38,14 +38,14 @@ import {
   readJson,
   validateQuery,
   withCors
-} from "../../chunk-BV7IKH3N.js";
+} from "../../chunk-FYGJDJPN.js";
 import {
   canonicalRefusal
-} from "../../chunk-FNJ457SE.js";
+} from "../../chunk-RZ3UZVRR.js";
 import {
   entitlementScope,
   standardKeysFrom
-} from "../../chunk-COKARI7O.js";
+} from "../../chunk-IOZAZA7Y.js";
 import {
   LIMITS,
   MODELS,
@@ -56,11 +56,11 @@ import {
   roleModel,
   sha256Hex,
   today
-} from "../../chunk-RESCBSX6.js";
+} from "../../chunk-434NRPSS.js";
 import {
   P,
   setProfile
-} from "../../chunk-YTWPZE5O.js";
+} from "../../chunk-HYI32HMI.js";
 
 // workers/worker_public/src/conversations.ts
 var ID_RE = /^[a-zA-Z0-9_-]{8,64}$/;
@@ -979,7 +979,7 @@ async function handleMcp(env, ctx, req, tier, key) {
       // stream:false forces the JSON lane (anon defaults to SSE)
       body: JSON.stringify({ ...args, stream: false })
     });
-    const res = name === "ask" ? await (await import("../../ask-36JS3555.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-YA6TD6QJ.js")).handleSearch(env, ctx, inner, tier, key);
+    const res = name === "ask" ? await (await import("../../ask-U3DLB37U.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-OJ776DMH.js")).handleSearch(env, ctx, inner, tier, key);
     return res.json().catch(() => ({ error: { message: "tool transport failed", status: res.status } }));
   });
   if (out.ok && "accepted" in out) return new Response(null, { status: 202 });

package/dist/worker_public/src/profile.js

@@ -1,7 +1,7 @@
 import {
   P,
   setProfile
-} from "../../chunk-YTWPZE5O.js";
+} from "../../chunk-HYI32HMI.js";
 export {
   P,
   setProfile

package/dist/worker_public/src/refusal.js

@@ -1,8 +1,8 @@
 import {
   canonicalRefusal,
   refusalAnswer
-} from "../../chunk-FNJ457SE.js";
-import "../../chunk-YTWPZE5O.js";
+} from "../../chunk-RZ3UZVRR.js";
+import "../../chunk-HYI32HMI.js";
 export {
   canonicalRefusal,
   refusalAnswer

package/dist/worker_public/src/requestScope.js

@@ -4,9 +4,9 @@ import {
   requestSalt,
   resolveRequestScope,
   standardKeysFrom
-} from "../../chunk-COKARI7O.js";
-import "../../chunk-RESCBSX6.js";
-import "../../chunk-YTWPZE5O.js";
+} from "../../chunk-IOZAZA7Y.js";
+import "../../chunk-434NRPSS.js";
+import "../../chunk-HYI32HMI.js";
 export {
   entitlementScope,
   licenseDeclared,

package/package.json

@@ -16,19 +16,18 @@
     "gen:profile": "node scripts/gen_profile.mjs"
   },
   "devDependencies": {
+    "@astrojs/markdown-satteri": "^0.4.1",
+    "@astrojs/mdx": "^4.3.14",
     "@cloudflare/workers-types": "^5.20260911.1",
+    "@konneal/client": "^0.2.1",
+    "@pubid/pubid": "^0.1.5",
     "esbuild": "^0.28.2",
     "jsdom": "^29.1.1",
     "openapi-typescript": "^7.13.0",
     "playwright": "^1.62.1",
-    "yaml": "^2.9.1",
-    "@astrojs/markdown-satteri": "^0.4.1",
-    "@astrojs/mdx": "^4.3.14",
-    "@konneal/client": "^0.2.1",
-    "@oimlsmart/oiml-pubid": "^1.2.1"
+    "yaml": "^2.9.1"
   },
-  "dependencies": {},
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "The Konneal engine: the publisher-agnostic build pipeline and API plane for standards intelligence (retrieval, answer contract, verdicts, evaluation).",
   "license": "BSD-3-Clause",
   "type": "module",

package/workers/worker_public/src/auth.ts

@@ -14,6 +14,8 @@ import {
   OidcError,
 } from "./oidc";
 import { clearSessionCookie, mintSessionCookie, mintSessionToken, rawSessionToken, readSession, sessionCookieFromToken, SessionClaims } from "./session";
+import { renewSessionClaims } from "./oidc-refresh";
+import { retainRefreshToken } from "./livedata";
 import { bubbleConfirmPage, isAllowedBubbleOrigin } from "./bubble";
 import { dropOpAccessToken, retainOpAccessToken } from "./livedata";
 
@@ -47,6 +49,9 @@ export interface AuthConfig {
   sessionSecret: string;
 }
 
+// how long a session serves before renewal re-judges it against the OP
+const RENEW_AFTER_MS = 60 * 60 * 1000;
+
 function authConfig(env: any): AuthConfig | null {
   const issuer = (env.OIDC_ISSUER ?? "").trim().replace(/\/$/, "");
   const clientId = env.OIDC_CLIENT_ID;
@@ -89,7 +94,7 @@ export async function handleLogin(env: any, req: Request): Promise<Response> {
     const url = buildAuthorizationUrl(meta, {
       clientId: cfg.clientId,
       redirectUri: cfg.redirectUri,
-      scopes: "openid profile email roles",
+      scopes: "openid profile email roles offline_access",
       state,
       nonce,
       codeChallenge: pkce.challenge,
@@ -181,6 +186,11 @@ export async function handleCallback(env: any, req: Request): Promise<Response>
     if (typeof token.access_token === "string" && typeof token.expires_in === "number") {
       await retainOpAccessToken(env, session.token, token.access_token, token.expires_in);
     }
+    // the session's lifeline (oidc-refresh.ts): the OP's refresh token
+    // is what makes renewal a RE-JUDGMENT instead of a re-stamp
+    if (typeof token.refresh_token === "string" && token.refresh_token) {
+      await retainRefreshToken(env, session.token, token.refresh_token);
+    }
     // Bubble bridge: hand the session to the embedded panel as a Bearer
     // token via the confirm page — postMessage to the validated origin
     // ONLY, and only on the user's explicit click (bubble.ts). The
@@ -211,9 +221,34 @@ export async function handleMe(env: any, req: Request): Promise<Response> {
   const cfg = authConfig(env);
   const session = cfg ? await readSession(req, cfg.sessionSecret) : null;
   const headers: Record<string, string> = { "content-type": "application/json" };
-  // sliding renewal: a session older than a day re-mints on sight, so
-  // active users never hit the 7-day wall mid-conversation
-  if (session && cfg && Date.now() - session.iat > 24 * 3600 * 1000) {
+  // Renewal is a RE-JUDGMENT, not a re-stamp (oidc-refresh.ts): a
+  // session older than the threshold presents the OP's refresh token,
+  // whose grant re-judges the live standing — a deactivated account's
+  // grant family is dead, the OP refuses, and the session ENDS here
+  // instead of silently serving stale claims for a week. A session with
+  // no stored refresh token (pre-offline_access logins) falls back to
+  // the legacy re-stamp; a network refusal keeps the session and
+  // retries on the next load.
+  let effective: SessionClaims | null = session;
+  if (session && cfg && Date.now() - session.iat > RENEW_AFTER_MS) {
+    const raw = rawSessionToken(req);
+    if (raw) {
+      const renewed = await renewSessionClaims(env, { issuer: cfg.issuer, clientId: cfg.clientId, clientSecret: env.OIDC_CLIENT_SECRET, sessionSecret: cfg.sessionSecret }, session, raw);
+      if (renewed.kind === "ok") {
+        const freshClaims = renewed.renewed.claims;
+        const minted = await mintSessionToken(cfg.sessionSecret, freshClaims);
+        effective = { ...freshClaims, iat: Date.now(), exp: minted.expiresAt };
+        headers["set-cookie"] = sessionCookieFromToken(minted.token);
+      } else if (renewed.kind === "revoked") {
+        effective = null;
+        headers["set-cookie"] = clearSessionCookie();
+      }
+    }
+  }
+  if (effective && cfg && session && effective === session && Date.now() - session.iat > 24 * 3600 * 1000) {
+    // the legacy re-stamp: no refresh token available (pre-offline_access
+    // sessions) — the claims are what they were, but the 7-day wall still
+    // slides for active users
     headers["set-cookie"] = await mintSessionCookie(cfg.sessionSecret, {
       sub: session.sub,
       name: session.name,
@@ -224,12 +259,12 @@ export async function handleMe(env: any, req: Request): Promise<Response> {
   }
   return new Response(
     JSON.stringify({
-      authenticated: !!session,
-      name: session?.name ?? null,
-      email: session?.email ?? null,
-      picture: session?.picture ?? null,
-      roles: session?.roles ?? [],
-      tier: session ? "member" : "anon",
+      authenticated: !!effective,
+      name: effective?.name ?? null,
+      email: effective?.email ?? null,
+      picture: effective?.picture ?? null,
+      roles: effective?.roles ?? [],
+      tier: effective ? "member" : "anon",
       sign_in_available: !!cfg,
     }),
     { headers },

package/workers/worker_public/src/codecs.ts

@@ -24,14 +24,57 @@ export interface RefCodec {
   familyOf(docidentifier: string): string | null;
 }
 
-// The OIML grammar is @oimlsmart/oiml-pubid — the estate's single
-// source of truth (real tokenizer: editions, amendments, languages,
-// the CS family — beyond what any regex here carried). This codec's
-// job is the ADAPTATION: the parser takes the prefixed form and
-// returns null for everything else; our callers also send bare forms
-// ("R 60-1:2021") and the URN provenance shape. Corpi: the package
-// ships the shared conformance corpus; our tests run against it.
-import { parseOimlPubid } from "@oimlsmart/oiml-pubid";
+// The OIML grammar is the unified pubid grammar (@pubid/pubid's oiml
+// flavor — single-flavor import so the worker bundle carries the OIML
+// grammar and nothing else). This codec's job is the ADAPTATION: the
+// grammar takes the prefixed form and returns null for everything
+// else; our callers also send bare forms ("R 60-1:2021"), the URN
+// provenance shape, and the dual-published print ("ISO
+// 4064-1:2024|OIML R 49-1:2024") whose retrieval spine is its OIML
+// side, whichever side prints first. The estate's former grammar
+// (@oimlsmart/oiml-pubid) retired into this one (pubid/pubid-ts#63).
+import { oimlGrammarImplementation } from "@pubid/pubid/dist/flavors/oiml/implementation.js";
+
+const oimlParser = oimlGrammarImplementation();
+
+const TYPE_LETTER: Record<string, string> = {
+  recommendation: "R", document: "D", basic_publication: "B",
+  "basic-publication": "B", guide: "G", expert_report: "E",
+  "expert-report": "E", vocabulary: "V", seminar_report: "S",
+  "seminar-report": "S",
+};
+
+interface PubidHash {
+  _type?: string;
+  number?: string | number;
+  part?: string;
+  year?: string;
+  edition?: string;
+}
+
+/** The spine of a printed identifier through the unified grammar: the
+ *  type letter, the normalized number, the part and the edition year.
+ *  A dual-published print resolves to its OIML member (the caller picks
+ *  the side); unknown type kinds refuse — never a fabricated letter. */
+function parseOimlSpine(display: string): { doc_number: string; edition?: string; label: string } | null {
+  try {
+    const h = oimlParser.parse(display.trim()).toHash() as PubidHash;
+    if (h.number === undefined) return null;
+    const kind = String(h._type ?? "").split(":").pop() ?? "";
+    const letter = TYPE_LETTER[kind] ?? "";
+    if (!letter) return null;
+    const num = String(Number(h.number));
+    const part = h.part !== undefined ? String(h.part) : undefined;
+    const ed = h.year !== undefined ? String(h.year) : h.edition !== undefined ? String(h.edition) : undefined;
+    return {
+      doc_number: num,
+      ...(ed ? { edition: ed } : {}),
+      label: `OIML ${letter} ${num}${part ? `-${part}` : ""}${ed ? `:${ed}` : ""}`,
+    };
+  } catch {
+    return null;
+  }
+}
 
 /** urn:oiml:pub:r:60-1:2021 (pub) / urn:oiml:pub:cs:pd-06 (CS) → the
  *  prefixed display form the parser takes. */
@@ -44,8 +87,15 @@ const urnToDisplay = (u: string) => {
 };
 
 const parsePubid = (doc: string) => {
+  // a dual-published print: the OIML side is the spine, whichever side
+  // prints first — pick it before the bare-form normalization, which
+  // would mis-prefix the co-publisher's side
+  if (!/^urn:/i.test(doc) && doc.includes("|")) {
+    const side = doc.split("|").map((s) => s.trim()).find((s) => /^(?:OIML|oiml)\b/i.test(s));
+    return side ? parseOimlSpine(side) : null;
+  }
   const src = /^urn:/i.test(doc) ? urnToDisplay(doc) : /^(?:OIML|oiml)\b/i.test(doc) ? doc : `OIML ${doc}`;
-  return src ? parseOimlPubid(src) : null;
+  return src ? parseOimlSpine(src) : null;
 };
 
 /** OIML's grammar (delegated): type letter + 1–3 digits, optional part,
@@ -54,11 +104,12 @@ const parsePubid = (doc: string) => {
 export const oimlPubid: RefCodec = {
   parse(doc, edition) {
     const p = parsePubid(doc);
-    if (!p || p.series !== "pub") return null;
-    const type = p.family.toUpperCase();
-    const num = String(Number(p.number)); // R 060 → R 60 (display and steering agree)
-    const ed = edition ?? p.year ?? undefined;
-    return { doc_number: num, ...(ed ? { edition: ed } : {}), label: `OIML ${type} ${num}${p.part ? `-${p.part}` : ""}${ed ? `:${ed}` : ""}` };
+    if (!p) return null;
+    // the caller's edition is bibdata's truth — it wins over the print's
+    if (edition && p.edition !== edition) {
+      return { ...p, edition, label: p.label.split(":")[0] + `:${edition}` };
+    }
+    return p;
   },
   scanQuestion(query) {
     const re = /\b(OIML\s+)?([RDBGE])(\s*)0*(\d{1,3})(?:\s*[-–]\s*\d+)?(?:\s*:\s*(\d{4}))?/gi;
@@ -78,7 +129,10 @@ export const oimlPubid: RefCodec = {
   },
   familyOf(di) {
     const p = parsePubid(di);
-    if (p && p.series === "pub") return `${p.family.toUpperCase()}-${String(Number(p.number))}`;
+    if (p) {
+      const m = /^OIML ([A-Z]+) (\d{1,3})/.exec(p.label);
+      return m ? `${m[1]}-${m[2]}` : null;
+    }
     const m = /^(?:OIML\s+)?([A-Z])\s?(\d{1,3})(?:[-–]([0-9A-Za-z]+))?/.exec(di);
     return m ? `${m[1]}-${m[2]}` : null;
   },

package/workers/worker_public/src/livedata.ts

@@ -65,6 +65,41 @@ const EXCHANGED_KEY = (sessionHash: string) => `ossx:${sessionHash}`;
  *  window (the OP token's own TTL, minus a small margin). Called ONCE
  *  per sign-in from the auth callback; the token never persists past
  *  the window. */
+// The session's refresh-token store (oidc-refresh.ts): the OP's refresh
+// grant is what makes session renewal a RE-JUDGMENT of live standing
+// instead of a re-stamp of frozen claims. Same KV discipline as the
+// access token: keyed by the session token's hash, TTL = the grant's
+// own life, never D1.
+const REFRESH_KEY = (sessionHash: string) => `ort:${sessionHash}`;
+const REFRESH_TTL_SEC = 30 * 24 * 60 * 60; // the OP's grant TTL default
+
+export async function retainRefreshToken(env: any, sessionRaw: string, refreshToken: string): Promise<void> {
+  try {
+    await env.CACHE.put(REFRESH_KEY(await sha256Hex(sessionRaw)), JSON.stringify({ token: refreshToken }), {
+      expirationTtl: REFRESH_TTL_SEC,
+    });
+  } catch {
+    // a KV hiccup degrades to the legacy staleness, never blocks sign-in
+  }
+}
+
+export async function readRefreshToken(env: any, sessionRaw: string): Promise<string | null> {
+  try {
+    const hit = await env.CACHE.get(REFRESH_KEY(await sha256Hex(sessionRaw)), "json");
+    return typeof hit?.token === "string" ? hit.token : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function dropRefreshToken(env: any, sessionRaw: string): Promise<void> {
+  try {
+    await env.CACHE.delete(REFRESH_KEY(await sha256Hex(sessionRaw)));
+  } catch {
+    // best effort
+  }
+}
+
 export async function retainOpAccessToken(
   env: any,
   sessionRaw: string,