feat(sdk): extend AssetRef with blurhash_data_url + asset_schema (v1.54)

MajorTal · claude · MajorTal · commit 1a1a837e0ef5 · 2026-05-24T21:56:43.000+02:00
The v1.54 gateway encoder writes two new fields to internal.blobs and
@run402/functions v2.7.0 surfaces them on AssetRef. The public SDK was
missing them — consumers that rehydrate stored AssetRefs or render the
v1.54 placeholder substrate had to fall back to `any` casts.

Threaded through all four surfaces:
- AssetRef (sdk/src/namespaces/assets.types.ts) — public envelope
- ResolvedAssetRef + AssetManifestEntry (deploy.types.ts) — wire shapes
- UploadCompleteResponse → buildAssetRef (assets.ts) — single-asset put
- ResolvedAssetRef → buildAssetManifestFromPlanEntries (deploy.ts) — apply

Omit-when-undefined throughout so pre-v1.54 gateway envelopes stay
bytewise-identical to before. Matches the v1.49 pattern (not the v1.50
widen-to-null pattern), since these fields are only present when the
v1.54+ encoder ran on an image source.

Build clean, 555/555 unit tests pass, 42/42 doc snippets compile.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/sdk/src/namespaces/assets.ts b/sdk/src/namespaces/assets.ts
@@ -151,6 +151,12 @@ interface UploadCompleteResponse {
   image_info?: Record<string, unknown> | null;
   image_exif?: Record<string, unknown> | null;
   image_exif_policy?: "keep" | "strip" | null;
+  // v1.54+ shape-contract fields. Absent for pre-v1.54 gateways and for
+  // non-image uploads. Threaded through to AssetRef using the omit-when-
+  // undefined pattern so the envelope stays bytewise-identical on older
+  // gateway versions.
+  blurhash_data_url?: string | null;
+  asset_schema?: "v1.49" | "v1.50" | "v1.54" | null;
 }
 
 function escapeHtmlAttr(s: string): string {
@@ -318,6 +324,15 @@ function buildAssetRef(
     image_exif: imageExifField,
     image_exif_policy: imageExifPolicyField,
 
+    // v1.54: shape-contract fields. Omit-when-undefined so pre-v1.54
+    // envelopes stay bytewise-identical (no null injection).
+    ...(resp.blurhash_data_url !== undefined
+      ? { blurhash_data_url: resp.blurhash_data_url }
+      : {}),
+    ...(resp.asset_schema !== undefined
+      ? { asset_schema: resp.asset_schema }
+      : {}),
+
     scriptTag(opts) {
       // Default `defer: true` — modern best practice. Defer prevents
       // render-blocking when placed in <head> and is a no-op when placed
@@ -601,6 +616,13 @@ export class Assets {
       ...(entry.image_exif_policy !== undefined
         ? { image_exif_policy: entry.image_exif_policy }
         : {}),
+      // v1.54 shape-contract pass-through.
+      ...(entry.blurhash_data_url !== undefined
+        ? { blurhash_data_url: entry.blurhash_data_url }
+        : {}),
+      ...(entry.asset_schema !== undefined
+        ? { asset_schema: entry.asset_schema }
+        : {}),
     };
     return buildAssetRef(completion, contentType);
   }
diff --git a/sdk/src/namespaces/assets.types.ts b/sdk/src/namespaces/assets.types.ts
@@ -452,6 +452,26 @@ export interface AssetRef {
   /** Echo of the EXIF policy actually applied to the stored bytes. `null`
    *  for non-image uploads. */
   image_exif_policy: ExifPolicy | null;
+
+  // ---- v1.54+ shape-contract fields ----------------------------------------
+  // Populated atomically at upload time when the v1.54+ gateway encoder runs.
+  // Surfaced on AssetRef so consumers (`<Run402Image>`, agent code that
+  // rehydrates stored AssetRefs) can render placeholders + apply
+  // schema-filtered strict-mode without an extra DB roundtrip.
+
+  /** Pre-decoded PNG data URL (~600-1200 bytes typical at 16×16) computed
+   *  once at upload time from the canonical pinned BlurHash decoder.
+   *  `<Run402Image>` emits this as the placeholder `background-image` so
+   *  render is pure-local (no SSR-time decode). `null` when the decoder
+   *  failed on otherwise-valid input (rare). Omitted for non-image and
+   *  pre-v1.54 uploads. */
+  blurhash_data_url?: string | null;
+  /** Semver shape-contract stamp recording the highest contract this row's
+   *  fields satisfy. `null` for partial-shape rows (e.g., HEIC sources
+   *  missing `display_jpeg`). Read by `<Run402Image>` strict mode
+   *  (`imageDefaults.strict: { onSchema: ">=v1.49" }`) to skip legacy rows.
+   *  Omitted for pre-v1.54 uploads. */
+  asset_schema?: "v1.49" | "v1.50" | "v1.54" | null;
 }
 
 /**
diff --git a/sdk/src/namespaces/deploy.ts b/sdk/src/namespaces/deploy.ts
@@ -3204,6 +3204,10 @@ function buildAssetManifestFromPlanEntries(
     if (ref.image_info !== undefined) e.image_info = ref.image_info;
     if (ref.image_exif !== undefined) e.image_exif = ref.image_exif;
     if (ref.image_exif_policy !== undefined) e.image_exif_policy = ref.image_exif_policy;
+    // v1.54 pass-through: shape-contract fields. Pre-v1.54 plan responses
+    // omit them; the manifest entry stays bytewise-identical to before.
+    if (ref.blurhash_data_url !== undefined) e.blurhash_data_url = ref.blurhash_data_url;
+    if (ref.asset_schema !== undefined) e.asset_schema = ref.asset_schema;
     list.push(e);
     byKey[entry.key] = e;
     manifest[entry.key] = e;
diff --git a/sdk/src/namespaces/deploy.types.ts b/sdk/src/namespaces/deploy.types.ts
@@ -1528,6 +1528,11 @@ export interface ResolvedAssetRef {
   image_info?: Record<string, unknown> | null;
   image_exif?: Record<string, unknown> | null;
   image_exif_policy?: "keep" | "strip" | null;
+
+  // v1.54+ shape-contract fields. Populated atomically at upload time when
+  // the gateway encoder runs; absent on pre-v1.54 plan responses.
+  blurhash_data_url?: string | null;
+  asset_schema?: "v1.49" | "v1.50" | "v1.54" | null;
 }
 
 export interface AssetSyncPlanBlock {
@@ -2309,6 +2314,11 @@ export interface AssetManifestEntry {
   image_info?: Record<string, unknown> | null;
   image_exif?: Record<string, unknown> | null;
   image_exif_policy?: "keep" | "strip" | null;
+
+  // v1.54+ shape-contract fields, threaded from `ResolvedAssetRef`. Absent
+  // on pre-v1.54 plan responses.
+  blurhash_data_url?: string | null;
+  asset_schema?: "v1.49" | "v1.50" | "v1.54" | null;
 }
 
 // ─── Apply / start / low-level options ───────────────────────────────────────
