@mesofact/runtime 0.8.29

package/src/routes.ts

@@ -0,0 +1,320 @@
+//! @yah:relay(R015, "Render cube support — placement axis + SSR build path + lint (W173)")
+//! @yah:at(2026-06-04T19:31:37Z)
+//! @yah:status(open)
+//! @yah:next("W173 lives in the yah parent camp at .yah/docs/working/W173-mesofact-render-cube.md (relative from mesofact root: ../../.yah/docs/working/W173-mesofact-render-cube.md). Read § 'v1 schema delta' and § 'SSR_PREFIXES derivation rule' before T1/T2.")
+//! @yah:next("yah-side consumer relay is R434 in the parent camp — R434-F3 (mesofact-dev SSR subprocess), R434-F4 (pond reconciler ssr_runtime), R434-F5 (first SSR consumer route) all assume this relay ships first.")
+//! @yah:next("Coordinate handoff via @mesofact/runtime version bump: yah-side consumes via packages/yah/workload-spec/index.ts and crates/yah/cloud/src/reconciler/mesofact_static.rs.")
+//! @yah:next("Order: T1 (schema) → T2 (build path) → then T3 + T4 unblock once a real SSR consumer exists on the yah side (R434-F5).")
+//!
+//! @yah:ticket(R015-F1, "Add Placement axis + placement?: field to RouteEntry + defineRoutes validation")
+//! @yah:assignee(agent:claude)
+//! @yah:at(2026-06-04T19:32:10Z)
+//! @yah:status(review)
+//! @yah:phase(P1)
+//! @yah:parent(R015)
+//! @yah:next("Add `export type Placement = \"host\" | \"edge\" | \"auto\"` alongside the existing RouteMode at routes.ts:5.")
+//! @yah:next("Add `placement?: Placement` to RouteEntry. ssr-only — reject (loud, at defineRoutes call site) on any non-\"ssr\" mode. Default \"auto\" → \"host\" today (auto-classifier deferred per W173).")
+//! @yah:next("RouteMode \"ssr\" slot already exists in this file — do NOT regress it. Do not remove or rename existing fields (requires, source_reads, concurrency, prerender, cache_policy.negative_ttl/vary).")
+//! @yah:next("Add a unit test that defineRoutes throws when placement is set on a static or spa route.")
+//! @yah:next("Place where the build classifier eventually slots in: comment that `placement: \"auto\"` resolves to \"host\" until the auto-classifier (W173 § 'Future auto-classifier criteria') lands.")
+//! @yah:verify("defineRoutes accepts every existing yah-side routes file (../../app/yah/web/marketing/mesofact.routes.ts and ../../app/yah/web/dashboard/mesofact.routes.ts) unchanged")
+//! @yah:verify("defineRoutes throws on `mode:\"static\", placement:\"host\"` etc.")
+//! @yah:verify("bun test passes for the new placement validation cases")
+//! @yah:handoff("Placement axis shipped. Changes to packages/mesofact-runtime/src/routes.ts: added `export type Placement = \"host\" | \"edge\" | \"auto\"`; added `placement?: Placement` to RouteEntry; defineRoutes now throws when placement is set on a non-ssr route (loud, names the offending route, default left undefined — auto-resolution happens at build time per W173). Exported Placement from src/index.ts. New tests/routes.test.ts covers 8 cases (ssr+host/edge/auto/undefined accepted; static+placement and spa+placement rejected; error message names route; mixed-mode workload accepted). Verified: bun test → 57 pass across 7 files; tsc --noEmit clean for runtime + build + worker; existing yah-side route files (marketing 5, dashboard 7, yah-dev 3) still parse unchanged.")
+//! @yah:verify("cd packages/mesofact-runtime && bun test — 57 pass")
+//! @yah:verify("cd packages/mesofact-runtime && bun run typecheck — clean")
+//! @yah:verify("cd packages/mesofact-build && bun run typecheck — clean")
+//! @yah:verify("cd packages/mesofact-worker && bun run typecheck — clean")
+
+// `mesofact.routes.ts` — user-authored route table. Build phase 2 reads this,
+// phase 3 infers `source_reads`, phase 4 validates, phase 6 emits the manifest.
+// See `.yah/docs/architecture/mesofact.md` §"Build pipeline".
+
+import { HOOK_NAMES, HOOK_ROUTE_CLAIMS, type HooksConfig, isHookName } from "./hooks.js";
+
+export type RouteMode = "static" | "ssr" | "spa";
+
+// Where per-request SSR rendering runs. Only meaningful for `mode:"ssr"`;
+// rejected at defineRoutes for static/spa. `"auto"` is the default — today
+// it resolves to `"host"` at build time. A future auto-classifier may pick
+// `"edge"` when criteria match (data-only sources, no host-only imports,
+// cacheable). See W173 § "Future auto-classifier criteria".
+export type Placement = "host" | "edge" | "auto";
+
+export type Requires = "user" | "project" | "region";
+
+export type CachePolicyConfig = {
+  ttl: number;
+  swr?: number;
+  negative_ttl?: number;
+  vary?: readonly string[];
+};
+
+// ─── Resilience axis (W181) ────────────────────────────────────────────────
+// Declarative retry / timeout applied at the always-up edge (CF Worker in
+// prod, the mesofact-dev proxy in dev) around the SSR origin hop. Not a cube
+// axis — it's the lifecycle wrapper around any `mode:"ssr"` cell. v1 ships
+// retry + timeout only; `queue` is type-reserved but rejected at validation
+// until v2 lands a real consumer (see W181 § "v1 scope").
+
+export type RetryOn = "connection" | "5xx" | "any";
+
+export type RetryPolicy = {
+  // Total attempts including the first; 1 = no retry.
+  attempts: number;
+  // Gap before attempt i+1; length must be `attempts - 1`.
+  backoff_ms: readonly number[];
+  // What failures trigger a retry. Default "connection" (ECONNREFUSED /
+  // fetch failure); "5xx" adds server errors; "any" adds everything non-2xx.
+  retry_on?: RetryOn;
+  // Total wall-clock cap across the request + all retries + backoffs. Must
+  // cover sum(backoff_ms) + attempts * per-attempt timeout when set.
+  budget_ms?: number;
+};
+
+// Reserved for v2 — the schema slot exists so v1 routes don't break when the
+// queue implementation lands, but `defineRoutes` rejects it today.
+export type QueuePolicy = {
+  queue: string;
+  ack: "on_enqueue" | "on_origin_2xx";
+  max_delay_ms?: number;
+};
+
+export type ResiliencePolicy = {
+  retry?: RetryPolicy;
+  queue?: QueuePolicy;
+  // Per-attempt request timeout; default 30_000.
+  timeout_ms?: number;
+};
+
+// Default per-attempt timeout used when `resilience.timeout_ms` is omitted.
+export const DEFAULT_RESILIENCE_TIMEOUT_MS = 30_000;
+
+// Literal param maps OR a source-derived query the publisher runs at build
+// time. Mode 1 routes only; non-parametric Mode 1 routes omit it.
+//
+// Three shapes:
+//   - { params }                    literal list, used as-is
+//   - { from, query, param }        registered source adapter (R2 BlobSource)
+//                                   walked at build time via async load
+//   - { from_data, items_key, param }
+//                                   local-JSON file already declared in the
+//                                   same route's `data_inputs`. Read
+//                                   synchronously, walked via `items_key` as
+//                                   a dotted/array path.
+//   - { deferred: true }            params are minted after the build
+//                                   (publish time). The build emits the
+//                                   server bundle + manifest entry and
+//                                   prerenders nothing; instances are
+//                                   produced exclusively through the
+//                                   render-only entrypoint and served per
+//                                   instance (instance-addressed route).
+//                                   mode:"static" + parametric route only.
+export type PrerenderConfig =
+  | { params: ReadonlyArray<Record<string, string>> }
+  | { from: string; query: string; param: string }
+  | { from_data: string; items_key: string; param: string }
+  | { deferred: true };
+
+// ─── Adding a field here (R749-T1) ─────────────────────────────────────────
+// Every field below that changes SERVING behaviour is checked at startup
+// against what the serving tier says it implements
+// (`crates/mesofact-core/src/policy.rs`). Declaring one a tier does not enforce
+// refuses the start, naming the route and the field — never a warning, never a
+// skip, because a policy nothing wired looks byte-identical to one that runs.
+//
+// So a new serving field costs two edits, not one: the type here, and either a
+// `RoutePolicy` variant plus an enforcement point per tier, or a
+// `STRUCTURAL_FIELDS` entry saying why ignoring it cannot lose behaviour. The
+// completeness gate (`every_route_field_is_classified`) fails until one of the
+// two exists, and until then the field refuses every manifest that carries it.
+//
+// A field with no consumer ANYWHERE follows `resilience.queue`: keep the type
+// slot so future routes don't break, and reject it at `defineRoutes` today.
+// Declaring something that does nothing is the defect, not the schema.
+export type RouteEntry = {
+  route: string;
+  mode: RouteMode;
+  entrypoint: string;
+  // Mode 3 (spa) only — the browser hydration entry. Required for `spa`
+  // routes; the build bundles it (browser target, content-hashed, code-split)
+  // to `dist/hydrate/` and records the result in the manifest's `hydration`.
+  client_entrypoint?: string;
+  requires?: readonly Requires[];
+  // Usually inferred by the build's adapter-import analysis. Setting it here
+  // is an explicit override (e.g. third-party module re-exporting an adapter).
+  source_reads?: readonly string[];
+  // Paths (relative to project root) of JSON files read as build-time data.
+  // Parsed content is passed to render() as `req.data[path]`. Mode 1 only.
+  // When any listed file changes, the route should be rebuilt.
+  data_inputs?: readonly string[];
+  cache_policy: CachePolicyConfig;
+  concurrency?: number;
+  prerender?: PrerenderConfig;
+  // SSR-only: where per-request rendering runs. Default `"auto"` resolves to
+  // `"host"` until the W173 auto-classifier ships.
+  placement?: Placement;
+  // SSR-only: declarative retry/timeout applied at the always-up edge (W181).
+  // No block = exactly today's behavior (one attempt, 30s timeout, 502 on
+  // failure). Rejected on static/spa and on placement:"edge" (retry-the-
+  // Worker-from-the-Worker is circular; reserved until an edge consumer
+  // needs it — W181 OQ1).
+  resilience?: ResiliencePolicy;
+};
+
+export type ErrorRoutes = {
+  "404"?: string;
+  "5xx"?: string;
+};
+
+export type RoutesConfig = {
+  routes: readonly RouteEntry[];
+  error_routes?: ErrorRoutes;
+  // Mode 2 endpoint callbacks (W311 §2 / R756-F6). Hook name → entrypoint
+  // path. A hook is engine-addressed, not path-addressed: Rust decides when
+  // to call it and owns the HTTP around it, so it is declared here beside
+  // `routes` rather than inside one. See `hooks.ts` for the vocabulary and
+  // why this shape rather than a per-route `middleware` field.
+  hooks?: HooksConfig;
+  // Origin for the manifest-derived sitemap (e.g. "https://yah.dev"), no
+  // trailing path. When set, the build emits `dist/sitemap.xml` listing every
+  // enumerable static route instance; instance-addressed (deferred) routes and
+  // `noindex` renders are excluded (W270 §4 — unlisted-by-capability means no
+  // sitemap participation). Omit to skip sitemap emission entirely.
+  site_url?: string;
+};
+
+export function defineRoutes(config: RoutesConfig): RoutesConfig {
+  if (config.site_url !== undefined && !/^https?:\/\/[^/]+/.test(config.site_url)) {
+    throw new Error(
+      `defineRoutes: site_url=${JSON.stringify(config.site_url)} must be an absolute origin like "https://yah.dev" (scheme + host, no trailing path) — the sitemap emitter joins it with each route's path`,
+    );
+  }
+  for (const r of config.routes) {
+    if (r.placement !== undefined && r.mode !== "ssr") {
+      throw new Error(
+        `defineRoutes: route ${r.route} has placement=${JSON.stringify(r.placement)} but mode=${JSON.stringify(r.mode)}; placement is only valid on mode:"ssr"`,
+      );
+    }
+    if (r.prerender && "from_data" in r.prerender) {
+      const declared = r.data_inputs ?? [];
+      if (!declared.includes(r.prerender.from_data)) {
+        throw new Error(
+          `defineRoutes: route ${r.route} has prerender.from_data=${JSON.stringify(r.prerender.from_data)} but that path is not in data_inputs (${JSON.stringify(declared)}); declare the file in data_inputs first so the build reads it once`,
+        );
+      }
+    }
+    if (r.prerender && "deferred" in r.prerender) {
+      if (r.prerender.deferred !== true) {
+        throw new Error(
+          `defineRoutes: route ${r.route} has prerender.deferred=${JSON.stringify(r.prerender.deferred)} — omit prerender (render once at build) or set deferred: true`,
+        );
+      }
+      if (r.mode !== "static") {
+        throw new Error(
+          `defineRoutes: route ${r.route} has prerender.deferred but mode=${JSON.stringify(r.mode)}; deferred (publish-time) params are only valid on mode:"static" — ssr renders per request, spa shells are not instance-addressed`,
+        );
+      }
+      if (!r.route.includes(":")) {
+        throw new Error(
+          `defineRoutes: route ${r.route} has prerender.deferred but no ":param" segment — a literal route has exactly one instance, rendered at build`,
+        );
+      }
+    }
+    if (r.resilience !== undefined) validateResilience(r);
+  }
+  if (config.hooks !== undefined) validateHooks(config);
+  return config;
+}
+
+// Mode 2 hook declaration (R756-F6). Same fail-fast home as placement and
+// resilience: throw at config import, before any bundling work.
+function validateHooks(config: RoutesConfig): void {
+  const hooks = config.hooks!;
+  for (const [name, entrypoint] of Object.entries(hooks)) {
+    if (!isHookName(name)) {
+      throw new Error(
+        `defineRoutes: unknown hook ${JSON.stringify(name)} — known hooks are ${HOOK_NAMES.map(
+          (h) => JSON.stringify(h),
+        ).join(", ")}. A hook name is engine-defined: only mesofact invokes hooks, so a name it ` +
+          `does not know would never be called.`,
+      );
+    }
+    if (typeof entrypoint !== "string" || entrypoint.trim() === "") {
+      throw new Error(
+        `defineRoutes: hooks.${name}=${JSON.stringify(entrypoint)} must be a non-empty entrypoint ` +
+          `path relative to the project root (e.g. "src/${name}.ts")`,
+      );
+    }
+    const claimed = HOOK_ROUTE_CLAIMS[name];
+    if (claimed !== undefined && config.routes.some((r) => r.route === claimed)) {
+      throw new Error(
+        `defineRoutes: hook ${JSON.stringify(name)} is declared twice — as hooks.${name} and by ` +
+          `claiming the route ${JSON.stringify(claimed)}. Both mean "this app contributes a ` +
+          `${name} verdict"; pick one. The hooks declaration is usually the one you want — the ` +
+          `module stays out of ssr_prefixes, so the edge never forwards ${claimed} to the SSR ` +
+          `origin and the Rust probe route never shadows it.`,
+      );
+    }
+  }
+}
+
+const RETRY_ON = new Set<RetryOn>(["connection", "5xx", "any"]);
+
+// W181 validation rules. Throws at defineRoutes time (fail fast at config
+// import, before any bundling work — same home as placement rejection).
+function validateResilience(r: RouteEntry): void {
+  const res = r.resilience!;
+  if (r.mode !== "ssr") {
+    throw new Error(
+      `defineRoutes: route ${r.route} declares resilience but mode=${JSON.stringify(r.mode)}; resilience is only valid on mode:"ssr" (the policy wraps the edge→origin proxy hop, which only exists for SSR routes)`,
+    );
+  }
+  if (r.placement === "edge") {
+    throw new Error(
+      `defineRoutes: route ${r.route} declares resilience on placement:"edge" — retrying the Worker from the Worker is circular (W181 OQ1); remove the block or use placement:"host"`,
+    );
+  }
+  if (res.queue !== undefined) {
+    throw new Error(
+      `defineRoutes: route ${r.route} declares resilience.queue — queue policy is reserved for v2 and not implemented yet (W181 § "v1 scope"); remove the block (the type slot exists so v1 routes won't break when v2 lands)`,
+    );
+  }
+  if (res.timeout_ms !== undefined && (!Number.isFinite(res.timeout_ms) || res.timeout_ms <= 0)) {
+    throw new Error(
+      `defineRoutes: route ${r.route} has resilience.timeout_ms=${String(res.timeout_ms)}; expected a positive number of milliseconds`,
+    );
+  }
+  const retry = res.retry;
+  if (retry === undefined) return;
+  if (!Number.isInteger(retry.attempts) || retry.attempts < 1) {
+    throw new Error(
+      `defineRoutes: route ${r.route} has resilience.retry.attempts=${String(retry.attempts)}; expected an integer >= 1 (1 = no retry)`,
+    );
+  }
+  if (!Array.isArray(retry.backoff_ms) || retry.backoff_ms.length !== retry.attempts - 1) {
+    throw new Error(
+      `defineRoutes: route ${r.route} has resilience.retry.backoff_ms of length ${Array.isArray(retry.backoff_ms) ? retry.backoff_ms.length : "?"}; expected attempts - 1 = ${retry.attempts - 1} entries (one gap between each pair of attempts)`,
+    );
+  }
+  if (retry.backoff_ms.some((b) => !Number.isFinite(b) || b < 0)) {
+    throw new Error(
+      `defineRoutes: route ${r.route} has a negative or non-numeric resilience.retry.backoff_ms entry`,
+    );
+  }
+  if (retry.retry_on !== undefined && !RETRY_ON.has(retry.retry_on)) {
+    throw new Error(
+      `defineRoutes: route ${r.route} has resilience.retry.retry_on=${JSON.stringify(retry.retry_on)}; expected "connection" | "5xx" | "any"`,
+    );
+  }
+  if (retry.budget_ms !== undefined) {
+    const perAttempt = res.timeout_ms ?? DEFAULT_RESILIENCE_TIMEOUT_MS;
+    const backoffSum = retry.backoff_ms.reduce((a, b) => a + b, 0);
+    const floor = backoffSum + retry.attempts * perAttempt;
+    if (retry.budget_ms < floor) {
+      throw new Error(
+        `defineRoutes: route ${r.route} has resilience.retry.budget_ms=${retry.budget_ms} < ${floor} (sum(backoff_ms)=${backoffSum} + attempts=${retry.attempts} × per-attempt timeout=${perAttempt}); raise budget_ms or lower the attempt/timeout shape`,
+      );
+    }
+  }
+}

