fix(astro): bump CACHE_SCHEMA_VERSION to 2 so v1.54 AssetRef fields propagate

The build cache at node_modules/.run402/assetMap.json stored AssetRefs
verbatim by source SHA. When the gateway started emitting the v1.54
shape-contract fields (blurhash_data_url + asset_schema), existing
caches kept returning pre-v1.54 AssetRefs on hit — every build with
unchanged source bytes was silently serializing manifests that looked
right (legacy fields populated) but lacked the two new fields.

Reproduced against silver-pines.kychon.com: manifest built 24 min after
the gateway fix shipped + live tests confirmed the fields on
api.run402.com, but the deployed manifest still had both fields missing.
Cache hit path at uploader.ts:404 returned the stale ref; buildManifest
(vite-plugin.ts:392) JSON.stringified it verbatim into the output.

Three coordinated changes plus the discipline note that prevents this
class of bug going forward:

1. astro/src/cache.ts — CACHE_SCHEMA_VERSION 1 → 2. Bumping is
   non-destructive: stale entries are dropped silently and the next
   build re-uploads (or, more commonly, hits the gateway's CAS dedupe
   and re-receives a fresh, fully-populated AssetRef). New file header
   documents the "bump on every AssetRef field add" discipline plus the
   history of why the version was bumped.

2. astro/src/types.ts — AssetRef widened to mirror the current SDK
   shape: v1.50 fields (metadata, image_format, image_info, image_exif,
   image_exif_policy) plus v1.54 fields (blurhash_data_url,
   asset_schema). Plus AssetMetadata + ExifPolicy supporting exports.
   Strictly additive — every existing consumer continues to type-check.
   CacheFile.version literal bumped to 2 in lockstep with cache.ts.

3. astro/src/cache.test.ts — existing version-on-disk assertion bumped
   to 2 with a comment pointing at the bump discipline. Adds two new
   tests: a v1 → v2 schema-migration regression that asserts v1 entries
   are discarded on load (this is the actual bug), and a v1.54-field
   roundtrip guard that catches accidental field stripping in
   flush()/load() (the class of bug v2 prevents) by writing then reading
   an AssetRef carrying blurhash_data_url + asset_schema.

4. astro/CHANGELOG.md — new "Unreleased" section above the existing
   1.0.0-alpha.1 entry documenting the fix + the AssetRef widening +
   the internal cache discipline doc.

223/223 astro unit tests pass; tsc build clean. Reproducer for
downstream consumers: rm -f node_modules/.run402/assetMap.json &&
npm run build, then jq '.assets[<key>] | {blurhash_data_url,
asset_schema}' dist/_assets-manifest.json populates both fields.

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

Author: MajorTal

astro/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `@run402/astro`.
 
+## Unreleased
+
+### Fixed
+
+- **Stale `dist/_assets-manifest.json` entries missing v1.54 AssetRef fields.** The build cache at `node_modules/.run402/assetMap.json` stores AssetRefs verbatim by source SHA; when the gateway started emitting `blurhash_data_url` + `asset_schema` (v1.54), existing caches kept returning pre-v1.54 AssetRefs on hit, silently producing manifests that looked correct (legacy fields populated) but lacked the v1.54 additions. Bumped `CACHE_SCHEMA_VERSION` from `1` to `2` so existing caches invalidate on first run after upgrade. Reproducer: `rm -f node_modules/.run402/assetMap.json && npm run build` then `jq '.assets[<key>] | {blurhash_data_url, asset_schema}' dist/_assets-manifest.json` populates both fields.
+
+### Changed
+
+- **`AssetRef` widened to mirror the current SDK shape.** Adds the v1.50 metadata + EXIF fields (`metadata`, `image_format`, `image_info`, `image_exif`, `image_exif_policy`) and v1.54 shape-contract fields (`blurhash_data_url`, `asset_schema`) the runtime already passed through. Plus the supporting `AssetMetadata` + `ExifPolicy` exports. Strictly additive — pre-existing consumers continue to type-check unchanged, but `as any` casts at field-access sites can now be removed.
+
+### Internal
+
+- New cache.ts header documents the AssetRef-field-add → cache-version-bump discipline that prevents future occurrences of this bug; `cache.test.ts` gains a v1 → v2 migration regression test and a v1.54-field roundtrip guard.
+
 ## 1.0.0-alpha.1 — unreleased
 
 The agent-DX-locked default-export preset (Finding 5 in the design-review consultation). One-line `astro.config.mjs`:

