@tokenoftrust/storefront-runner 3.3.4 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.3.4",
+  "version": "3.4.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/scripts/generate-managed-analytics-api-v1-schemas.mjs

@@ -1,13 +1,92 @@
+// Renders packages/public-runtime/schemas/managed-analytics/v1/*.schema.json from
+// MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS. The output is a declared derived mirror
+// (.tot/derived-mirror-steps.json), re-derived on the umbrella tip.
+//
+//   (no flag)  write every schema file
+//   --check    refuse a stale, missing or orphaned file. Inside a fold gate (TOT_FOLD_GATE=1) a
+//              stale or missing file passes with a STALE line, since the tip re-derives it; an
+//              orphan still refuses, because no derivation deletes a file.
+import { readdirSync, readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-import { MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS } from "../src/integration/managed-analytics-api-v1.schemas.ts";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
-const output = resolve(here, "../schemas/managed-analytics/v1");
-await mkdir(output, { recursive: true });
+const repoRoot = resolve(here, "../../..");
+export const OUTPUT_DIR = relative(repoRoot, resolve(here, "../schemas/managed-analytics/v1"));
 
-for (const schema of Object.values(MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS)) {
-  const name = new URL(schema.$id).pathname.split("/").at(-1);
-  await writeFile(resolve(output, name), `${JSON.stringify(schema, null, 2)}\n`, "utf8");
+/**
+ * Every schema file, as repo-relative path -> text.
+ * @returns {Promise<Map<string, string>>}
+ */
+export async function renderManagedAnalyticsSchemas() {
+  const { MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS } = await import("../src/integration/managed-analytics-api-v1.schemas.ts");
+  const files = new Map();
+  for (const schema of Object.values(MANAGED_ANALYTICS_API_V1_JSON_SCHEMAS)) {
+    const name = new URL(schema.$id).pathname.split("/").at(-1);
+    files.set(`${OUTPUT_DIR}/${name}`, `${JSON.stringify(schema, null, 2)}\n`);
+  }
+  return files;
+}
+
+/**
+ * The committed files under `root` against a fresh render: `stale` differ or are missing, `orphans`
+ * sit in the output directory with no schema rendering them.
+ * @param {string} [root]
+ */
+export async function findSchemaDrift(root = repoRoot) {
+  const files = await renderManagedAnalyticsSchemas();
+  /** @param {string} path */
+  const committed = (path) => {
+    try {
+      return readFileSync(resolve(root, path), "utf8");
+    } catch {
+      return null;
+    }
+  };
+  let present = [];
+  try {
+    present = readdirSync(resolve(root, OUTPUT_DIR));
+  } catch {
+    present = [];
+  }
+  return {
+    files,
+    stale: [...files].filter(([path, text]) => committed(path) !== text).map(([path]) => path),
+    orphans: present.map((name) => `${OUTPUT_DIR}/${name}`).filter((path) => !files.has(path)),
+  };
+}
+
+/**
+ * The `--check` verdict. A fold gate tolerates stale files, which the tip re-derives; an orphan is
+ * always red, since no derivation deletes a file.
+ * @param {{ count: number, stale: string[], orphans: string[], foldGate: boolean }} drift
+ * @returns {{ ok: boolean, lines: string[] }}
+ */
+export function schemaCheckVerdict({ count, stale, orphans, foldGate }) {
+  const lines = [
+    ...orphans.map((path) => `managed-analytics-schemas-orphan: ${path} is not rendered by any schema; delete it`),
+    ...stale.map((path) => `${foldGate ? "STALE" : "managed-analytics-schemas-stale"}: ${path}`),
+  ];
+  const ok = orphans.length === 0 && (stale.length === 0 || foldGate);
+  if (!ok && stale.length > 0) lines.push(`re-derive: node ${relative(repoRoot, fileURLToPath(import.meta.url))}`);
+  if (ok) lines.push(`${count} managed analytics v1 schemas are ${stale.length > 0 ? "stale; the tip re-derives them" : "current"}`);
+  return { ok, lines };
+}
+
+async function check() {
+  const { files, stale, orphans } = await findSchemaDrift();
+  const verdict = schemaCheckVerdict({ count: files.size, stale, orphans, foldGate: process.env.TOT_FOLD_GATE === "1" });
+  for (const line of verdict.lines) (verdict.ok ? console.log : console.error)(line);
+  if (!verdict.ok) process.exitCode = 1;
+}
+
+async function write() {
+  const files = await renderManagedAnalyticsSchemas();
+  await mkdir(resolve(repoRoot, OUTPUT_DIR), { recursive: true });
+  for (const [path, text] of files) await writeFile(resolve(repoRoot, path), text, "utf8");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  await (process.argv.includes("--check") ? check() : write());
 }

package/packages/public-runtime/src/asset-registry.ts

@@ -34,10 +34,17 @@ export interface AssetProvenance {
   at: string;
 }
 
+/**
+ * How a derived pool object was made from its `parent` entry. A rendition's identity is its parent's
+ * address plus this recipe; the bytes it produces get their own address, so a changed recipe or
+ * encoder mints new renditions and never rewrites a URL already served.
+ */
+export interface VariantRecipe { kind: "variant"; parent: string; width: number; format: string; quality: number; encoder: string }
+
 export type AssetRecipe =
   | { kind: "original" }
   | { kind: "sanitized"; sanitizer: string; source: string }
-  | { kind: "variant"; parent: string; width: number; format: string; encoder: string };
+  | VariantRecipe;
 
 export type RetentionClass = "release" | "durable" | "external-use" | "removal-requested";
 export interface RetentionTransition {
@@ -55,6 +62,9 @@ export interface AssetRecord {
   address: string;
   mediaType?: string;
   size?: number;
+  /** Intrinsic pixel dimensions of an image, as decoded (orientation applied). */
+  width?: number;
+  height?: number;
   provenance?: AssetProvenance;
   /** Tenants authorized to reference this address: each one proved it holds the bytes. */
   tenants?: string[];
@@ -79,6 +89,8 @@ export interface AssetWrite {
   entry: string;
   mediaType?: string;
   size?: number;
+  width?: number;
+  height?: number;
   provenance?: AssetProvenance;
   tenant?: string;
   owner?: string;
@@ -103,6 +115,11 @@ const MAX_TENANTS = 256;
 const MAX_RENDITIONS = 64;
 const MAX_TRANSITIONS = 32;
 const MAX_LOCATOR = 2048;
+const MAX_DIMENSION = 65535;
+
+function validDimension(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) > 0 && (value as number) <= MAX_DIMENSION;
+}
 
 /**
  * The retention transitions an owner or a designation may make. A record with no retention facet is
@@ -176,8 +193,10 @@ function normalizeRecipe(raw: unknown): AssetRecipe | null {
   if (raw.kind === "variant" && typeof raw.parent === "string" && entryAddress(raw.parent) !== null &&
       Number.isSafeInteger(raw.width) && (raw.width as number) > 0 && (raw.width as number) <= 16384 &&
       typeof raw.format === "string" && TOKEN_RE.test(raw.format) &&
+      Number.isSafeInteger(raw.quality) && (raw.quality as number) >= 1 && (raw.quality as number) <= 100 &&
       typeof raw.encoder === "string" && TOKEN_RE.test(raw.encoder)) {
-    return { kind: "variant", parent: raw.parent, width: raw.width as number, format: raw.format, encoder: raw.encoder };
+    return { kind: "variant", parent: raw.parent, width: raw.width as number, format: raw.format,
+      quality: raw.quality as number, encoder: raw.encoder };
   }
   return null;
 }
@@ -227,6 +246,11 @@ export function normalizeAssetRecord(entry: string, raw: unknown): AssetRecord |
   const record: AssetRecord = { address };
   if (typeof raw.mediaType === "string" && MEDIA_TYPE_RE.test(raw.mediaType)) record.mediaType = raw.mediaType;
   if (Number.isSafeInteger(raw.size) && (raw.size as number) > 0) record.size = raw.size as number;
+  // Dimensions are one fact: both or neither.
+  if (validDimension(raw.width) && validDimension(raw.height)) {
+    record.width = raw.width;
+    record.height = raw.height;
+  }
   const provenance = normalizeProvenance(raw.provenance);
   if (provenance) record.provenance = provenance;
   if (Array.isArray(raw.tenants)) {
@@ -294,6 +318,10 @@ export function applyAssetWrite(existing: AssetRecord | undefined, write: AssetW
   const record: AssetRecord = existing ? structuredCloneRecord(existing) : { address };
   if (record.mediaType === undefined && write.mediaType !== undefined && MEDIA_TYPE_RE.test(write.mediaType)) record.mediaType = write.mediaType;
   if (record.size === undefined && Number.isSafeInteger(write.size) && (write.size as number) > 0) record.size = write.size as number;
+  if (record.width === undefined && validDimension(write.width) && validDimension(write.height)) {
+    record.width = write.width;
+    record.height = write.height;
+  }
   if (record.provenance === undefined && write.provenance) {
     const provenance = normalizeProvenance(write.provenance);
     if (provenance) record.provenance = provenance;
@@ -386,6 +414,34 @@ export function authorizeAssetReference(
   };
 }
 
+export interface RegisteredRendition { entry: string; size: number }
+
+/**
+ * The registered rendition of `recipe.parent` made by exactly `recipe`, or null. It counts only when
+ * the parent lists it among its renditions, its record's recipe has the same width, format, quality
+ * and encoder, it is registered to `tenantId`, and the store holds a byte verification of it (so it
+ * is in the pool). A recipe or encoder that differs in any field finds nothing: it mints its own
+ * renditions. The record's own `parent` is not compared: two sources with the same pixels share
+ * rendition bytes, the record keeps its first writer's parent, and each parent's link is the proof
+ * that a build made it from that parent.
+ */
+export function registeredRendition(
+  registry: AssetRegistry | null | undefined, tenantId: string, recipe: VariantRecipe,
+): RegisteredRendition | null {
+  const wanted = normalizeRecipe(recipe);
+  if (!registry || !wanted || wanted.kind !== "variant") return null;
+  for (const entry of registry.assets[wanted.parent]?.renditions ?? []) {
+    const record = registry.assets[entry];
+    const made = record?.recipe;
+    if (!record?.verified || !record.tenants?.includes(tenantId) || made?.kind !== "variant") continue;
+    if (made.width === wanted.width && made.format === wanted.format &&
+        made.quality === wanted.quality && made.encoder === wanted.encoder) {
+      return { entry, size: record.verified.size };
+    }
+  }
+  return null;
+}
+
 /**
  * The tenants a record lists other than `tenantId`, without naming them: true when the address is
  * registered and this tenant is not among its tenants. Capture uses it to refuse a reference to