@wmind/site-core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WMIND S.r.l.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# @wmind/site-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The product-independent core of the site SDK: an HTTP transport, request-driven refresh over one
+cache model, an atomic-swap snapshot, webhooks and status. Product modules (`@wmind/site-entitycms`,
+`@wmind/site-legal`) build on it; a site normally installs a module, not this package alone.
+
+- **Status:** MIT, final name. Version `0.0.0`, `private` and unpublished until the publishing plan
+  (changesets, the `wmind` npm organisation, a manual publish workflow).
+- **Runs on:** Node 22, browsers and edge runtimes (Cloudflare Workers, Vercel, Netlify). Web
+  platform APIs only (`fetch`, `Request`, `Response`, `crypto.subtle`, `AbortController`); zero
+  runtime dependencies.
+- **Is not:** a product client (no EntityCMS or Kit paths, headers or events) or a framework
+  adapter.
+- **Design:** `docs/superpowers/specs/2026-11-02-site-sdk-design.md` in the entitycms repository.
+
+## Rules a module author keeps
+
+1. **Requests drive refreshes.** No timer ever starts a refresh or an HTTP call. A copy past its
+   freshness is refreshed when a request asks for it; the flight is shared by every concurrent
+   request for the key (one per key and process) and is never cancelled. A flight that has not
+   settled after `refreshMaxMs` (60 s) is abandoned by the next request, which starts a new one;
+   the abandoned one writes nothing when it settles.
+2. **Budgets, not waits.** A request with a copy waits for the refresh at most `refreshBudgetMs`
+   (default 0: it answers with the copy at once); a request without one waits at most
+   `coldBudgetMs` (10 s), then gets `Unavailable` `refresh_budget_exceeded`. The refresh goes on and
+   the next request finds it. Pass `waitUntil` where the platform has one.
+3. **A copy never expires by time.** It is served until a refresh succeeds; `status()` shows its
+   age. `maxStaleMs` opts out. A full refresh answering the product's own 404 (the JSON error
+   envelope) deletes the copy; any other 404 (a load balancer's HTML page) and every other error
+   keep it and start the error pause: `errorPauseMs` (15 s), or the answer's `Retry-After` when
+   longer but at most `maxErrorPauseMs` (10 min), during which nothing is retried.
+4. **Keys carry the tenant, and the product when a module sets it.** A store key is
+   `encodeURIComponent(tenant):key`, or `encodeURIComponent(namespace)|encodeURIComponent(tenant):key`
+   with `createSiteCache({ namespace: 'legal' })`; a module should always set its namespace, so
+   products and tenants can share one memory store or one KV namespace.
+5. **Resources are declared, not made per request.** `site.resource()` keeps one entry per key
+   for the life of the process. A module keyed on request input (a document code from the URL)
+   checks the key against what exists before declaring a resource for it.
+6. **A `Snapshot` stays in a `MemoryCacheStore`.** It refuses JSON; a KV store reports
+   `store_unserialisable`.
+7. **Webhooks accelerate, the periodic full refresh guarantees.** `invalidate()` marks a copy due;
+   it never deletes it. Within one process the mark is never lost to a refresh landing at the same
+   time, and a copy a 404 deleted is never written back. Instances sharing a KV store are not
+   serialised (the store has no compare-and-set): a refresh on one instance can overwrite a mark
+   written by another, until the next full refresh.
+8. **Answers marked `no-store` or `private` are never stored.** EntityCMS marks every non-GET
+   answer so; read such endpoints in your own loader.
+
+## Known limits
+
+- **A loader slower than `refreshMaxMs` never lands.** Each request past `refreshMaxMs` (60 s)
+  abandons the running flight and starts another, and an abandoned flight writes nothing, so a
+  loader that always takes longer keeps restarting and its copy never moves. `httpResource` is
+  bounded by the transport's 30 s deadline and is not affected; a loader making several calls in a
+  row is. Set `refreshMaxMs` above the loader's worst case. A later version may let an abandoned
+  flight still write when the stored copy is older than its start.
+- **A store call that never settles blocks its key.** Writes to one key are queued in process, so a
+  `CacheStore` (or `KvBackend`) call that never settles leaves that key's later refresh writes and
+  `invalidate()` waiting for good; other keys are unaffected. Give the backend its own timeout. A
+  later version may bound store calls with a budget.
+
+## Quick start
+
+```ts
+import { createHttp, createSiteCache, httpResource } from '@wmind/site-core';
+
+const http = createHttp({
+  baseUrl: 'https://api.example.com',
+  auth: { bearer: process.env.API_KEY! }, // omit for a public API; never logged or shown
+  headers: { 'x-tenant-id': TENANT_ID },
+});
+
+const site = createSiteCache({
+  tenant: TENANT_ID,
+  namespace: 'legal', // the product module's prefix for every store key
+  // store: new KvCacheStore(backend) to share copies between instances
+  // policy: { fullEveryMs: 300_000 } overrides the answer's Cache-Control
+});
+
+const privacy = httpResource<{ title: string; html: string }>(site, http, {
+  key: 'doc:PRIVACY_POLICY:it',
+  request: { path: '/v1/documents/PRIVACY_POLICY', query: { lang: 'it' } },
+  preview: (token) => ({ headers: { 'x-preview-token': token } }),
+});
+
+// In a request handler (Astro, Next.js, a Worker…):
+const doc = await privacy.get({ waitUntil: ctx.waitUntil });
+const draft = await privacy.get(site.preview(token)); // this request only, never stored
+```
+
+Freshness defaults to the answer's `s-maxage`, else `max-age`, else 60 s; a 304 to the stored
+`ETag` keeps the copy. A module with its own loaders uses `site.resource({ key, full, partial? })`:
+`full` and `partial` answer `{ kind: 'value', value, etag?, cacheControl? }` or
+`{ kind: 'not_modified' }`, and `Snapshot.of(spec, rows)` / `snapshot.with({ upsert, remove })`
+build the next store apart from the one being served.
+
+## Webhooks
+
+```ts
+import { createWebhookHandler } from '@wmind/site-core';
+
+export const POST = createWebhookHandler({
+  secrets: [process.env.WEBHOOK_SECRET_NEW!, process.env.WEBHOOK_SECRET_OLD!], // during a rotation
+  signatureHeader: 'x-entitycms-signature', // the product module's header
+  onEvent: async (event) => {
+    if (event.event === 'entity.published') await privacy.invalidate();
+  },
+  status: site,
+});
+```
+
+- Header `t=<ts>,v1=<hex>[,v1=<hex>…]`, HMAC-SHA256 over `<ts>.<raw body bytes>`; any secret
+  matching any `v1` verifies; tolerance 300 s. One HMAC per secret whatever the header holds; a
+  header over 1,024 characters or with more than 8 `v1` is `malformed_signature_header`.
+- The body is capped at 1 MiB before any signature work (413).
+- A verified, well-formed event always answers 2xx, so a slow handler never makes the sender
+  disable the subscription. `budgetMs` (4 s, under EntityCMS's 5 s delivery timeout) counts from
+  the request's arrival: 204 when `onEvent` finished within it, 202 when it is still running
+  (handed to `waitUntil`) or failed (the failure goes to `status()` and the event can be resent).
+  A repeated event (the envelope `id`, else `ts` + body hash) is 200 `{ ok: true, deduped: true }`.
+- Refusals: 405, 415, 413, 401 `{ error: <reason> }` (`missing_signature`,
+  `malformed_signature_header`, `timestamp_outside_tolerance`, `signature_mismatch`), 400
+  `invalid_json` / `malformed_event`.
+
+## Status
+
+`site.status()` gives, per resource, the copy's age, the last full and partial refresh, whether a
+refresh is flying, the error pause and the last error; then the last webhook received, verified
+and rejected, and the most recent error. To serve it:
+
+```ts
+import { createStatusHandler } from '@wmind/site-core';
+
+export const GET = createStatusHandler({ token: process.env.SDK_STATUS_TOKEN!, site }); // >= 32 chars
+```
+
+It answers only `Authorization: Bearer <token>` (compared in constant time) and never shows the
+API bearer.
+
+## Errors
+
+Every error is a `SiteSdkError` with `code`, `status` (0 when there was no HTTP answer),
+`details`, `requestId` and, on 429, `retryAfterSeconds`. Subclasses: `NotFound` (a 404 carrying the
+product's JSON error envelope), `RateLimited` (429), `Unavailable` (502, 503, 504, any other 404,
+network, timeout, budgets). The transport
+retries 429 (after `Retry-After`) and 503 (400 ms · 2ⁿ, at most 6 times) within a 30 s deadline;
+it never retries a network error or a timeout.
+
+Codes this package mints:
+
+| Code | Class | When |
+|---|---|---|
+| `network_error`, `timeout` | `Unavailable` | no HTTP answer (status 0) |
+| `unexpected_response` | by status (`Unavailable` for a 404) | an answer that is not the JSON error envelope, a 2xx that is not JSON, a 304 to a request without `If-None-Match` |
+| `refresh_budget_exceeded` | `Unavailable` | no servable copy within the budget; `details.reason` `cold`, `max_stale` or `preview` |
+| `store_unavailable` | `Unavailable` | the cache store failed |
+| `refresh_abandoned` | `Unavailable` (status only) | a flight older than `refreshMaxMs` was replaced |
+| `store_unserialisable` | `SiteSdkError` | a value a KV store cannot hold as JSON |
+| `unexpected_not_modified` | `SiteSdkError` (304) | a loader answered `not_modified` with no copy |
+| `preview_unsupported` | `SiteSdkError` | a preview of an `httpResource` with no `preview` |
+
+Any other code is the API's own (`not_found`, `rate_limited`, `unauthorized`…), passed through.

package/dist/cache-control.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `Cache-Control` of an answer, read for the default freshness (spec §4.2.4): EntityCMS sends
+ * `s-maxage=60, stale-while-revalidate=3600`, the Kit's public API `max-age=300,
+ * stale-while-revalidate=86400`. Only `s-maxage`, else `max-age`, sets how long a copy is fresh;
+ * `stale-while-revalidate` never expires a copy (R9). A `no-store` or `private` answer is served
+ * to the requests waiting for it and never stored.
+ */
+export interface CacheControl {
+    maxAgeMs: number | null;
+    sMaxAgeMs: number | null;
+    staleWhileRevalidateMs: number | null;
+    noStore: boolean;
+    noCache: boolean;
+    private: boolean;
+}
+export declare function parseCacheControl(header: string | null): CacheControl;
+/** How long a copy is fresh: `no-cache` → 0; else `s-maxage`, else `max-age`, else null (R9). */
+export declare function freshForMs(cc: CacheControl): number | null;
+/** Whether a copy may be kept: neither `no-store` nor `private`. */
+export declare function isStorable(cc: CacheControl): boolean;

package/dist/cache-control.js

@@ -0,0 +1,69 @@
+/**
+ * `Cache-Control` of an answer, read for the default freshness (spec §4.2.4): EntityCMS sends
+ * `s-maxage=60, stale-while-revalidate=3600`, the Kit's public API `max-age=300,
+ * stale-while-revalidate=86400`. Only `s-maxage`, else `max-age`, sets how long a copy is fresh;
+ * `stale-while-revalidate` never expires a copy (R9). A `no-store` or `private` answer is served
+ * to the requests waiting for it and never stored.
+ */
+/** Delta-seconds as milliseconds, or null for anything but a non-negative integer. */
+function seconds(value) {
+    if (value === undefined)
+        return null;
+    const text = value
+        .trim()
+        .replace(/^"(.*)"$/, '$1')
+        .trim();
+    if (!/^\d+$/.test(text))
+        return null;
+    return Number(text) * 1000;
+}
+export function parseCacheControl(header) {
+    const cc = {
+        maxAgeMs: null,
+        sMaxAgeMs: null,
+        staleWhileRevalidateMs: null,
+        noStore: false,
+        noCache: false,
+        private: false,
+    };
+    if (!header)
+        return cc;
+    for (const part of header.split(',')) {
+        const eq = part.indexOf('=');
+        const name = (eq === -1 ? part : part.slice(0, eq)).trim().toLowerCase();
+        const value = eq === -1 ? undefined : part.slice(eq + 1);
+        switch (name) {
+            case 'max-age':
+                cc.maxAgeMs = seconds(value);
+                break;
+            case 's-maxage':
+                cc.sMaxAgeMs = seconds(value);
+                break;
+            case 'stale-while-revalidate':
+                cc.staleWhileRevalidateMs = seconds(value);
+                break;
+            case 'no-store':
+                cc.noStore = true;
+                break;
+            case 'no-cache':
+                cc.noCache = true;
+                break;
+            case 'private':
+                cc.private = true;
+                break;
+            default:
+                break;
+        }
+    }
+    return cc;
+}
+/** How long a copy is fresh: `no-cache` → 0; else `s-maxage`, else `max-age`, else null (R9). */
+export function freshForMs(cc) {
+    if (cc.noCache)
+        return 0;
+    return cc.sMaxAgeMs ?? cc.maxAgeMs;
+}
+/** Whether a copy may be kept: neither `no-store` nor `private`. */
+export function isStorable(cc) {
+    return !cc.noStore && !cc.private;
+}

package/dist/dedupe.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Webhook dedupe (spec §4.2 Webhook): a key is claimed once within its TTL. The in-memory store is
+ * per process, swept on each call and capped; it never sets a timer.
+ */
+export interface DedupeStore {
+    /** True the first time within `ttlSeconds`. */
+    claim(key: string, ttlSeconds: number): Promise<boolean>;
+    release(key: string): Promise<void>;
+}
+export interface MemoryDedupeStoreOptions {
+    /** Default `Date.now`. */
+    now?: () => number;
+    /** 10_000. */
+    maxEntries?: number;
+}
+export declare const DEFAULT_DEDUPE_MAX_ENTRIES = 10000;
+export declare class MemoryDedupeStore implements DedupeStore {
+    #private;
+    constructor(options?: MemoryDedupeStoreOptions);
+    claim(key: string, ttlSeconds: number): Promise<boolean>;
+    release(key: string): Promise<void>;
+}

package/dist/dedupe.js

@@ -0,0 +1,46 @@
+/**
+ * Webhook dedupe (spec §4.2 Webhook): a key is claimed once within its TTL. The in-memory store is
+ * per process, swept on each call and capped; it never sets a timer.
+ */
+export const DEFAULT_DEDUPE_MAX_ENTRIES = 10_000;
+export class MemoryDedupeStore {
+    /** key → expiry (ms), in claim order. */
+    #entries = new Map();
+    #now;
+    #maxEntries;
+    constructor(options = {}) {
+        const max = options.maxEntries ?? DEFAULT_DEDUPE_MAX_ENTRIES;
+        if (!Number.isInteger(max) || max < 1) {
+            throw new TypeError('MemoryDedupeStore: maxEntries must be an integer >= 1');
+        }
+        this.#now = options.now ?? Date.now;
+        this.#maxEntries = max;
+    }
+    async claim(key, ttlSeconds) {
+        const t = this.#now();
+        this.#sweep(t);
+        const expiresAt = this.#entries.get(key);
+        if (expiresAt !== undefined && t < expiresAt)
+            return false;
+        this.#entries.delete(key);
+        this.#entries.set(key, t + ttlSeconds * 1000);
+        while (this.#entries.size > this.#maxEntries) {
+            const oldest = this.#entries.keys().next();
+            if (oldest.done)
+                break;
+            this.#entries.delete(oldest.value);
+        }
+        return true;
+    }
+    async release(key) {
+        this.#entries.delete(key);
+    }
+    /** Drops expired keys from the front (claim order); a later expired key is caught on lookup. */
+    #sweep(t) {
+        for (const [key, expiresAt] of this.#entries) {
+            if (t < expiresAt)
+                break;
+            this.#entries.delete(key);
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The one error class of the site SDK (spec §4.2 Errori): `code`, `status`, `details`, `requestId`,
+ * `retryAfterSeconds?`, with subclasses only where a caller must tell them apart.
+ *
+ * An error never carries a `cause`: a platform error can hold the request, and the request holds
+ * the bearer, which must never appear in an error, a log or `status()`.
+ */
+export interface SiteSdkErrorInit {
+    code: string;
+    message: string;
+    /** The HTTP status; 0 when there was no HTTP answer. */
+    status: number;
+    details?: Readonly<Record<string, unknown>> | null;
+    requestId?: string | null;
+    retryAfterSeconds?: number;
+}
+export interface SiteSdkErrorJson {
+    name: string;
+    code: string;
+    message: string;
+    status: number;
+    details: Readonly<Record<string, unknown>> | null;
+    requestId: string | null;
+    retryAfterSeconds?: number;
+}
+export declare class SiteSdkError extends Error {
+    name: string;
+    readonly code: string;
+    readonly status: number;
+    readonly details: Readonly<Record<string, unknown>> | null;
+    readonly requestId: string | null;
+    readonly retryAfterSeconds?: number;
+    constructor(init: SiteSdkErrorInit);
+    toJSON(): SiteSdkErrorJson;
+}
+/** The resource does not exist (HTTP 404). */
+export declare class NotFound extends SiteSdkError {
+    name: string;
+}
+/** The API refused for rate (HTTP 429); `retryAfterSeconds` when the answer said. */
+export declare class RateLimited extends SiteSdkError {
+    name: string;
+}
+/** No usable answer: 502, 503, 504, a network error, a timeout, or a budget that elapsed. */
+export declare class Unavailable extends SiteSdkError {
+    name: string;
+}
+/** 404 → NotFound; 429 → RateLimited; 502, 503, 504 and status 0 with code network_error | timeout → Unavailable; else SiteSdkError. */
+export declare function siteSdkError(init: SiteSdkErrorInit): SiteSdkError;
+/** Seconds from `Retry-After` (delta-seconds or HTTP-date against `now`), undefined when absent or unreadable. */
+export declare function parseRetryAfter(value: string | null, now: number): number | undefined;
+/**
+ * Never throws. Reads `{ error: { code, message, details, requestId? } }` (both products),
+ * requestId from `X-Request-Id` first; on 429 retryAfterSeconds from the header, else
+ * `details.retryAfterSeconds`; a body that is not that envelope gives code `unexpected_response`
+ * and the message `${label} answered ${status}: <first 200 chars of the text, whitespace collapsed>`.
+ *
+ * Only a 404 that carries the envelope with a JSON content type is `NotFound` (review I2): the
+ * product says the resource is gone, and the engine deletes the copy (R5). Any other 404 (a load
+ * balancer's or a CDN's HTML page, a wrong route, plain text) is `Unavailable` `unexpected_response`:
+ * the copy is kept and the error pause starts.
+ */
+export declare function errorFromResponse(res: Response, label: string, now: number): Promise<SiteSdkError>;

package/dist/errors.js

@@ -0,0 +1,154 @@
+/**
+ * The one error class of the site SDK (spec §4.2 Errori): `code`, `status`, `details`, `requestId`,
+ * `retryAfterSeconds?`, with subclasses only where a caller must tell them apart.
+ *
+ * An error never carries a `cause`: a platform error can hold the request, and the request holds
+ * the bearer, which must never appear in an error, a log or `status()`.
+ */
+export class SiteSdkError extends Error {
+    name = 'SiteSdkError';
+    code;
+    status;
+    details;
+    requestId;
+    retryAfterSeconds;
+    constructor(init) {
+        super(init.message);
+        this.code = init.code;
+        this.status = init.status;
+        this.details = init.details ?? null;
+        this.requestId = init.requestId ?? null;
+        if (init.retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = init.retryAfterSeconds;
+    }
+    toJSON() {
+        const json = {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            status: this.status,
+            details: this.details,
+            requestId: this.requestId,
+        };
+        if (this.retryAfterSeconds !== undefined)
+            json.retryAfterSeconds = this.retryAfterSeconds;
+        return json;
+    }
+}
+/** The resource does not exist (HTTP 404). */
+export class NotFound extends SiteSdkError {
+    name = 'NotFound';
+}
+/** The API refused for rate (HTTP 429); `retryAfterSeconds` when the answer said. */
+export class RateLimited extends SiteSdkError {
+    name = 'RateLimited';
+}
+/** No usable answer: 502, 503, 504, a network error, a timeout, or a budget that elapsed. */
+export class Unavailable extends SiteSdkError {
+    name = 'Unavailable';
+}
+/** 404 → NotFound; 429 → RateLimited; 502, 503, 504 and status 0 with code network_error | timeout → Unavailable; else SiteSdkError. */
+export function siteSdkError(init) {
+    if (init.status === 404)
+        return new NotFound(init);
+    if (init.status === 429)
+        return new RateLimited(init);
+    if (init.status === 502 || init.status === 503 || init.status === 504) {
+        return new Unavailable(init);
+    }
+    if (init.status === 0 && (init.code === 'network_error' || init.code === 'timeout')) {
+        return new Unavailable(init);
+    }
+    return new SiteSdkError(init);
+}
+/** Seconds from `Retry-After` (delta-seconds or HTTP-date against `now`), undefined when absent or unreadable. */
+export function parseRetryAfter(value, now) {
+    if (value === null)
+        return undefined;
+    const text = value.trim();
+    if (text === '')
+        return undefined;
+    if (/^\d+$/.test(text))
+        return Number(text);
+    // An HTTP-date always names a weekday or a month; a bare signed number is not one.
+    if (!/[a-z]/i.test(text))
+        return undefined;
+    const at = Date.parse(text);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.ceil((at - now) / 1000));
+}
+const FALLBACK_TEXT_MAX = 200;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `application/json`, with parameters, or a `+json` type (`application/problem+json`). */
+function isJsonContentType(value) {
+    return /^application\/(?:[\w.-]+\+)?json\s*(?:;|$)/i.test((value ?? '').trim());
+}
+/**
+ * Never throws. Reads `{ error: { code, message, details, requestId? } }` (both products),
+ * requestId from `X-Request-Id` first; on 429 retryAfterSeconds from the header, else
+ * `details.retryAfterSeconds`; a body that is not that envelope gives code `unexpected_response`
+ * and the message `${label} answered ${status}: <first 200 chars of the text, whitespace collapsed>`.
+ *
+ * Only a 404 that carries the envelope with a JSON content type is `NotFound` (review I2): the
+ * product says the resource is gone, and the engine deletes the copy (R5). Any other 404 (a load
+ * balancer's or a CDN's HTML page, a wrong route, plain text) is `Unavailable` `unexpected_response`:
+ * the copy is kept and the error pause starts.
+ */
+export async function errorFromResponse(res, label, now) {
+    let text = '';
+    try {
+        text = await res.text();
+    }
+    catch {
+        text = '';
+    }
+    const headerRequestId = res.headers.get('x-request-id');
+    let envelope = null;
+    try {
+        const parsed = JSON.parse(text);
+        if (isRecord(parsed) && isRecord(parsed.error))
+            envelope = parsed.error;
+    }
+    catch {
+        envelope = null;
+    }
+    const code = envelope?.code;
+    const message = envelope?.message;
+    const productAnswer = res.status !== 404 || isJsonContentType(res.headers.get('content-type'));
+    if (envelope && typeof code === 'string' && typeof message === 'string' && productAnswer) {
+        const details = isRecord(envelope.details) ? envelope.details : null;
+        const bodyRequestId = typeof envelope.requestId === 'string' ? envelope.requestId : null;
+        let retryAfterSeconds;
+        if (res.status === 429) {
+            retryAfterSeconds = parseRetryAfter(res.headers.get('retry-after'), now);
+            const fromDetails = details?.retryAfterSeconds;
+            if (retryAfterSeconds === undefined &&
+                typeof fromDetails === 'number' &&
+                Number.isFinite(fromDetails) &&
+                fromDetails >= 0) {
+                retryAfterSeconds = fromDetails;
+            }
+        }
+        return siteSdkError({
+            code,
+            message,
+            status: res.status,
+            details,
+            requestId: headerRequestId ?? bodyRequestId,
+            ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+        });
+    }
+    const snippet = text.replace(/\s+/g, ' ').trim().slice(0, FALLBACK_TEXT_MAX);
+    const retryAfterSeconds = res.status === 429 ? parseRetryAfter(res.headers.get('retry-after'), now) : undefined;
+    const init = {
+        code: 'unexpected_response',
+        message: `${label} answered ${res.status}: ${snippet}`,
+        status: res.status,
+        requestId: headerRequestId,
+        ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+    };
+    return res.status === 404 ? new Unavailable(init) : siteSdkError(init);
+}

package/dist/freshness.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The pure freshness policy (spec §4.2.3): `decideRefresh(state, now, policy)` →
+ * `'full' | 'partial' | 'none'`, generalised from collieuganei's `src/lib/freshness.ts`. No clock,
+ * no I/O: the engine passes the time, and the product module decides what a full and a partial
+ * refresh are (a product without a partial sets `partialAvailable: false`).
+ */
+export interface FreshnessPolicy {
+    fullEveryMs: number;
+    /** Without it a partial runs only on invalidation. */
+    partialEveryMs?: number;
+    errorPauseMs: number;
+}
+export declare const DEFAULT_FULL_EVERY_MS = 60000;
+export declare const DEFAULT_ERROR_PAUSE_MS = 15000;
+export interface RefreshState {
+    /** Start of the last successful full refresh; null = no copy. */
+    lastFullAt: number | null;
+    /** Start of the last successful partial refresh. */
+    lastPartialAt: number | null;
+    invalidatedAt: number | null;
+    lastErrorAt: number | null;
+    partialAvailable: boolean;
+}
+export type RefreshDecision = 'full' | 'partial' | 'none';
+/**
+ * Order (load-bearing): pause → cold → full due → invalidated → partial due → none.
+ * - The error pause holds even a cold key (R4): one refresh per pause, not one per request.
+ * - Invalidated gives `partial` when one is available, else `full`.
+ * - The partial cadence counts from the later of the last full and the last partial refresh.
+ */
+export declare function decideRefresh(state: RefreshState, now: number, policy: FreshnessPolicy): RefreshDecision;

package/dist/freshness.js

@@ -0,0 +1,41 @@
+/**
+ * The pure freshness policy (spec §4.2.3): `decideRefresh(state, now, policy)` →
+ * `'full' | 'partial' | 'none'`, generalised from collieuganei's `src/lib/freshness.ts`. No clock,
+ * no I/O: the engine passes the time, and the product module decides what a full and a partial
+ * refresh are (a product without a partial sets `partialAvailable: false`).
+ */
+export const DEFAULT_FULL_EVERY_MS = 60_000;
+export const DEFAULT_ERROR_PAUSE_MS = 15_000;
+/**
+ * Whether `every` ms have passed since `at`. A negative elapsed time (the clock stepped back: NTP,
+ * a VM resume) counts as due, so a step back triggers one refresh instead of freezing them (R11).
+ */
+function due(at, now, every) {
+    const elapsed = now - at;
+    return elapsed < 0 || elapsed >= every;
+}
+/**
+ * Order (load-bearing): pause → cold → full due → invalidated → partial due → none.
+ * - The error pause holds even a cold key (R4): one refresh per pause, not one per request.
+ * - Invalidated gives `partial` when one is available, else `full`.
+ * - The partial cadence counts from the later of the last full and the last partial refresh.
+ */
+export function decideRefresh(state, now, policy) {
+    if (state.lastErrorAt !== null) {
+        const sinceError = now - state.lastErrorAt;
+        if (sinceError >= 0 && sinceError < policy.errorPauseMs)
+            return 'none';
+    }
+    if (state.lastFullAt === null)
+        return 'full';
+    if (due(state.lastFullAt, now, policy.fullEveryMs))
+        return 'full';
+    if (state.invalidatedAt !== null)
+        return state.partialAvailable ? 'partial' : 'full';
+    if (state.partialAvailable && policy.partialEveryMs !== undefined) {
+        const lastRefresh = Math.max(state.lastFullAt, state.lastPartialAt ?? state.lastFullAt);
+        if (due(lastRefresh, now, policy.partialEveryMs))
+            return 'partial';
+    }
+    return 'none';
+}

package/dist/http-resource.d.ts

@@ -0,0 +1,13 @@
+import type { FreshnessPolicy } from './freshness.js';
+import type { Http, HttpRequest } from './http.js';
+import type { Resource, SiteCache } from './site.js';
+export interface HttpResourceDefinition<T> {
+    key: string;
+    request: Omit<HttpRequest, 'etag'>;
+    /** Default: the body as is. */
+    map?: (body: unknown) => T;
+    policy?: Partial<FreshnessPolicy>;
+    /** What a preview request adds; without it a preview is `preview_unsupported`. */
+    preview?: (token: string) => Pick<HttpRequest, 'headers' | 'query'>;
+}
+export declare function httpResource<T>(site: SiteCache, http: Http, definition: HttpResourceDefinition<T>): Resource<T>;