package/src/source.ts

@@ -0,0 +1,91 @@
+// Adapter API surface. Read-only by design — mesofact has no write API.
+// See `.yah/docs/architecture/mesofact.md` §"Adapter API surface".
+//
+// The design doc lists `get`/`query`/`fetch`/`list` on a single interface with
+// per-backend annotations. We split them into BlobSource (r2) and
+// KeyValueSource (sqlite/pg) so callers get type-safety on what they hold:
+// `r2('assets').get(...)` is a type error, not a runtime trap.
+
+import { currentTrackCtx } from "./track-ctx.js";
+
+export type ListOpts = {
+  limit?: number;
+  cursor?: string;
+  delimiter?: string;
+};
+
+export type R2Object = {
+  key: string;
+  size: number;
+  last_modified: string;
+  etag?: string;
+};
+
+// Common shape every adapter exposes.
+export interface Source {
+  readonly name: string;
+
+  // Skip read-set tracking for the next call (e.g. fast-changing flags that
+  // would over-purge Mode 1 HTML). The override resets after one read.
+  noTrack(): this;
+
+  // Override the next call's timeout. Defaults: sqlite 100ms, pg 500ms,
+  // r2 2000ms. The override resets after one read.
+  timeout(ms: number): this;
+}
+
+// Blob backends (r2): byte payloads addressed by key or key prefix.
+export interface BlobSource extends Source {
+  fetch(key: string): Promise<Uint8Array | null>;
+  list(prefix: string, opts?: ListOpts): Promise<R2Object[]>;
+}
+
+// Row backends (sqlite, pg): tabular reads by id or query.
+export interface KeyValueSource extends Source {
+  get<T>(table: string, id: string): Promise<T | null>;
+  query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+
+// Shared impl for `.noTrack()` / `.timeout(ms)` and tag emission. Adapters
+// extend this and implement the read methods their backend supports.
+export abstract class BaseSource implements Source {
+  constructor(public readonly name: string) {}
+
+  noTrack(): this {
+    const ctx = currentTrackCtx();
+    if (ctx) ctx.next.track = false;
+    return this;
+  }
+
+  timeout(ms: number): this {
+    const ctx = currentTrackCtx();
+    if (ctx) ctx.next.timeout_ms = ms;
+    return this;
+  }
+
+  // Consume per-call overrides applied by the most recent `.noTrack()` /
+  // `.timeout(ms)` and return the effective settings for a single read. The
+  // override slot resets after this call, so two chained reads only carry the
+  // override on the first.
+  protected consumeOverrides(defaultTimeoutMs: number): {
+    track: boolean;
+    timeout_ms: number;
+  } {
+    const ctx = currentTrackCtx();
+    if (!ctx) return { track: true, timeout_ms: defaultTimeoutMs };
+    const effective = {
+      track: ctx.next.track,
+      timeout_ms: ctx.next.timeout_ms ?? defaultTimeoutMs,
+    };
+    ctx.next = { track: true };
+    return effective;
+  }
+
+  // Add a read-set tag to the ambient trackCtx, unless tracking was disabled
+  // for this call or there is no ctx (e.g. test harness running render outside
+  // `runInTrackCtx`).
+  protected emitTag(tag: string, track: boolean): void {
+    if (!track) return;
+    currentTrackCtx()?.tags.add(tag);
+  }
+}

package/src/track-ctx.ts

@@ -0,0 +1,29 @@
+// Per-render ambient context. Adapters in this package read it to register
+// read-set tags and honor `.noTrack()` / `.timeout(ms)` overrides. The worker
+// re-exports it for backward compatibility with R005's surface.
+//
+// See `.yah/docs/architecture/mesofact.md` §"Adapter read-set provenance".
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type TrackCtx = {
+  readonly tags: Set<string>;
+  // Per-call overrides toggled by `Source.noTrack()` / `.timeout(ms)`. The
+  // adapter consults these inside the same async chain and resets after the
+  // single read they apply to.
+  next: {
+    track: boolean;
+    timeout_ms?: number;
+  };
+};
+
+const storage = new AsyncLocalStorage<TrackCtx>();
+
+export function runInTrackCtx<T>(fn: () => Promise<T>): Promise<{ value: T; ctx: TrackCtx }> {
+  const ctx: TrackCtx = { tags: new Set(), next: { track: true } };
+  return storage.run(ctx, async () => ({ value: await fn(), ctx }));
+}
+
+export function currentTrackCtx(): TrackCtx | undefined {
+  return storage.getStore();
+}