astro/src/cache.test.ts

@@ -62,7 +62,11 @@ describe("BuildCache", () => {
     const expected = join(root, "node_modules", ".run402", "assetMap.json");
     assert.ok(existsSync(expected), "cache file should exist");
     const parsed = JSON.parse(readFileSync(expected, "utf-8"));
-    assert.equal(parsed.version, 1);
+    // Cache schema is currently v2 (v1.50 + v1.54 AssetRef additions).
+    // Bumping CACHE_SCHEMA_VERSION should also bump this assertion AND
+    // add a new "drops a v<previous> cache file" test to the migration
+    // suite below — see cache.ts header for the rationale.
+    assert.equal(parsed.version, 2);
     assert.ok(parsed.entries["/abs/hero.jpg"]);
   });
 
@@ -115,4 +119,63 @@ describe("BuildCache", () => {
     const cache = new BuildCache(root);
     assert.equal(cache.size(), 0);
   });
+
+  // Regression: pre-v2 cache files (written before v1.54 AssetRef shape
+  // added `blurhash_data_url` + `asset_schema`) were silently returned
+  // verbatim on cache hit, dropping the new fields from
+  // `dist/_assets-manifest.json`. Bumping CACHE_SCHEMA_VERSION to 2
+  // invalidates those caches and forces a fresh AssetRef on the next
+  // build. If this test fails after a future schema bump, also bump
+  // CACHE_SCHEMA_VERSION here AND add a new test asserting v2 caches
+  // are dropped at the new version.
+  it("drops a v1 cache file on load (schema migration v1 → v2)", async () => {
+    const cacheDir = join(root, "node_modules", ".run402");
+    const { mkdirSync: mkdir, writeFileSync: writeFile } = await import("node:fs");
+    mkdir(cacheDir, { recursive: true });
+    const v1File = {
+      version: 1,
+      entries: {
+        "/abs/legacy.jpg": {
+          sha256: sampleRef.sha256,
+          assetRef: sampleRef,
+          cachedAt: Date.now() - 86_400_000,
+        },
+      },
+    };
+    writeFile(join(cacheDir, "assetMap.json"), JSON.stringify(v1File), "utf-8");
+    const cache = new BuildCache(root);
+    assert.equal(cache.size(), 0, "v1 entries should be discarded");
+    assert.equal(
+      cache.get("/abs/legacy.jpg", sampleRef.sha256),
+      null,
+      "lookup against the pre-bump entry must miss so the uploader re-fetches a fresh AssetRef",
+    );
+  });
+
+  it("round-trips v1.54 fields (blurhash_data_url + asset_schema) through set/get", () => {
+    const v154Ref: AssetRef = {
+      ...sampleRef,
+      metadata: { tag: "hero" },
+      image_format: "jpeg",
+      image_info: { has_alpha: false, color_space: "srgb" },
+      image_exif: null,
+      image_exif_policy: "strip",
+      blurhash_data_url: "data:image/png;base64,iVBORw0KGgoAAAA",
+      asset_schema: "v1.54",
+    };
+    const cache = new BuildCache(root);
+    cache.set("/abs/hero.jpg", v154Ref.sha256, v154Ref);
+
+    // Same-process read.
+    const same = cache.get("/abs/hero.jpg", v154Ref.sha256);
+    assert.deepEqual(same, v154Ref);
+
+    // Roundtrip via the on-disk file (catches accidental field stripping
+    // in flush()/load(), which is the actual class of bug v2 prevents).
+    const fresh = new BuildCache(root);
+    const reloaded = fresh.get("/abs/hero.jpg", v154Ref.sha256);
+    assert.deepEqual(reloaded, v154Ref);
+    assert.equal(reloaded?.blurhash_data_url, v154Ref.blurhash_data_url);
+    assert.equal(reloaded?.asset_schema, "v1.54");
+  });
 });

