@mesofact/runtime 0.8.29

package/src/health.ts

@@ -0,0 +1,99 @@
+// `defineReadyz` — the TSX half of mesofact's `/readyz` probe.
+//
+// mesofact serves `/livez` and `/readyz` itself, in Rust
+// (`crates/mesofact/src/health.rs`), gated on the things only the engine can
+// know: is the SSR isolate up, is there a tree to serve, are we draining. An
+// app opts into contributing its own readiness by declaring the path as an
+// ordinary SSR route — there is no config key and no manifest field:
+//
+//   // mesofact.routes.ts
+//   { route: "/readyz", mode: "ssr", entrypoint: "src/readyz.ts", cache_policy: { ttl: 0 } }
+//
+// The Rust handler notices the app claimed the path, dispatches to it while
+// answering the probe, and folds the response status into its own listing as a
+// check named `app`. Anything outside 2xx takes the pod out of rotation.
+//
+// # The contract, and its one asymmetry
+//
+// An app verdict is **additive**: it can only make the process less ready. A
+// 200 from here cannot un-drain a terminating process or overrule a dead
+// isolate, because those are exactly the states in which app code is the
+// unreliable narrator. Design your checks accordingly — this is the place to
+// say "my database pool is exhausted", not "ignore the engine, I'm fine".
+//
+// # Vanilla, or this helper
+//
+// The route is a plain Fetch handler, so vanilla works and owes nothing to this
+// module:
+//
+//   export default async () =>
+//     (await db.ping()) ? new Response("ok") : new Response("db", { status: 503 });
+//
+// `defineReadyz` is the opt-in ergonomic layer: it runs named checks and emits
+// the *same* wire format the Rust side emits — the kube-apiserver `[+]name ok`
+// listing under `?verbose`. Matching formats is the point. An operator running
+// `curl localhost:3000/readyz?verbose` should not be able to tell which
+// language answered, and when the Rust side aggregates, the two listings nest
+// instead of clashing.
+
+/** One named readiness condition. `check` should be fast and side-effect free —
+ *  probes run on the kubelet's schedule, per replica. */
+export type ReadyCheck = {
+  /** Operator-facing name in `?verbose` output. A noun (`db`, `cache`). */
+  name: string;
+  check: () => boolean | Promise<boolean>;
+};
+
+/** Build the Fetch handler for a `mode:"ssr"` `/readyz` route.
+ *
+ *  Every check runs, even after one fails: reporting only the first failure
+ *  hides a second broken subsystem behind the first. A check that throws counts
+ *  as failed — an exception is not an assertion of readiness. */
+export function defineReadyz(
+  checks: readonly ReadyCheck[],
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    const results = await Promise.all(
+      checks.map(async (c) => {
+        try {
+          return { name: c.name, pass: (await c.check()) === true };
+        } catch {
+          return { name: c.name, pass: false };
+        }
+      }),
+    );
+
+    const ok = results.every((r) => r.pass);
+    const status = ok ? 200 : 503;
+    const headers = {
+      "content-type": "text/plain; charset=utf-8",
+      // A cached 200 outlives the condition it described, which is the exact
+      // failure the probe exists to catch.
+      "cache-control": "no-cache, no-store, must-revalidate",
+    };
+
+    if (!isVerbose(req)) {
+      return new Response(ok ? "ok\n" : "readyz check failed\n", {
+        status,
+        headers,
+      });
+    }
+
+    const listing = results
+      .map((r) => (r.pass ? `[+]${r.name} ok\n` : `[-]${r.name} failed\n`))
+      .join("");
+    const trailer = ok ? "readyz check passed\n" : "readyz check failed\n";
+    return new Response(listing + trailer, { status, headers });
+  };
+}
+
+/** `?verbose` / `?verbose=1`, matching the Rust `is_verbose`. A malformed URL
+ *  means the non-verbose body, never a crash — a probe that 500s because it
+ *  could not parse its own URL is worse than one that answers tersely. */
+function isVerbose(req: Request): boolean {
+  try {
+    return new URL(req.url).searchParams.has("verbose");
+  } catch {
+    return false;
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,72 @@
+// Mode 2 hook declaration — W311 §2 "Open Decision 1", answered by R756-F6.
+//
+// # What a hook is
+//
+// mesofact's TSX override surface has two modes (W311 §2). Mode 1 is the
+// general API: `mode:"ssr"` route, `Request -> Response`, the app owns the
+// wire. Mode 2 is the endpoint callback: a small `input -> verdict`, and
+// **Rust** owns the HTTP. R756-F3 shipped Mode 2's wire verb
+// (`__mesofact_ssr.invoke(bundle, hookName, input)`) but hardcoded its single
+// hook name, because `/readyz` — Mode 2's only consumer — could reuse the
+// route-claim opt-in it already had. A hook that is *not* a path (`onRequest`,
+// `onError`, an auth gate) has no route to claim, so it needs a declaration
+// site. This is that site.
+//
+// # Why a top-level `hooks` key, and not a per-route `middleware` field
+//
+// W311 named two candidates and deliberately picked neither. The `hooks` key
+// wins on the doc's own terms:
+//
+//   - A per-route `middleware` field is a *chain*, and "a general TS
+//     middleware chain" is an explicit W311 non-goal — it has ordering
+//     semantics (what runs before what, who may short-circuit, how errors
+//     propagate) that Mode 2 does not have and does not want.
+//   - Mode 2's defining property is that Rust owns the HTTP. A hook is
+//     therefore engine-addressed — the engine decides when to call `readyz`,
+//     not a route table — so the declaration belongs beside `routes`, not
+//     inside one.
+//   - Hook names are a **closed set** for the same reason: only the engine
+//     invokes a hook, so a name the engine does not know is dead code and a
+//     silent typo. Adding one is three deliberate edits — a name here, an
+//     adapter in `crates/mesofact-ssr/js/ssr_harness.js`, and the Rust call
+//     site that decides when it runs — and each is a real contract statement.
+//
+// # Adding a hook
+//
+// Add the name to `HOOK_NAMES`, teach `ssr_harness.js` how to call it (the
+// default is plain Mode 2 — `(input) => verdict`, JSON both ways), and write
+// the Rust call site. `hooks` in the manifest carries name → bundled module;
+// `mesofact::ssr::spawn` registers each one on every isolate in the pool and
+// `SsrChild::invoke_hook(name, input)` calls it.
+
+/** Every hook name the engine knows how to invoke.
+ *
+ *  `readyz` is the one hook that predates this declaration site, so it has two
+ *  ways in (see {@link HOOK_ROUTE_CLAIMS}) and its module's contract is a
+ *  Fetch handler rather than a plain Mode 2 function. Hooks added from here on
+ *  are `(input) => verdict`. */
+export const HOOK_NAMES = ["readyz"] as const;
+
+export type HookName = (typeof HOOK_NAMES)[number];
+
+/** The `hooks` block of `defineRoutes` — hook name → entrypoint path, relative
+ *  to the project root, bundled to `dist/server/hooks/<name>.js`. */
+export type HooksConfig = { readonly [K in HookName]?: string };
+
+/** Hooks that may *alternatively* be declared by claiming a route, which is
+ *  how `/readyz` shipped (R756-F5) before hooks existed.
+ *
+ *  Route-claiming still works and is still the shortest path for an app that
+ *  wants its readiness handler reachable as an ordinary Fetch handler. The
+ *  `hooks` declaration is the better one for everything else: the module is
+ *  not a route, so it never enters `ssr_prefixes`, is never forwarded to the
+ *  SSR origin by the edge Worker, and is never shadowed by the Rust probe
+ *  route it would otherwise collide with. Declaring both is rejected — two
+ *  opt-ins for one verdict is ambiguous, not additive. */
+export const HOOK_ROUTE_CLAIMS: { readonly [K in HookName]?: string } = {
+  readyz: "/readyz",
+};
+
+export function isHookName(name: string): name is HookName {
+  return (HOOK_NAMES as readonly string[]).includes(name);
+}

package/src/hydration.ts

@@ -0,0 +1,72 @@
+// Hydration handoff — helpers an SSR route's Fetch handler calls to inline
+// server-resolved data into the response body for the client to read on
+// mount. Disposable when RSC streaming lands; until then this is the
+// Universal cell's contract (W173 § "Hydration handoff").
+//
+// API surface is intentionally minimal — two pure functions. The handler
+// composes them into its own HTML response, which means the consumer keeps
+// full control over the document shell. The trade-off is that the consumer
+// has to know its own build_id + hashed client-script name (read from the
+// manifest at boot, or inject via env). Acceptable for the dogfood window;
+// revisit when more consumers exist.
+//
+// Also published standalone as the `@mesofact/runtime/hydration` subpath
+// export (R513-B11): this file must stay free of imports (or only import
+// other import-free, browser-safe modules) so a client bundle can read
+// `SPA_STATE_SCRIPT_ID` without dragging in the `@mesofact/runtime` barrel,
+// which re-exports server-only code (`track-ctx.ts` → `node:async_hooks`,
+// `config.ts` → `node:fs`) that rolldown can't tree-shake past.
+
+// Build-time SPA shell consumes this id; the prerender weaves it in.
+export const SPA_STATE_SCRIPT_ID = "__MESOFACT_STATE__" as const;
+
+// Per-request SSR Universal handoff consumes this id; see W173 § "Hydration
+// handoff" — the name is fixed (not configurable) so the client snippet can
+// be copy-pasteable across consumers.
+export const SSR_DATA_SCRIPT_ID = "__mesofact_data__" as const;
+
+// JSON-encode `value` and escape the characters that could close the parent
+// `<script>` tag early or be reinterpreted by the HTML parser:
+//
+//   `<`, `>`, `&`         — `</script>`, `<!--`, `<![CDATA[`, `&amp;` injection
+//   U+2028 / U+2029       — JS line separators valid in JSON but break inline
+//                           scripts when not escaped
+//
+// `JSON.parse` decodes the `\uXXXX` escapes transparently, so the client
+// reads back the original value via `JSON.parse(el.textContent)` with no
+// special handling. Non-negotiable per W173 § "XSS escape rule".
+export function escapeJsonForScriptTag(value: unknown): string {
+  return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (c) => {
+    switch (c) {
+      case "<":
+        return "\\u003c";
+      case ">":
+        return "\\u003e";
+      case "&":
+        return "\\u0026";
+      case "\u2028":
+        return "\\u2028";
+      case "\u2029":
+        return "\\u2029";
+      default:
+        return c;
+    }
+  });
+}
+
+// Serialize `data` into the data-handoff `<script>` tag an SSR route's
+// Fetch handler inlines into its response body. Read back on the client via
+// `JSON.parse(document.getElementById("__mesofact_data__").textContent)`.
+export function hydrationDataTag(data: unknown): string {
+  return `<script id="${SSR_DATA_SCRIPT_ID}" type="application/json">${escapeJsonForScriptTag(data)}</script>`;
+}
+
+// Build the module-script tag that loads the route's hydrate bundle. `src`
+// is escaped against `"`, `<`, and `&` so a manifest-derived URL containing
+// a stray quote can't break the attribute or the tag boundary; belt-and-
+// braces — the manifest paths the build emits don't contain quotes, but
+// consumers may compose paths from request data.
+export function hydrationScriptTag(src: string): string {
+  const safeSrc = src.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+  return `<script type="module" src="${safeSrc}"></script>`;
+}

package/src/index.ts

@@ -0,0 +1,113 @@
+// @mesofact/runtime — render contract types and adapter API.
+// See `.yah/docs/architecture/mesofact.md`.
+
+export type {
+  Region,
+  User,
+  Project,
+  RenderRequest,
+  CachePolicy,
+  Hydration,
+  RenderResult,
+  RenderFn,
+} from "./contract.js";
+
+export type {
+  ListOpts,
+  R2Object,
+  Source,
+  BlobSource,
+  KeyValueSource,
+} from "./source.js";
+export { BaseSource } from "./source.js";
+
+export {
+  SourceError,
+  SourceUnavailableError,
+  SourceTimeoutError,
+  SourceQueryError,
+  RowNotFoundError,
+} from "./errors.js";
+
+export type {
+  RouteMode,
+  Placement,
+  Requires,
+  CachePolicyConfig,
+  PrerenderConfig,
+  RouteEntry,
+  ErrorRoutes,
+  RoutesConfig,
+  RetryOn,
+  RetryPolicy,
+  QueuePolicy,
+  ResiliencePolicy,
+} from "./routes.js";
+
+export { defineRoutes, DEFAULT_RESILIENCE_TIMEOUT_MS } from "./routes.js";
+
+export type { HookName, HooksConfig } from "./hooks.js";
+export { HOOK_NAMES, HOOK_ROUTE_CLAIMS, isHookName } from "./hooks.js";
+
+export type {
+  ManifestVersion,
+  ManifestCachePolicy,
+  ManifestHydration,
+  ManifestPrerender,
+  ManifestRoute,
+  ManifestStaticAsset,
+  ManifestErrorRoutes,
+  ManifestHook,
+  ManifestHooks,
+  Manifest,
+  ResolvedPlacement,
+} from "./manifest.js";
+
+export { MANIFEST_VERSION } from "./manifest.js";
+
+export type {
+  SourceScope,
+  SourceCatalog,
+  ValidationError,
+  ValidationErrorKind,
+  ValidationResult,
+} from "./validate.js";
+
+export { validate } from "./validate.js";
+
+export { runInTrackCtx, currentTrackCtx } from "./track-ctx.js";
+export type { TrackCtx } from "./track-ctx.js";
+
+export {
+  SPA_STATE_SCRIPT_ID,
+  SSR_DATA_SCRIPT_ID,
+  escapeJsonForScriptTag,
+  hydrationDataTag,
+  hydrationScriptTag,
+} from "./hydration.js";
+
+export type { OpenGraph, TwitterCard, HeadLink, Head } from "./head.js";
+export { renderHead, weaveHead } from "./head.js";
+
+export { defineReadyz } from "./health.js";
+export type { ReadyCheck } from "./health.js";
+
+export { R2Adapter, r2, registerR2, clearR2Registry } from "./adapters/r2.js";
+export type { R2Config } from "./adapters/r2.js";
+
+export { SqliteAdapter, sqlite, registerSqlite, clearSqliteRegistry } from "./adapters/sqlite.js";
+export type { SqliteConfig, SqliteRunner } from "./adapters/sqlite.js";
+
+export {
+  loadConfig,
+  parseConfig,
+  registerSourcesFromConfig,
+  ConfigError,
+} from "./config.js";
+export type {
+  BuildConfig,
+  MesofactConfig,
+  R2SourceConfig,
+  SqliteSourceConfig,
+  SourceConfig,
+} from "./config.js";

package/src/manifest.ts

@@ -0,0 +1,104 @@
+// Manifest types — the single document the build emits and the proxy boots
+// from. Authored shape lives in `routes.ts` (RoutesConfig); the build enriches
+// it with `build_id`, `static_assets`, hydration, and resolved entrypoint
+// paths.
+//
+// Versioned independently of the mesofact binary; major bumps force restart.
+// See `.yah/docs/architecture/mesofact.md` §"Manifest schema".
+
+import type { HookName } from "./hooks.js";
+import type { Placement, ResiliencePolicy, RouteMode, Requires } from "./routes.js";
+
+// Placement as carried in the manifest — the build resolves `"auto"` to
+// `"host"` or `"edge"` before emission, so consumers never see `"auto"`.
+// See W173 § "Placement: validation rules".
+export type ResolvedPlacement = Exclude<Placement, "auto">;
+
+export const MANIFEST_VERSION = "1" as const;
+
+export type ManifestVersion = typeof MANIFEST_VERSION;
+
+export type ManifestCachePolicy = {
+  ttl: number;
+  swr?: number;
+  negative_ttl?: number;
+  vary?: readonly string[];
+};
+
+export type ManifestHydration = {
+  script: string;
+  code_split: readonly string[];
+};
+
+export type ManifestPrerender =
+  | { params: ReadonlyArray<Record<string, string>> }
+  | { from: string; query: string; param: string }
+  | { from_data: string; items_key: string; param: string }
+  // Instance-addressed: params are minted after the build (publish time); the
+  // build emits the server bundle + manifest entry and prerenders nothing.
+  // Serving resolves each instance through the pointer store (W270 §2). Mirrors
+  // `Prerender::Deferred` in `crates/mesofact/src/manifest.rs`.
+  | { deferred: true };
+
+export type ManifestRoute = {
+  route: string;
+  mode: RouteMode;
+  render_entrypoint: string;
+  requires?: readonly Requires[];
+  source_reads?: readonly string[];
+  // Build-time data artifact paths (relative to project root). Present when
+  // the route declared `data_inputs`; used by the reconciler to detect which
+  // file changes trigger a rebuild of this route.
+  data_inputs?: readonly string[];
+  cache_policy: ManifestCachePolicy;
+  concurrency?: number;
+  hydration?: ManifestHydration;
+  prerender?: ManifestPrerender;
+  // SSR routes only; never "auto" (resolved at build time per W173).
+  placement?: ResolvedPlacement;
+  // SSR routes only (W181). Carried verbatim from the route declaration so
+  // the Worker (prod) and the mesofact-dev proxy (dev) apply the same retry/
+  // timeout policy around the origin hop. Absent = one attempt, default
+  // timeout, fail with 502 — exactly the pre-W181 behavior.
+  resilience?: ResiliencePolicy;
+};
+
+export type ManifestStaticAsset = {
+  key: string;
+  content_hash: string;
+  content_type: string;
+  immutable: boolean;
+};
+
+export type ManifestErrorRoutes = {
+  "404"?: string;
+  "5xx"?: string;
+};
+
+// One declared Mode 2 hook (W311 §2 / R756-F6). An object rather than a bare
+// path string because the per-hook options W311 left open — chiefly "may this
+// hook be async" (Open Decision 3) — land here without a schema break.
+export type ManifestHook = {
+  // Bundled module, `dist/server/hooks/<name>.js`. Same shape and resolution
+  // rule as a route's `render_entrypoint`.
+  entrypoint: string;
+};
+
+export type ManifestHooks = { readonly [K in HookName]?: ManifestHook };
+
+export type Manifest = {
+  version: ManifestVersion;
+  build_id: string;
+  routes: readonly ManifestRoute[];
+  static_assets: readonly ManifestStaticAsset[];
+  error_routes?: ManifestErrorRoutes;
+  // Declared Mode 2 hooks, name → bundled module. Absent when the workload
+  // declares none. Host-only: the edge Worker never invokes a hook, because
+  // Mode 2's whole premise is that the Rust host owns the HTTP around it.
+  hooks?: ManifestHooks;
+  // Derived from every `mode:"ssr"` route per W173 § "SSR_PREFIXES derivation
+  // rule". Used by mesofact-dev (proxy) and the CF Worker to forward matching
+  // paths to the SSR runtime. Segment-aware match: `path === p || path.startsWith(p + "/")`.
+  // Absent when the workload has no SSR routes.
+  ssr_prefixes?: readonly string[];
+};