@unoverse-platform/studio 0.1.89 → 0.1.91

package/vendor/base/src/executor.ts

@@ -0,0 +1,284 @@
+/**
+ * Node Execution - Handles executing nodes (PromiseNode, CallbackNode, ServiceCall)
+ */
+
+import type { NodeDefinition } from "./types.js";
+import { getNode } from "./registry.js";
+import { buildExecutionContext } from "./platform/index.js";
+
+/**
+ * Create a logger for a node type - outputs structured JSON for Loki/Promtail
+ */
+function createLogger(nodeType: string) {
+  const log = (level: string, ...args: any[]) => {
+    const msg = args.map((a) => (typeof a === "object" ? JSON.stringify(a) : String(a))).join(" ");
+    console.log(JSON.stringify({ level, nodeType, msg, service: "node-service" }));
+  };
+  return {
+    info: (...args: any[]) => log("info", ...args),
+    error: (...args: any[]) => log("error", ...args),
+    debug: (...args: any[]) => log("debug", ...args),
+    warn: (...args: any[]) => log("warn", ...args),
+  };
+}
+
+/**
+ * Execute a PromiseNode (single execution, returns result)
+ */
+async function executePromiseNode(nodeDef: NodeDefinition, inputs: any, config: any, context: any) {
+  const ExecutorClass = nodeDef.executor.executor || nodeDef.executor;
+  const executor = new ExecutorClass(nodeDef.type);
+
+  // Inject logger into executor (base classes expect this.logger)
+  executor.logger = createLogger(nodeDef.type);
+
+  // Ensure base class methods are available (some executors call this.validateAndGetContext)
+  if (!executor.validateAndGetContext) {
+    executor.validateAndGetContext = (ctx: any) => ({
+      workflowId: ctx?.workflowId || ctx?.workflow?.id || "",
+      executionId: ctx?.executionId || ctx?.workflow?.runId || "",
+      nodeId: ctx?.nodeId || "",
+    });
+  }
+
+  if (!executor.execute || typeof executor.execute !== "function") {
+    throw new Error(`Node ${nodeDef.type} executor does not have an execute method`);
+  }
+
+  const executionContext = buildExecutionContext(nodeDef.type, inputs, config, context);
+  return await executor.execute(inputs, config, executionContext);
+}
+
+/**
+ * Execute a CallbackNode (generator, emits multiple outputs)
+ * Returns an async generator that yields outputs
+ */
+export async function* executeCallbackNode(nodeDef: NodeDefinition, inputs: any, config: any, context: any) {
+  const ExecutorClass = nodeDef.executor.executor || nodeDef.executor;
+  const executor = new ExecutorClass(nodeDef.type);
+
+  // Inject logger into executor (base classes expect this.logger)
+  executor.logger = createLogger(nodeDef.type);
+
+  // Ensure base class methods are available (some executors call this.validateAndGetContext)
+  if (!executor.validateAndGetContext) {
+    executor.validateAndGetContext = (ctx: any) => ({
+      workflowId: ctx?.workflowId || ctx?.workflow?.id || "",
+      executionId: ctx?.executionId || ctx?.workflow?.runId || "",
+      nodeId: ctx?.nodeId || "",
+    });
+  }
+
+  if (!executor.initializeState || !executor.handleEvent) {
+    // A PromiseNode on the stream path: design-system nodes ride the callback-actor
+    // lifecycle (template uiComponent) but their universal executor is a PromiseNode
+    // that outputs at the end (UNOVERSE_NODE_RUNTIME.md). One output, then done.
+    if (typeof (executor as any).execute === "function") {
+      yield await executePromiseNode(nodeDef, inputs, config, context);
+      return;
+    }
+    throw new Error(`Node ${nodeDef.type} is a CallbackNode but missing initializeState or handleEvent`);
+  }
+
+  const executionContext = buildExecutionContext(nodeDef.type, inputs, config, context);
+
+  // Set executionContext on executor for nodes that need it (e.g., OpenAIStream)
+  executor.executionContext = executionContext;
+
+  // Initialize state
+  let state = executor.initializeState(inputs);
+
+  // Queue-based streaming: emit() pushes to queue, generator yields from queue
+  const outputQueue: any[] = [];
+  const state_: { resolver: ((v: { value: any; done: boolean }) => void) | null; done: boolean } = {
+    resolver: null,
+    done: false,
+  };
+
+  // emit() either resolves a waiting consumer or queues the output
+  let emitCount = 0;
+  const emit = (output: any) => {
+    emitCount++;
+    if (state_.resolver) {
+      const resolve = state_.resolver;
+      state_.resolver = null;
+      resolve({ value: output, done: false });
+    } else {
+      outputQueue.push(output);
+    }
+  };
+
+  // Run execution in background - don't await it
+  const executionPromise = (async () => {
+    try {
+      // Pass executionContext as 4th parameter for nodes that need it (e.g., AWSNovaSpeech)
+      state = await executor.handleEvent({ type: "EXECUTE", inputs, config }, state, emit, executionContext);
+
+      // Only auto-continue if node is NOT yielding for user input (focusInputRequired).
+      // Guard against a node that never completes and makes no progress: a signal-driven
+      // node (e.g. Loop) run standalone takes "no action" on CONTINUE and never sets
+      // isComplete, which would spin forever and flood logs. Break after repeated
+      // no-progress iterations (no new emit AND unchanged state), plus a hard backstop.
+      const stateSig = (s: any) => {
+        try {
+          return JSON.stringify(s ?? null);
+        } catch {
+          return String(emitCount); // uncomparable state → fall back to emit progress
+        }
+      };
+      // The signature is consulted ONLY when emits have stalled: stringifying the full
+      // node state per iteration is O(state size) per chunk — O(n²) over a long stream
+      // for a state-accumulating node (message history, streamed text). Emit progress
+      // alone proves progress on the common path, so skip the stringify entirely there.
+      let prevSig: string | null = null;
+      let prevEmit = emitCount;
+      let stalls = 0;
+      let total = 0;
+      while (!state.isComplete && !state.focusInputRequired) {
+        if (++total > 100000) break; // hard backstop
+        state = await executor.handleEvent(
+          { type: "CONTINUE", inputs: { continue: true }, config },
+          state,
+          emit,
+          executionContext,
+        );
+        if (emitCount !== prevEmit) {
+          stalls = 0;
+          prevSig = null; // stale — recompute only if emits stall again
+        } else {
+          const sig = stateSig(state);
+          if (prevSig !== null && sig !== prevSig) {
+            stalls = 0;
+          } else if (prevSig !== null && ++stalls >= 3) {
+            // No new emit and unchanged state across a few CONTINUEs → the node is
+            // signal-driven (e.g. Loop) and won't advance standalone. Stop quietly.
+            break;
+          }
+          prevSig = sig;
+        }
+        prevEmit = emitCount;
+      }
+    } finally {
+      state_.done = true;
+      // Signal completion to any waiting consumer
+      if (state_.resolver) {
+        const resolve = state_.resolver;
+        state_.resolver = null;
+        resolve({ value: undefined, done: true });
+      }
+    }
+  })();
+
+  // Yield outputs as they arrive
+  try {
+    while (true) {
+      // First drain the queue
+      if (outputQueue.length > 0) {
+        yield outputQueue.shift();
+        continue;
+      }
+
+      // If execution is done, drain any remaining queue items before finishing
+      if (state_.done) {
+        // CRITICAL: Yield any remaining queued outputs before exiting
+        // This ensures the final emit() is always sent to the client
+        while (outputQueue.length > 0) {
+          yield outputQueue.shift();
+        }
+        break;
+      }
+
+      // Wait for next output or completion
+      const result = await new Promise<{ value: any; done: boolean }>((resolve) => {
+        state_.resolver = resolve;
+      });
+
+      if (result.done) {
+        break;
+      }
+
+      yield result.value;
+    }
+  } finally {
+    // Ensure execution completes even if generator is abandoned
+    await executionPromise;
+  }
+}
+
+/**
+ * Execute a service call on a node (calls handleServiceCall method)
+ * Used for service nodes like OpenAIEmbeddingService, BedrockEmbeddingService
+ */
+export async function executeServiceCall(
+  nodeType: string,
+  method: string,
+  params: any,
+  config: any,
+  context: any,
+): Promise<any> {
+  const nodeDef = getNode(nodeType);
+
+  if (!nodeDef) {
+    throw new Error(`Node type not found: ${nodeType}`);
+  }
+
+  if (!nodeDef.executor) {
+    throw new Error(`No executor found for node type: ${nodeType}`);
+  }
+
+  const ExecutorClass = nodeDef.executor.executor || nodeDef.executor;
+  /**
+   * WITH THE NODE TYPE, like the two other construction sites in this file.
+   *
+   * A code node's executor hardcodes its own type in its constructor, so `new ExecutorClass()`
+   * worked for every one of them and the missing argument sat here unnoticed. The two SHARED
+   * manifest classes cannot: one class serves every manifest node, so the type IS the
+   * argument, and without it `this.nodeType` is undefined and the lookup fails with
+   * `No manifest loaded for node type "undefined"`.
+   *
+   * It broke the SERVICE channel only, which is why it survived the whole migration: every
+   * manifest node so far is reached by the graph (executePromiseNode / executeCallbackNode
+   * above, both of which pass it). SpatialSearch is the first manifest node that is ONLY ever
+   * called as a service, so it is the first to hit this line.
+   */
+  const executor = new ExecutorClass(nodeDef.type);
+
+  // Inject logger into executor (base classes expect this.logger)
+  executor.logger = createLogger(nodeType);
+
+  if (!executor.handleServiceCall || typeof executor.handleServiceCall !== "function") {
+    throw new Error(`Node ${nodeType} executor does not have a handleServiceCall method`);
+  }
+
+  const executionContext = buildExecutionContext(nodeType, {}, config, context);
+  return await executor.handleServiceCall(method, params, config, executionContext);
+}
+
+/**
+ * Execute a node (dispatches to correct executor based on type)
+ */
+export async function executeNode(nodeType: string, inputs: any, config: any, context: any) {
+  const nodeDef = getNode(nodeType);
+
+  if (!nodeDef) {
+    throw new Error(`Node type not found: ${nodeType}`);
+  }
+
+  if (!nodeDef.executor) {
+    throw new Error(`No executor found for node type: ${nodeType}`);
+  }
+
+  // PromiseNode - single execution
+  if (nodeDef.executionMode === "single") {
+    return await executePromiseNode(nodeDef, inputs, config, context);
+  }
+
+  // CallbackNode - collect all outputs and return final result
+  const outputs: any[] = [];
+  for await (const output of executeCallbackNode(nodeDef, inputs, config, context)) {
+    outputs.push(output);
+  }
+
+  // Return the last output (final result)
+  return outputs[outputs.length - 1] || {};
+}