astro/src/cache.ts

@@ -10,6 +10,23 @@
  * to match the cached entry. A rename invalidates the OLD path's entry on
  * the next build (when no `<Image>` reference points at it anymore); a content
  * change at the same path invalidates the entry via the sha mismatch.
+ *
+ * **Bumping `CACHE_SCHEMA_VERSION` — required discipline whenever AssetRef
+ * gains a field.** The cache stores AssetRef objects verbatim by source SHA.
+ * If the SDK / gateway starts returning a new field but the cache version
+ * doesn't change, every build with unchanged source bytes is a cache HIT and
+ * the new field never makes it into the cached AssetRef — silently producing
+ * stale manifests that look correct (legacy fields populate) but lack the
+ * additions. This was the v1.54 `blurhash_data_url` / `asset_schema` bug.
+ *
+ * Bump on:
+ *   - any new AssetRef field the gateway can emit (even an optional one)
+ *   - any new derived field the SDK or this package adds at adapt time
+ *   - any change to the `CacheEntry` / `CacheFile` shape
+ *
+ * Bumping is non-destructive: stale entries are dropped silently and the
+ * next build re-uploads (or, more commonly, gets a CAS dedupe at the
+ * gateway and re-receives a fresh, fully-populated AssetRef).
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -18,7 +35,15 @@ import type { AssetRef, CacheEntry, CacheFile } from "./types.js";
 
 const CACHE_DIR_REL = "node_modules/.run402";
 const CACHE_FILE_REL = "node_modules/.run402/assetMap.json";
