fix(astro): SDK preflight check + implicit-mode default to opt out of inherited public_paths

Kychon's v1.2.0 re-test surfaced two issues neither the helper nor the
gateway-side work caught:

1. SDK version mismatch surfaced as a misleading error.

   The helper emits `class: 'ssr'` (gateway v1.52+ field). `@run402/sdk`
   versions older than 2.18.0 don't include `class` in their local
   `FUNCTION_SPEC_FIELDS` allowlist, so `validateKnownFields` rejects
   the spec LOCALLY before any network call with the message
   "Unknown ReleaseSpec field: functions.replace.<name>.class". The
   error looks gateway-shaped (phase: "validate") but doesn't carry a
   trace_id — that's because there's never been a request.

   Fix: bumped peerDep `@run402/sdk` from `>=2.3` to `>=2.18.0`, and
   added a runtime preflight (`assertSdkSupportsClassField`) that reads
   `@run402/sdk/package.json` via createRequire and throws a precise
   `Run402AstroSdkVersionError` with the installed vs required versions
   and an actionable suggestedFix
   (`npm install @run402/sdk@latest run402@latest`).

2. Inherited explicit public_paths blocked the deploy AFTER the class
   field landed.

   The gateway's `resolvePublicPathMode` carries the prior release's
   public-paths mode forward when the new release doesn't declare one
   (`stable-host-resolver`'s `inheritedDirectPublicEntries`). Kychon's
   prior release used `mode: "explicit"` with many declared paths
   including `.well-known/kychon.json`; the slice's new (minimal) site
   dir didn't carry those exact assets, triggering
   `site.public_paths.inherited./.well-known/kychon.json` missing-asset
   rejections.

   Fix: default `site.public_paths: { mode: "implicit" }` — opts the
   new release out of the explicit-mode carry-forward. Astro's natural
   build shape is filename-URL congruent, so implicit reachability is
   semantically correct. The gateway emits a `PUBLIC_PATH_MODE_WIDENS_TO_IMPLICIT`
   warning (severity: warn, requires_confirmation: true) so the
   transition is auditable. Callers who need explicit per-path control
   pass `cacheClass`, which still produces a fully-declared explicit map.

Verification:
- 243 astro unit tests pass.
- 30 SSR-astro e2e assertions pass.
- End-to-end smoke against api.run402.com on Kychon's actual project
  (`prj_1776162950442_0031`) reached plan.diff with class:'ssr'
  accepted and only expected destructive-removal + mode-widen
  confirmation warnings.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

astro/package.json

@@ -65,7 +65,7 @@
   },
   "peerDependencies": {
     "@run402/functions": "^2.7.0",
-    "@run402/sdk": ">=2.3",
+    "@run402/sdk": ">=2.18.0",
     "astro": ">=5 <7",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"

astro/src/release-slice.test.ts

@@ -247,15 +247,24 @@ describe("buildAstroReleaseSlice — explicit cacheClass option", () => {
     });
   });
 