package/vendor/base/src/http/uwsFetchAdapter.ts

@@ -0,0 +1,260 @@
+/**
+ * uWS ↔ Web-Fetch adapter — the ONLY bespoke transport code.
+ *
+ * The MCP SDK's transport is framework-agnostic: `WebStandardStreamableHTTPServerTransport`
+ * exposes `handleRequest(req: Request) => Promise<Response>` — the exact entry the SDK
+ * documents for Hono / Cloudflare Workers / Deno / Bun. So we do NOT hand-roll the MCP
+ * protocol: this adapter just converts a uWS request into a Web `Request`, and writes the
+ * Web `Response` (single-shot JSON, or a long-lived SSE stream) back onto the uWS
+ * `HttpResponse`. All MCP protocol logic stays inside the SDK transport.
+ *
+ * uWS rules honored here (these are the easy things to get wrong):
+ *  - `HttpRequest` is valid only synchronously → method/url/headers are read up-front.
+ *  - `onAborted` MUST be registered before the first `await`, or uWS throws on disconnect.
+ *  - every write happens inside `res.cork()`.
+ *  - body chunks are copied synchronously (uWS reuses the chunk's backing memory).
+ */
+import { gzipSync } from "node:zlib";
+import type { HttpRequest, HttpResponse } from "uWebSockets.js";
+
+const STATUS_TEXT: Record<number, string> = {
+  200: "OK",
+  202: "Accepted",
+  204: "No Content",
+  304: "Not Modified",
+  400: "Bad Request",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  500: "Internal Server Error",
+};
+const statusLine = (code: number): string => `${code} ${STATUS_TEXT[code] ?? "OK"}`;
+
+/** Text-ish payloads compress ~4:1; anything else (images, audio) is already packed. */
+const COMPRESSIBLE = /^(text\/|application\/(json|javascript|xml|vnd\.unoverse))/;
+/** Below this, the gzip header + CPU outweigh the shrink. */
+const COMPRESS_MIN_BYTES = 1024;
+
+function writeCors(res: HttpResponse): void {
+  // The workbench is same-origin (via the Vite proxy) so needs none of this; kept so
+  // external MCP clients / the Inspector / the canvas can connect cross-origin.
+  res.writeHeader("Access-Control-Allow-Origin", "*");
+  res.writeHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
+  // `ngrok-skip-browser-warning` (2026-08-28): the webSDK sends it on ngrok-hosted dev
+  // tunnels to bypass the free tier's interstitial; a custom header makes the browser
+  // PREFLIGHT, and a preflight that doesn't allow it fails the whole request ("blocked
+  // by CORS: header field not allowed") — observed live inside ChatGPT's widget sandbox.
+  // Harmless to allow always: it's only ever SENT to ngrok hosts.
+  res.writeHeader(
+    "Access-Control-Allow-Headers",
+    "Content-Type, Authorization, mcp-session-id, mcp-protocol-version, ngrok-skip-browser-warning",
+  );
+  res.writeHeader("Access-Control-Expose-Headers", "mcp-session-id, mcp-protocol-version");
+  // A PREFLIGHT IS A ROUND TRIP THAT CARRIES NO DATA, AND WITHOUT THIS THE BROWSER REPEATS
+  // IT CONSTANTLY. Chrome's default preflight cache is 5 seconds, so an app making a series
+  // of MCP calls pays OPTIONS → 204 → the real request, doubling the round trips on nearly
+  // every one. On a universe served from one region that is the dominant cost of loading an
+  // app: measured London → UAE, a round trip is ~150ms and the server's own processing is
+  // ~0ms, so the preflights were most of the wait, not the work.
+  //
+  // 24h is the practical ceiling (Chromium caps at 2h, Firefox at 24h; both clamp rather
+  // than ignore). The response being cached says only which methods and headers are allowed,
+  // which is static in this file — no authorization decision is cached, because auth is
+  // checked on the real request every time.
+  res.writeHeader("Access-Control-Max-Age", "86400");
+}
+
+/** Buffer the full request body; resolves on the last chunk (copies as it goes). */
+function readBody(res: HttpResponse): Promise<Buffer> {
+  return new Promise((resolve) => {
+    // Collect copies and concat ONCE at the end. The old per-chunk
+    // `Buffer.concat([buf, chunk])` reallocated+copied the whole accumulator on every
+    // chunk — O(n²) in body size, which hurts large /execute payloads. Each chunk is
+    // still copied synchronously (uWS reuses the chunk's backing memory after return).
+    const chunks: Buffer[] = [];
+    res.onData((chunk, isLast) => {
+      // COPY each chunk synchronously NOW — uWS detaches/reuses the chunk's backing
+      // ArrayBuffer after this callback returns. `Buffer.from(arrayBuffer)` is only a
+      // VIEW (no copy), so wrap in a Uint8Array, which Buffer.from then copies; deferring
+      // a bare view to the final concat would read detached memory.
+      chunks.push(Buffer.from(new Uint8Array(chunk)));
+      if (isLast) resolve(chunks.length === 1 ? chunks[0] : Buffer.concat(chunks));
+    });
+  });
+}
+
+/**
+ * Drive a uWS request through a Web-fetch handler: OPTIONS preflight, body buffering,
+ * and pumping the Response (single-shot JSON or long-lived SSE) back to uWS.
+ */
+export async function handleFetch(
+  res: HttpResponse,
+  req: HttpRequest,
+  handler: (request: Request) => Promise<Response>,
+): Promise<void> {
+  const state: { aborted: boolean; reader?: ReadableStreamDefaultReader<Uint8Array> } = { aborted: false };
+  res.onAborted(() => {
+    state.aborted = true;
+    void state.reader?.cancel().catch(() => {});
+  });
+
+  // HttpRequest is only valid synchronously — capture everything now.
+  const method = req.getMethod().toUpperCase();
+  const query = req.getQuery();
+  const url = `http://localhost${req.getUrl()}${query ? `?${query}` : ""}`;
+  const headers: Record<string, string> = {};
+  req.forEach((k, v) => {
+    headers[k] = v;
+  });
+
+  if (method === "OPTIONS") {
+    res.cork(() => {
+      res.writeStatus(statusLine(204));
+      writeCors(res);
+      res.endWithoutBody();
+    });
+    return;
+  }
+
+  const body = method !== "GET" && method !== "HEAD" ? await readBody(res) : undefined;
+  if (state.aborted) return;
+
+  let response: Response;
+  try {
+    const init: RequestInit = { method, headers };
+    if (body && body.length) init.body = new Uint8Array(body); // BodyInit-compatible copy of the Buffer
+    response = await handler(new Request(url, init));
+  } catch (err) {
+    // Log the detail server-side; return a GENERIC message to the client (no internal
+    // detail leakage — MCP security best-practices).
+    console.error("[unoverse] request handler error:", err);
+    if (!state.aborted) {
+      res.cork(() => {
+        res.writeStatus(statusLine(500));
+        res.writeHeader("Content-Type", "application/json");
+        writeCors(res);
+        res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null }));
+      });
+    }
+    return;
+  }
+  if (state.aborted) return;
+
+  const isSse = (response.headers.get("content-type") ?? "").startsWith("text/event-stream");
+
+  // Single-shot responses (everything except SSE) are buffered so large text payloads
+  // can be gzipped. Neither uWS nor the DO load balancer compresses, so without this
+  // every byte travels identity-encoded — the widget boot alone was ~660KB of JS/JSON
+  // that gzips to ~150KB. SSE must stream, so it is never buffered or compressed.
+  if (!isSse) {
+    const contentType = response.headers.get("content-type") ?? "";
+    const acceptsGzip = /(^|,)\s*gzip\s*(;|,|$)/.test(headers["accept-encoding"] ?? "");
+    let payload: Buffer | null = null;
+    try {
+      payload = Buffer.from(await response.arrayBuffer());
+    } catch {
+      payload = null; // body unreadable — fall through and end empty below
+    }
+    if (state.aborted) return;
+    const shouldCompress =
+      acceptsGzip &&
+      payload !== null &&
+      payload.length >= COMPRESS_MIN_BYTES &&
+      COMPRESSIBLE.test(contentType) &&
+      !response.headers.get("content-encoding");
+    const body = shouldCompress && payload ? gzipSync(payload) : payload;
+    res.cork(() => {
+      res.writeStatus(statusLine(response.status));
+      response.headers.forEach((value, key) => {
+        const k = key.toLowerCase();
+        // uWS generates these itself on every response. Forwarding an upstream copy
+        // (e.g. the engine's own `date`) yields a DUPLICATE header — nginx just warns
+        // and serves 200, but HTTP/3 (QUIC) rejects the malformed header block with
+        // QUIC_PACKET_READ_ERROR. Skip them so uWS's single copy is authoritative.
+        // access-control-*: writeCors() below is authoritative — forwarding an upstream
+        // copy too produced the doubled `access-control-allow-origin: *,*` seen live.
+        if (k === "content-length" || k === "date" || k === "server" || k.startsWith("access-control-")) return;
+        res.writeHeader(key, value);
+      });
+      if (shouldCompress) {
+        res.writeHeader("Content-Encoding", "gzip");
+        // Encoding varies by the request's Accept-Encoding, so shared caches must key on it.
+        res.writeHeader("Vary", "Accept-Encoding");
+      }
+      writeCors(res);
+      // `res.end()` for the empty case, NEVER `endWithoutBody()`. On HTTP/1.1 with no
+      // Content-Length, endWithoutBody() leaves the response unterminated: the client
+      // waits on a reply that never finishes until the socket's idle timeout kills the
+      // connection ~12s later. Every bodyless response paid it — the MCP handshake's
+      // 202 ack among them, so every app open stalled ~10s before its first paint
+      // (observed live on bppunoverse 2026-08-21; reproduced in isolation: a JSON
+      // response 28ms, a null-body 202 11.9s). end() closes with content-length: 0.
+      if (body && body.length) res.end(body);
+      else res.end();
+    });
+    return;
+  }
+
+  // SSE: write head, then pump chunks until the transport closes the stream.
+  const reader = response.body?.getReader();
+  state.reader = reader;
+  res.cork(() => {
+    res.writeStatus(statusLine(response.status));
+    response.headers.forEach((value, key) => {
+      const k = key.toLowerCase();
+      // See the single-shot branch for why these are skipped.
+      if (k === "content-length" || k === "date" || k === "server" || k.startsWith("access-control-")) return;
+      res.writeHeader(key, value);
+    });
+    writeCors(res);
+  });
+
+  if (!reader) {
+    if (!state.aborted) res.cork(() => res.end());
+    return;
+  }
+
+  // SSE pump lifecycle. A GET stream that dies leaves its session registered while
+  // every push silently drops (the SDK sends nothing to a missing standalone stream),
+  // so these logs are the ground truth for whether a client's inbound stream exists.
+  const path = new URL(url).pathname;
+  // Session id ties a pump to its MCP session (request header on established sessions,
+  // response header on initialize).
+  const sid = headers["mcp-session-id"] ?? response.headers.get("mcp-session-id") ?? "-";
+  if (isSse) console.log(`[unoverse:sse] pump OPEN ${method} ${path} sid=${sid}`);
+
+  // KEEPALIVE — an idle SSE stream writes NOTHING, and a silent connection is fair game
+  // for any middlebox (the Vite dev proxy kills one after ~2 min; observed as "client
+  // aborted" mid-run, after which every push into the still-registered session drops
+  // silently). An SSE comment line every 25s keeps every hop alive; parsers ignore
+  // comments by spec, so no client sees them.
+  // 10s, not 25s: the client's zombie watchdog declares death after ~1.5 missed
+  // beats, so the beat interval directly sets how long a silently-dead stream can
+  // blind the canvas. Comment lines are ~18 bytes — frequency is free.
+  const keepalive = isSse
+    ? setInterval(() => {
+        if (!state.aborted) res.cork(() => res.write(": keepalive\n\n"));
+      }, 10_000)
+    : null;
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (state.aborted) {
+        void reader.cancel().catch(() => {});
+        if (isSse) console.log(`[unoverse:sse] pump CLOSED (client aborted) ${method} ${path} sid=${sid}`);
+        return;
+      }
+      if (done) break;
+      if (value) res.cork(() => res.write(value));
+    }
+    if (!state.aborted) res.cork(() => res.end());
+    if (isSse) console.log(`[unoverse:sse] pump CLOSED (stream ended) ${method} ${path} sid=${sid}`);
+  } catch {
+    void reader.cancel().catch(() => {});
+    if (!state.aborted) res.cork(() => res.end());
+    if (isSse) console.log(`[unoverse:sse] pump CLOSED (pump error) ${method} ${path} sid=${sid}`);
+  } finally {
+    if (keepalive) clearInterval(keepalive);
+  }
+}