-const CACHE_SCHEMA_VERSION = 1;
+/**
+ * Bump whenever AssetRef gains a field (see file header for full discipline).
+ * History:
+ *   - 1 — initial v1.49 AssetRef shape.
+ *   - 2 — v1.54 AssetRef additions (`blurhash_data_url`, `asset_schema`)
+ *         plus the v1.50 fields (`metadata`, `image_format`, `image_info`,
+ *         `image_exif`, `image_exif_policy`) the local type now mirrors.
+ */
+const CACHE_SCHEMA_VERSION = 2;
 const GITIGNORE_LINE = "node_modules/.run402/";
 
 export class BuildCache {

astro/src/types.ts

@@ -1,13 +1,18 @@
 /**
  * Shared types for `@run402/astro`.
  *
- * Mirrors the v1.49 AssetRef shape so the package doesn't have to deep-import
+ * Mirrors the current AssetRef shape (v1.49 base + v1.50 metadata/EXIF +
+ * v1.54 shape-contract fields) so the package doesn't have to deep-import
  * SDK internals (the SDK doesn't currently export `AssetRef` from `./node`,
  * only via `./` — but we want to stay self-contained so the package still
  * type-checks if the SDK refactors its public surface).
  *
- * Keep this file in lockstep with the v1.49 `internal.blob_image_variants`
- * shape and `services/asset-slice.ts` `ResolvedAssetRef`.
+ * **Lockstep + cache discipline:** keep this file in lockstep with the
+ * gateway's `services/asset-slice.ts` `ResolvedAssetRef` shape. When you
+ * add a field here, ALSO bump `CACHE_SCHEMA_VERSION` in `./cache.ts` —
+ * the build cache stores AssetRefs verbatim by source SHA, so a forgotten
+ * version bump means stale builds silently drop the new field (see the
+ * cache.ts header for the full story).
  */
 
 /** A single pre-encoded variant entry returned by the gateway. */
@@ -20,7 +25,26 @@ export interface AssetVariant {
   sha256: string;
 }
 
-/** The full v1.49 AssetRef including image-intrinsic fields. */
+/**
+ * The full AssetRef returned by `r.assets.put` and stored verbatim in the
+ * build cache + emitted into `dist/_assets-manifest.json`.
+ *
+ * Field generations:
+ *   - core (v1.45): `key`, `sha256`, `size_bytes`, `content_type`, `url`,
+ *     `cdn_url`, plus `immutable_url`, `cdn_immutable_url`, `etag`, `sri`.
+ *   - v1.49 image-intrinsic: `width_px`, `height_px`, `blurhash`,
+ *     `variant_spec_version`, `display_url`, `display_immutable_url`,
+ *     `variants`.
+ *   - v1.50 metadata + EXIF: `metadata`, `image_format`, `image_info`,
+ *     `image_exif`, `image_exif_policy` — `null` on non-image uploads
+ *     (the wire shape is widen-to-null, not omit), `null` for fields the
+ *     pipeline couldn't compute.
+ *   - v1.54 shape contract: `blurhash_data_url`, `asset_schema` — omitted
+ *     entirely (not `null`) on pre-v1.54 uploads; the omit pattern is what
+ *     `<Run402Image>` strict-mode keys off to skip legacy rows.
+ *
+ * Adding a field here? Bump `CACHE_SCHEMA_VERSION` in `./cache.ts`.
+ */
 export interface AssetRef {
   key: string;
   sha256: string;
@@ -48,8 +72,33 @@ export interface AssetRef {
         display_jpeg?: AssetVariant;
       }
     | undefined;
+
+  // v1.50 metadata + EXIF policy + image intrinsics. Wire shape is
+  // widen-to-null on non-image uploads (NOT omit) — keeps the JSON inventory
+  // wire-shape stable.
+  metadata?: AssetMetadata | null;
+  image_format?: string | null;
+  image_info?: Record<string, unknown> | null;
+  image_exif?: Record<string, unknown> | null;
+  image_exif_policy?: ExifPolicy | null;
+
+  // v1.54 shape-contract fields (omitted entirely — NOT null — on pre-v1.54
+  // uploads). Surfaced so `<Run402Image>` placeholder rendering +
+  // schema-filtered strict-mode work without a DB roundtrip.
+  blurhash_data_url?: string | null;
+  asset_schema?: "v1.49" | "v1.50" | "v1.54" | null;
 }
 
+/** Caller-supplied metadata block. ≤4 KB serialized; leaf values may be
+ *  `string | number | boolean | string[]`. The gateway echoes this back
+ *  verbatim on AssetRef. */
+export type AssetMetadata = Record<string, string | number | boolean | string[]>;
+
+/** EXIF retention policy applied to an image upload. `"strip"` removes
+ *  the EXIF block at upload time; `"preserve"` keeps it; `"redact"` keeps
+ *  the structural keys but blanks GPS / serial-number / lens-info fields. */
+export type ExifPolicy = "strip" | "preserve" | "redact";
+
 /** Options accepted by the `run402()` integration factory. */
 export interface Run402AstroOptions {
   /** Run402 project ID. Defaults to `process.env.RUN402_PROJECT_ID`. */
@@ -173,8 +222,10 @@ export interface CacheEntry {
 
 /** Shape of the on-disk cache file. */
 export interface CacheFile {
-  /** Cache schema version — bump on incompatible AssetRef shape change. */
-  version: 1;
+  /** Cache schema version. Bump in lockstep with `CACHE_SCHEMA_VERSION` in
+   *  `./cache.ts` whenever `AssetRef` gains a field — see that file's header
+   *  for the full discipline. v1 → v2 bump: v1.50 + v1.54 AssetRef fields. */
+  version: 2;
   entries: { [absolutePath: string]: CacheEntry };
 }