-  it("does not emit public_paths when cacheClass is not provided", async () => {
+  it("defaults to public_paths { mode: 'implicit' } so the release opts out of inherited explicit paths", async () => {
     const { distDir } = writeFixture(root, {
       routes: [{ pattern: "/about", pathname: "/about", prerender: true, type: "page" }],
     });
     const slice = await buildAstroReleaseSlice(distDir);
+    const publicPaths = (slice.site as { public_paths?: unknown }).public_paths as {
+      mode: string;
+      replace?: unknown;
+    };
+    assert.equal(
+      publicPaths?.mode,
+      "implicit",
+      "default mode must be 'implicit' to avoid carry-forward of prior explicit public_paths",
+    );
     assert.equal(
-      (slice.site as { public_paths?: unknown }).public_paths,
+      publicPaths.replace,
       undefined,
-      "public_paths must remain implicit unless the caller asked for cacheClass overrides",
+      "implicit mode must NOT carry a replace map",
     );
   });
 

astro/src/release-slice.ts

@@ -43,6 +43,13 @@ const ADAPTER_MANIFEST_RELATIVE = path.join("run402", "adapter.json");
 const CLIENT_DIR_RELATIVE = path.join("run402", "client");
 const SERVER_DIR_RELATIVE = path.join("run402", "server");
 const DEFAULT_ENTRYPOINT_REL = "entry.mjs";
+/** Minimum `@run402/sdk` version where `FunctionSpec.class` is in the
+ *  SDK's local strict-fields allowlist (`FUNCTION_SPEC_FIELDS` in
+ *  `sdk/src/namespaces/deploy.ts`). Earlier SDKs reject `class: 'ssr'`
+ *  LOCALLY via `validateKnownFields` before the spec ever reaches the
+ *  gateway — the rejection looks like
+ *  `Unknown ReleaseSpec field: functions.replace.<name>.class`. */
+const MIN_SDK_VERSION_FOR_CLASS_FIELD = "2.18.0";
 
 /**
  * Public-facing error envelope for `@run402/astro/release-slice` failures.
@@ -78,6 +85,95 @@ export class Run402AstroAdapterManifestError extends Error {
   }
 }
 
+/**
+ * Thrown when the installed `@run402/sdk` is older than the version that
+ * accepts `FunctionSpec.class: 'ssr'` in its local validator (≥2.18.0).
+ * The release-slice helper always emits `class: 'ssr'` for the SSR
+ * function — without that field, the gateway's v1.52 auto-fallback
+ * doesn't route unmatched paths to the function, and hybrid mode breaks.
+ * Older SDKs reject the field locally with `Unknown ReleaseSpec field:
+ * functions.replace.<name>.class` before any network call.
+ *
+ * The remedy is always the same: upgrade `@run402/sdk` (and typically
+ * `run402` CLI alongside, since the CLI bundles its own SDK).
+ */
+export class Run402AstroSdkVersionError extends Error {
+  readonly code = "R402_ASTRO_SDK_VERSION_TOO_OLD" as const;
+  readonly installedVersion: string;
+  readonly requiredVersion: string;
+  readonly suggestedFix: string;
+  readonly docs: string;
+
+  constructor(opts: { installedVersion: string; requiredVersion: string }) {
+    super(
+      `@run402/astro/release-slice produces specs with FunctionSpec.class: 'ssr' (gateway ` +
+        `v1.52+ feature). The installed @run402/sdk version (${opts.installedVersion}) ` +
+        `rejects this field locally before the spec reaches the gateway. Required: ` +
+        `>=${opts.requiredVersion}.`,
+    );
+    this.name = "Run402AstroSdkVersionError";
+    this.installedVersion = opts.installedVersion;
+    this.requiredVersion = opts.requiredVersion;
+    this.suggestedFix =
+      "Upgrade with `npm install @run402/sdk@latest run402@latest`. " +
+      "The CLI bundles its own SDK, so both packages need to be on a matching version.";
+    this.docs = "https://docs.run402.com/errors#R402_ASTRO_SDK_VERSION_TOO_OLD";
+  }
+}
+
+/**
+ * Read the installed `@run402/sdk` package.json `version` field. Returns
+ * `null` when the package isn't resolvable from the helper's import
+ * context — e.g. some bundled test runners shim require() and the resolve
+ * fails. A null return falls through to "skip the version check" rather
+ * than throwing, so the helper never blocks on a self-inflicted lookup
+ * failure. The downstream gateway / SDK validator still catches a real
+ * mismatch.
+ */
+function readInstalledSdkVersion(): string | null {
+  try {
+    // Use createRequire to resolve relative to this module. The Vite /
+    // esbuild build of @run402/astro keeps this as a runtime require —
+    // package.json reads aren't statically inlined.
+    const { createRequire } = require("node:module") as typeof import("node:module");
+    const req = createRequire(import.meta.url);
+    const pkg = req("@run402/sdk/package.json") as { version?: unknown };
+    if (pkg && typeof pkg.version === "string") return pkg.version;
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+/** Lowest-common-denominator semver compare. Handles `MAJOR.MINOR.PATCH`
+ *  and ignores pre-release / build suffixes (treats `2.18.0-alpha.1` as
+ *  `2.18.0` — strictly less than `2.18.0` is the correct comparison since
+ *  alphas are pre-releases of the final). Returns negative when a < b,
+ *  positive when a > b, 0 on equal. */
+function compareSemver(a: string, b: string): number {
+  const parse = (v: string) =>
+    v
+      .split("-")[0]!
+      .split(".")
+      .map((n) => Number.parseInt(n, 10) || 0);
+  const [aa, ab, ac] = parse(a);
+  const [ba, bb, bc] = parse(b);
+  if ((aa ?? 0) !== (ba ?? 0)) return (aa ?? 0) - (ba ?? 0);
+  if ((ab ?? 0) !== (bb ?? 0)) return (ab ?? 0) - (bb ?? 0);
+  return (ac ?? 0) - (bc ?? 0);
+}
+
+function assertSdkSupportsClassField(): void {
+  const installed = readInstalledSdkVersion();
+  if (installed === null) return; // lookup failed → defer to runtime
+  if (compareSemver(installed, MIN_SDK_VERSION_FOR_CLASS_FIELD) < 0) {
+    throw new Run402AstroSdkVersionError({
+      installedVersion: installed,
+      requiredVersion: MIN_SDK_VERSION_FOR_CLASS_FIELD,
+    });
+  }
+}
+
 export interface BuildAstroReleaseSliceOptions {
   /** Materialized function name for the SSR Lambda. Defaults to `"ssr"`. */
   functionName?: string;
@@ -232,6 +328,14 @@ export async function buildAstroReleaseSlice(
   distDir: string,
   opts: BuildAstroReleaseSliceOptions = {},
 ): Promise<AstroReleaseSlice> {
+  // Fail fast on stale `@run402/sdk` installs. The helper always emits
+  // `class: 'ssr'` on the SSR function; SDKs older than 2.18.0 reject
+  // that field LOCALLY (in `validateKnownFields`) before the spec ever
+  // reaches the gateway. Detecting this here means consumers see a
+  // precise "upgrade @run402/sdk" message instead of a misleading
+  // "Unknown ReleaseSpec field" error after the deploy script's
+  // boilerplate runs.
+  assertSdkSupportsClassField();
   const manifest = await loadAstroAdapterManifest(distDir);
   const functionName = opts.functionName ?? DEFAULT_FUNCTION_NAME;
   const cacheClass = opts.cacheClass ?? DEFAULT_HTML_CACHE_CLASS;
@@ -242,7 +346,23 @@ export async function buildAstroReleaseSlice(
     path: clientDirAbs,
   };
 
-  const site: SiteSpec = { replace: siteDir };
+  // Default public_paths mode: "implicit" — filename-derived reachability
+  // from the new client dir. Critically, this OPTS OUT of the gateway's
+  // base-release carry-forward semantics: when a prior release used
+  // `mode: "explicit"` with declared paths (e.g., `.well-known/kychon.json`),
+  // the gateway would otherwise inherit those paths into the new release
+  // and reject if the asset isn't present in the new site dir, surfacing
+  // as `site.public_paths.inherited.<path>` missing-asset errors.
+  //
+  // The Astro build's natural shape is filename-URL congruent (`/about` →
+  // `<client>/about/index.html`; assets in `public/` → top-level paths in
+  // the client dir), so implicit mode is semantically correct for an Astro
+  // release. Consumers who need explicit per-path overrides pass `cacheClass`
+  // and the helper switches to `mode: "explicit"` with a fully-declared map.
+  const site: SiteSpec = {
+    replace: siteDir,
+    public_paths: { mode: "implicit" },
+  };
 
   // Bundle the Astro server output into a single ESM source. The
   // gateway's `validateFunctionSpec` rejects multi-file function specs