package/vendor/base/src/items/baseVersion.ts

@@ -0,0 +1,96 @@
+/**
+ * The design system version an asset was authored against.
+ *
+ * TWO PARTS, because neither alone is enough:
+ *
+ *     1.4.2+a3f1
+ *     └───┘ └──┘
+ *       │     └── HASH over every member's content. Derived, so it cannot be forgotten or
+ *       │         bumped wrongly, and it moves the instant anything moves. This is what
+ *       │         actually answers "did it change".
+ *       └──────── PACKAGE VERSION, when there is one. Declared, so it can be stale, but it
+ *                 is ORDERED, which a hash never is. This is what answers "which way".
+ *
+ * A hash alone tells you two things differ and not which is newer. A version alone can be
+ * wrong, and is absent entirely in the monorepo where the design system is uncommitted
+ * source on disk rather than an installed package. So: hash always, version when known.
+ *
+ * WHAT IT IS FOR. Every published asset is built ON the design system: a component composes
+ * marketplace atoms, an app composes components, an org's tokens override a foundation
+ * scale. When the foundation moves, an item authored against the older one may reference
+ * something that no longer exists. The symptom is a hole where a component should be, seen
+ * by an end user and traceable to nothing. This is the record that makes it traceable.
+ *
+ * It cannot be backfilled: nothing else anywhere records what a definition was written
+ * against. See migration 018 and DECLARATIVE_NODES.md §9.12.
+ */
+import { createHash } from "crypto";
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { fingerprintOf } from "./fingerprint.js";
+
+/** Short, readable, and only ever compared for equality. */
+function shortHash(s: string): string {
+  return createHash("sha256").update(s).digest("hex").slice(0, 8);
+}
+
+/** Every file under a directory, sorted, so the hash is order-independent. */
+function filesUnder(dir: string, prefix = "", out: Record<string, string> = {}): Record<string, string> {
+  if (!existsSync(dir)) return out;
+  for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (e.isDirectory()) filesUnder(join(dir, e.name), rel, out);
+    else if (/\.(ya?ml|json)$/.test(e.name)) out[rel] = readFileSync(join(dir, e.name), "utf8");
+  }
+  return out;
+}
+
+/**
+ * The declared version, if the design system arrived as a package.
+ *
+ * Absent in the monorepo, where it is source on disk. That absence is honest rather than a
+ * gap: there is no version, because nobody cut one.
+ */
+function packageVersion(designSystemDir: string): string | null {
+  // The bundle lives at <package>/definitions, so its package.json is one level up.
+  for (const candidate of [join(designSystemDir, "..", "package.json"), join(designSystemDir, "package.json")]) {
+    if (!existsSync(candidate)) continue;
+    try {
+      const v = JSON.parse(readFileSync(candidate, "utf8"))?.version;
+      if (typeof v === "string") return v;
+    } catch {
+      /* unreadable package.json: fall through to the hash alone */
+    }
+  }
+  return null;
+}
+
+/**
+ * Compute the version of the design system at `designSystemDir` (the resolved marketplace
+ * directory: on-disk design/marketplace, or the installed bundle).
+ *
+ * Hashes components, atoms and styles together, because they only mean anything as a set:
+ * a universe holding half of them renders against a contract with holes.
+ */
+export function designSystemVersion(designSystemDir: string): string {
+  const parts: string[] = [];
+
+  for (const kind of ["components", "atoms"] as const) {
+    const home = join(designSystemDir, kind);
+    if (!existsSync(home)) continue;
+    for (const e of readdirSync(home, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (e.name.startsWith(".") || e.name === "README.md") continue;
+      const files = e.isDirectory()
+        ? filesUnder(join(home, e.name))
+        : { [e.name]: readFileSync(join(home, e.name), "utf8") };
+      parts.push(`${kind}/${e.name}:${fingerprintOf(files)}`);
+    }
+  }
+
+  const styles = filesUnder(join(designSystemDir, "styles"));
+  if (Object.keys(styles).length) parts.push(`styles:${fingerprintOf(styles)}`);
+
+  const hash = shortHash(parts.join("|"));
+  const declared = packageVersion(designSystemDir);
+  return declared ? `${declared}+${hash}` : hash;
+}