@dharta/cli 0.6.77 → 0.6.78

package/src/genui.ts

@@ -0,0 +1,1398 @@
+// RFC 0056 generative UI: the CLI-side mirror of the data plane's `[genui]`
+// contract, plus the compiler that turns a source folder into the bundle the
+// data plane serves.
+//
+// SOURCE OF TRUTH: apps/dharta-python/src/dharta/genui/manifest.py (the
+// `[genui]` table) and apps/dharta-python/src/dharta/genui/bundle.py (the
+// `dharta.genui-bundle.v1` file). Those two files decide what a release is
+// allowed to carry; everything here is a local mirror whose only job is to fail
+// on the developer's machine instead of at deploy. Change either Python file and
+// this one has to move with it. test/genui-crossplane.test.ts reads both files
+// out of the monorepo and pins every constant below against them. The widget
+// re-validates the same shape a third time in
+// sdks/widget/src/transport/managedAgents.ts (`coerceGenuiCatalog`).
+//
+// The mirror is hand-written rather than generated from a @dharta/contracts
+// schema because that package's established pattern is a language-neutral JSON
+// file pinned by conformance tests on BOTH sides (see its README). The Python
+// side of that pin lives in apps/dharta-python, so a half-pinned schema would
+// claim a guarantee it does not have - and the CLI would gain a runtime
+// dependency it does not otherwise need.
+
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import TOML from "@iarna/toml";
+import { setGenuiBundleSha256, tableScalarLiteral } from "./manifest.js";
+
+// --- The contract, mirrored -------------------------------------------------
+
+export const BUNDLE_FORMAT = "dharta.genui-bundle.v1";
+export const MAX_BUNDLE_BYTES = 5 * 1024 * 1024;
+export const MAX_COMPONENTS = 128;
+export const MAX_WORKER_BYTES = 500 * 1024;
+export const MAX_HTML_BYTES = 1024 * 1024;
+export const MAX_EVENTS = 64;
+export const MAX_EVENT_NAME_LENGTH = 128;
+export const EVENT_CADENCES = ["agent_action", "reference", "side_effect"] as const;
+
+// Must equal bundle.py's TIER1_BUILTINS exactly: a Tier-1 component is only an
+// alias for one of Dharta's own host-rendered primitives.
+export const TIER1_BUILTINS = [
+  "Badge",
+  "Button",
+  "Card",
+  "Checkbox",
+  "Column",
+  "Divider",
+  "Heading",
+  "Row",
+  "Select",
+  "Text",
+  "TextField",
+] as const;
+
+// manifest.py's _IDENTIFIER, for both catalog_id and component names.
+export const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_.:/@-]{0,127}$/;
+
+// Where `dharta genui build` looks for component sources when
+// `[genui.build] source` is unset. One directory per component, named exactly
+// as the component.
+export const DEFAULT_SOURCE_DIR = "genui/components";
+export const COMPONENT_SPEC_FILE = "component.json";
+export const TIER2_SOURCE_FILE = "worker.js";
+export const TIER3_SOURCE_FILE = "index.html";
+
+// The data plane's own wording for the two path rejections in
+// bundle.py::_read_regular_file. `checkGenui` reports them verbatim, because a
+// pre-flight refusal should read exactly like the release rejection it
+// predicts; the build appends the offending path, because there the developer
+// is being told which link to remove.
+const CROSSES_SYMLINK = "[genui] bundle path crosses a non-directory or symlink";
+const NOT_A_REGULAR_FILE = "[genui] bundle must be a regular file";
+
+/** A `[genui]` section, or a bundle, that the data plane would reject. */
+export class GenuiError extends Error {}
+
+export interface GenuiComponent {
+  name: string;
+  tier: 1 | 2 | 3;
+}
+
+export interface GenuiSection {
+  catalogId: string;
+  version: number;
+  /** Release-relative path to the built bundle; null when Tier-1 only. */
+  bundle: string | null;
+  bundleSha256: string | null;
+  components: GenuiComponent[];
+  enabled: boolean;
+  /** Release-relative component source folder, from `[genui.build] source`. */
+  source: string;
+}
+
+function plainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// --- [genui] parsing (mirror of manifest.py parse_genui) --------------------
+
+export interface ParseGenuiOptions {
+  /**
+   * The data plane requires bundle_sha256 whenever bundle is set, and so does
+   * every read path here. `dharta genui build` is the one exception: it is the
+   * thing that produces the digest, so it must be able to parse a manifest that
+   * declares a bundle it has not built yet.
+   */
+  requireDigest?: boolean;
+  /**
+   * The manifest's raw text. Supplied so `version` can be judged by its TOML
+   * literal rather than by the JavaScript number it parsed to - see
+   * `rejectFloatVersion`.
+   */
+  text?: string;
+}
+
+/**
+ * Parse the `[genui]` table out of a loaded `dharta.toml`. Returns null when
+ * there is no section (generative UI is opt-in); throws `GenuiError` on a
+ * section the data plane would reject.
+ */
+export function parseGenuiSection(
+  manifest: Record<string, unknown>,
+  options: ParseGenuiOptions = {},
+): GenuiSection | null {
+  const requireDigest = options.requireDigest !== false;
+  const raw = manifest.genui;
+  if (raw === undefined) return null;
+  if (!plainObject(raw)) throw new GenuiError("[genui] must be a table");
+
+  const catalogId = raw.catalog_id;
+  if (typeof catalogId !== "string" || !IDENTIFIER.test(catalogId.trim())) {
+    throw new GenuiError("[genui] requires a non-empty string catalog_id");
+  }
+
+  const rawBundle = raw.bundle;
+  if (rawBundle !== undefined && (typeof rawBundle !== "string" || !rawBundle.trim())) {
+    throw new GenuiError("[genui] bundle must be a non-empty string path when set");
+  }
+  const bundle = typeof rawBundle === "string" ? rawBundle.trim() : null;
+
+  if (options.text !== undefined) rejectFloatVersion(options.text);
+  const version = raw.version === undefined ? 1 : raw.version;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    throw new GenuiError("[genui] version must be a positive integer");
+  }
+
+  const digest = raw.bundle_sha256;
+  const digestValid = typeof digest === "string" && /^[0-9a-f]{64}$/.test(digest);
+  if (bundle !== null) {
+    if (requireDigest && !digestValid) {
+      throw new GenuiError(
+        "[genui] bundle_sha256 must be a lowercase 64-character SHA-256 digest",
+      );
+    }
+  } else if (digest !== undefined) {
+    throw new GenuiError("[genui] bundle_sha256 requires bundle");
+  }
+
+  const enabled = raw.enabled === undefined ? true : raw.enabled;
+  if (typeof enabled !== "boolean") throw new GenuiError("[genui] enabled must be a boolean");
+
+  return {
+    catalogId: catalogId.trim(),
+    version,
+    bundle,
+    bundleSha256: digestValid ? (digest as string) : null,
+    components: parseComponents(raw.components === undefined ? [] : raw.components, bundle !== null),
+    enabled,
+    source: parseBuildTable(raw.build),
+  };
+}
+
+// `[genui.build]` is a CLI-only sub-table: `dharta genui build` reads it, the
+// release contract never does. Safe because manifest.py's parse_genui reads
+// only its own known keys off the section mapping (catalog_id, bundle, version,
+// bundle_sha256, enabled, components) and nothing in releases.py rejects
+// unrecognized keys, so an extra sub-table is simply ignored at deploy. Keeping
+// it out of `[genui]` itself means a CLI-only key can never collide with a key
+// the data plane later adds there.
+function parseBuildTable(raw: unknown): string {
+  if (raw === undefined) return DEFAULT_SOURCE_DIR;
+  if (!plainObject(raw)) throw new GenuiError("[genui.build] must be a table");
+  const source = raw.source;
+  if (source === undefined) return DEFAULT_SOURCE_DIR;
+  if (typeof source !== "string" || !source.trim()) {
+    throw new GenuiError("[genui.build] source must be a non-empty string path when set");
+  }
+  return source.trim();
+}
+
+// `@iarna/toml` returns a JavaScript number for both `version = 1` and
+// `version = 1.0`, so by the time the value reaches us the two are identical.
+// Python's tomllib keeps them apart: `1.0` is a float, and manifest.py's
+// `isinstance(version, int)` rejects it. Read the literal back out of the
+// manifest text so the deploy-time failure surfaces here instead.
+//
+// Best effort by construction: it only sees a plain `[genui]` table with a
+// `version = ...` line. An inline (`genui = { version = 1.0 }`) or dotted
+// (`genui.version = 1.0`) spelling is invisible to it and still fails at
+// deploy, with this same message.
+function rejectFloatVersion(text: string): void {
+  const literal = tableScalarLiteral(text, "genui", "version");
+  if (literal === null || !isTomlFloatLiteral(literal)) return;
+  throw new GenuiError("[genui] version must be a positive integer");
+}
+
+function isTomlFloatLiteral(literal: string): boolean {
+  if (/^[+-]?(inf|nan)$/.test(literal)) return true;
+  if (/^[+-]?0[xob]/i.test(literal)) return false; // hex/octal/binary are integers
+  return /[.eE]/.test(literal);
+}
+
+function parseComponents(raw: unknown, hasBundle: boolean): GenuiComponent[] {
+  if (!Array.isArray(raw)) throw new GenuiError("[genui] components must be an array of tables");
+  const out: GenuiComponent[] = [];
+  const seen = new Set<string>();
+  for (const entry of raw) {
+    if (!plainObject(entry)) throw new GenuiError("each [genui] component must be a table");
+    const rawName = entry.name;
+    if (typeof rawName !== "string" || !IDENTIFIER.test(rawName.trim())) {
+      throw new GenuiError("each [genui] component needs a non-empty name");
+    }
+    const name = rawName.trim();
+    if (seen.has(name)) throw new GenuiError(`duplicate genui component: '${name}'`);
+    seen.add(name);
+    const tier = entry.tier === undefined ? 1 : entry.tier;
+    if (tier !== 1 && tier !== 2 && tier !== 3) {
+      throw new GenuiError(`component '${name}' tier must be one of 1, 2, 3`);
+    }
+    if (tier >= 2 && !hasBundle) {
+      throw new GenuiError(
+        `component '${name}' is tier ${tier} (builder code) but [genui] declares no bundle`,
+      );
+    }
+    out.push({ name, tier });
+  }
+  return out;
+}
+
+// --- bundle validation (mirror of bundle.py _validate_payload) --------------
+
+/**
+ * The catalog the data plane synthesizes when `[genui]` declares no bundle
+ * (bundle.py load_genui_bundle_with_bytes). It runs the SAME payload validation
+ * over it, so a Tier-1-only catalog is not unvalidated: a component whose name
+ * is not a Dharta builtin, or a 129th component, is rejected at deploy.
+ */
+export function synthesizeBundlePayload(section: GenuiSection): Record<string, unknown> {
+  return {
+    format: BUNDLE_FORMAT,
+    catalog_id: section.catalogId,
+    version: section.version,
+    components: section.components.map((component) => ({
+      name: component.name,
+      tier: component.tier,
+      implementation: { builtin: component.name },
+    })),
+  };
+}
+
+/**
+ * Throw `GenuiError` unless `payload` is a bundle this manifest can ship.
+ *
+ * `rawText` is the bundle file's bytes as read off disk, when there was one.
+ * The whole integer rule lives here because JavaScript cannot see it in the
+ * parsed value: `JSON.parse` collapses `1.0` to `1`, while Python's
+ * `json.loads` yields a float that fails `isinstance(..., int)`.
+ */
+export function validateBundlePayload(
+  payload: unknown,
+  section: GenuiSection,
+  rawText?: string,
+): void {
+  if (!plainObject(payload)) throw new GenuiError("[genui] bundle root must be an object");
+  if (payload.format !== BUNDLE_FORMAT) {
+    throw new GenuiError(`[genui] bundle format must be '${BUNDLE_FORMAT}'`);
+  }
+  if (rawText !== undefined) rejectNonIntegerLiterals(rawText);
+  if (
+    payload.catalog_id !== section.catalogId ||
+    typeof payload.version !== "number" ||
+    !Number.isInteger(payload.version) ||
+    payload.version !== section.version
+  ) {
+    throw new GenuiError("[genui] bundle identity does not match dharta.toml");
+  }
+
+  const rawComponents = payload.components;
+  if (!Array.isArray(rawComponents) || rawComponents.length > MAX_COMPONENTS) {
+    throw new GenuiError(
+      `[genui] bundle components must be an array of at most ${MAX_COMPONENTS} entries`,
+    );
+  }
+
+  const actual = new Map<string, number>();
+  for (const component of rawComponents) {
+    if (!plainObject(component)) {
+      throw new GenuiError("[genui] every bundled component must be an object");
+    }
+    const name = component.name;
+    const tier = component.tier;
+    if (
+      typeof name !== "string" ||
+      !name ||
+      actual.has(name) ||
+      (tier !== 1 && tier !== 2 && tier !== 3)
+    ) {
+      throw new GenuiError("[genui] bundled component name/tier is invalid or duplicated");
+    }
+    actual.set(name, tier);
+    if (component.props_schema !== undefined && !plainObject(component.props_schema)) {
+      throw new GenuiError(`[genui] component '${name}' props_schema must be an object`);
+    }
+    const events = component.events === undefined ? {} : component.events;
+    if (!plainObject(events)) {
+      throw new GenuiError(`[genui] component '${name}' events must be an object`);
+    }
+    validateEvents(name, events);
+    if (!plainObject(component.implementation)) {
+      throw new GenuiError(`[genui] component '${name}' needs an implementation object`);
+    }
+    validateImplementation(name, tier, component.implementation);
+  }
+
+  const expected = new Map(section.components.map((c) => [c.name, c.tier as number]));
+  const matches =
+    actual.size === expected.size &&
+    [...expected].every(([name, tier]) => actual.get(name) === tier);
+  if (!matches) {
+    throw new GenuiError(
+      "[genui] bundled components do not exactly match dharta.toml " +
+        `(dharta.toml: ${describeComponents(expected)}; bundle: ${describeComponents(actual)})`,
+    );
+  }
+}
+
+function describeComponents(components: Map<string, number>): string {
+  const entries = [...components].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return entries.length === 0
+    ? "(none)"
+    : entries.map(([name, tier]) => `${name}@tier${tier}`).join(", ");
+}
+
+function validateImplementation(name: string, tier: number, impl: Record<string, unknown>): void {
+  if (tier === 1) {
+    const keys = Object.keys(impl);
+    const builtin = impl.builtin;
+    if (
+      keys.length !== 1 ||
+      keys[0] !== "builtin" ||
+      typeof builtin !== "string" ||
+      !(TIER1_BUILTINS as readonly string[]).includes(builtin)
+    ) {
+      throw new GenuiError(
+        `[genui] Tier-1 component '${name}' must alias a Dharta builtin ` +
+          `(one of ${TIER1_BUILTINS.join(", ")})`,
+      );
+    }
+    // A built-in name may only alias itself. The widget merges a registered
+    // catalog OVER the built-in one, so `{ name: "Card", builtin: "Badge" }`
+    // reads as an alias but takes the built-in's name, and every Card in the
+    // transcript - including surfaces that never asked for this catalog - would
+    // draw as a Badge.
+    if ((TIER1_BUILTINS as readonly string[]).includes(name) && builtin !== name) {
+      throw new GenuiError(
+        `[genui] Tier-1 component '${name}' takes a built-in component name and aliases ` +
+          `'${builtin}'; a built-in name may only alias itself. Rename the component, or ` +
+          `drop the alias so '${name}' renders as the built-in '${name}'.`,
+      );
+    }
+    return;
+  }
+  // A builder component may not take a built-in's name: the renderer resolves
+  // by name, so a Tier-2/3 component called `Card` would shadow the host
+  // primitive every other surface expects. Tier-1 entries are aliases FOR those
+  // primitives, so they keep the name.
+  if ((TIER1_BUILTINS as readonly string[]).includes(name)) {
+    throw new GenuiError(
+      `[genui] Tier-${tier} component '${name}' may not reuse the name of a Dharta builtin; ` +
+        "rename it, or declare it as a Tier-1 alias",
+    );
+  }
+  const field = tier === 2 ? "worker" : "html";
+  const limit = tier === 2 ? MAX_WORKER_BYTES : MAX_HTML_BYTES;
+  const source = impl[field];
+  const keys = Object.keys(impl);
+  if (
+    keys.length !== 1 ||
+    keys[0] !== field ||
+    typeof source !== "string" ||
+    Buffer.byteLength(source, "utf8") > limit
+  ) {
+    throw new GenuiError(
+      `[genui] Tier-${tier} component '${name}' needs bounded ${field} source ` +
+        `(a string of at most ${limit} bytes)`,
+    );
+  }
+}
+
+function validateEvents(name: string, events: Record<string, unknown>): void {
+  const entries = Object.entries(events);
+  if (entries.length > MAX_EVENTS) {
+    throw new GenuiError(`[genui] component '${name}' declares too many events`);
+  }
+  for (const [eventName, raw] of entries) {
+    if (
+      !eventName ||
+      // Python's len() counts code points, so an emoji costs 1 there and 2 in
+      // UTF-16. Count the same units it does.
+      Array.from(eventName).length > MAX_EVENT_NAME_LENGTH ||
+      !plainObject(raw) ||
+      !(EVENT_CADENCES as readonly string[]).includes(raw.cadence as string)
+    ) {
+      throw new GenuiError(
+        `[genui] component '${name}' has an invalid event declaration '${eventName}' ` +
+          `(each event needs cadence = ${EVENT_CADENCES.join(" | ")})`,
+      );
+    }
+    // `context_schema: null` is accepted: Python tests `is not None` first.
+    if (
+      raw.context_schema !== undefined &&
+      raw.context_schema !== null &&
+      !plainObject(raw.context_schema)
+    ) {
+      throw new GenuiError(`[genui] component '${name}' event schema must be an object`);
+    }
+  }
+}
+
+/**
+ * Reject a numeric literal the contract requires to be an integer but which was
+ * written as a float: the root object's `version`, and `tier` inside the root's
+ * `components` array. Python's `json.loads` returns a float for `1.0` / `1e0`
+ * and the data plane's `isinstance(..., int)` refuses it, while JavaScript has
+ * a single number type and cannot tell after parsing.
+ *
+ * Depth-tracked so it judges only those two positions: a component's
+ * `props_schema` may legitimately describe a `version` or `tier` of its own,
+ * and that is builder data, not the bundle's contract.
+ */
+function rejectNonIntegerLiterals(text: string): void {
+  // The key that opened each container: null for the root object and for the
+  // objects inside an array, "components" for the components array itself.
+  const containers: Array<string | null> = [];
+  let lastKey: string | null = null;
+
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index];
+    if (char === '"') {
+      let end = index + 1;
+      while (end < text.length && text[end] !== '"') end += text[end] === "\\" ? 2 : 1;
+      lastKey = text.slice(index + 1, end);
+      index = end;
+      continue;
+    }
+    if (char === "{" || char === "[") {
+      containers.push(lastKey);
+      lastKey = null;
+      continue;
+    }
+    if (char === "}" || char === "]") {
+      containers.pop();
+      lastKey = null;
+      continue;
+    }
+    if (char !== ":") continue;
+
+    const atRoot = containers.length === 1;
+    const inComponent =
+      containers.length === 3 && containers[1] === "components" && containers[2] === null;
+    if (!(atRoot && lastKey === "version") && !(inComponent && lastKey === "tier")) continue;
+
+    const literal = text.slice(index + 1).match(/^\s*([^\s,}\]]+)/)?.[1];
+    if (literal === undefined || !isJsonFloatLiteral(literal)) continue;
+    throw new GenuiError(
+      lastKey === "version"
+        ? "[genui] bundle identity does not match dharta.toml"
+        : "[genui] bundled component name/tier is invalid or duplicated",
+    );
+  }
+}
+
+function isJsonFloatLiteral(literal: string): boolean {
+  return /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(literal) && /[.eE]/.test(literal);
+}
+
+/** A number in a JSON document that a JavaScript double cannot carry. */
+interface UnsafeNumber {
+  /** Dotted and indexed path from the root, for example `props_schema.rows[0].max`. */
+  path: string;
+  literal: string;
+  /**
+   * `integer` - beyond Number.MAX_SAFE_INTEGER, so it is silently rounded.
+   * `overflow` - beyond a double's range, so it parses to +/-Infinity and
+   * serializes as `null`.
+   */
+  kind: "integer" | "overflow";
+}
+
+/**
+ * The first number literal in `text` that a JavaScript double cannot carry, or
+ * null when there is none. Two shapes qualify, and both are silent:
+ *
+ * An integer beyond `Number.MAX_SAFE_INTEGER`. `JSON.parse` rounds
+ * `12345678901234567890` to `12345678901234567000` and nothing downstream can
+ * tell, so a build would write digits into the bundle that the source never
+ * had - and the data plane, whose `int` is arbitrary precision, would read the
+ * builder's own digits back out of its own copy.
+ *
+ * A float that overflows a double. `1e400` parses to `Infinity`, which
+ * `JSON.stringify` writes as `null`: the bundle would carry no number at all
+ * where the source had one, while Python's `float` reads the same literal as
+ * `inf` and keeps it.
+ *
+ * Every other float is left alone. `0.1` and `1.5e300` are IEEE doubles on both
+ * planes, so the two lose exactly the same precision and still agree.
+ *
+ * The only place the real number still exists is the raw text, so read it
+ * there, the same way `rejectNonIntegerLiterals` reads `version` and `tier`.
+ */
+function findUnsafeNumberLiteral(text: string): UnsafeNumber | null {
+  // One frame per open container. `base` is the path of the container itself;
+  // `key` and `index` say where the container's NEXT value goes.
+  const frames: Array<{ array: boolean; base: string; key: string; index: number }> = [];
+
+  // The path of the value about to be read.
+  const at = (): string => {
+    const frame = frames[frames.length - 1];
+    if (frame === undefined) return "the document root";
+    if (frame.array) return `${frame.base}[${frame.index}]`;
+    return frame.base === "" ? frame.key : `${frame.base}.${frame.key}`;
+  };
+
+  for (let index = 0; index < text.length; index++) {
+    const char = text[index];
+    if (char === '"') {
+      let end = index + 1;
+      while (end < text.length && text[end] !== '"') end += text[end] === "\\" ? 2 : 1;
+      const value = text.slice(index + 1, end);
+      index = end;
+      // A string followed by `:` is its object's next key. Every other string
+      // is a value, and a value never moves the path.
+      const frame = frames[frames.length - 1];
+      if (frame !== undefined && !frame.array && /^\s*:/.test(text.slice(index + 1))) {
+        frame.key = value;
+      }
+      continue;
+    }
+    if (char === "{" || char === "[") {
+      frames.push({
+        array: char === "[",
+        base: frames.length === 0 ? "" : at(),
+        key: "",
+        index: 0,
+      });
+      continue;
+    }
+    if (char === "}" || char === "]") {
+      frames.pop();
+      continue;
+    }
+    if (char === ",") {
+      const frame = frames[frames.length - 1];
+      if (frame?.array) frame.index += 1;
+      continue;
+    }
+    if (char !== "-" && (char < "0" || char > "9")) continue;
+    const literal = text.slice(index).match(/^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/)?.[0];
+    if (literal === undefined) continue;
+    index += literal.length - 1;
+    if (/^-?\d+$/.test(literal)) {
+      // BigInt, not Number: the comparison has to be exact at the boundary,
+      // and Number() has already lost the digits that decide it.
+      const digits = literal.startsWith("-") ? literal.slice(1) : literal;
+      if (BigInt(digits) > BigInt(Number.MAX_SAFE_INTEGER)) {
+        return { path: at(), literal, kind: "integer" };
+      }
+    } else if (!Number.isFinite(Number(literal))) {
+      return { path: at(), literal, kind: "overflow" };
+    }
+  }
+  return null;
+}
+
+// --- canonical serialization ------------------------------------------------
+
+/**
+ * Byte-for-byte reproducible JSON, matching the data plane's own canonical form
+ * (`json.dumps(..., ensure_ascii=True, separators=(",", ":"), sort_keys=True)`):
+ * sorted keys, compact separators, ASCII only. The digest recorded in
+ * dharta.toml is over these exact bytes, so a rebuild of unchanged sources must
+ * produce an unchanged file.
+ *
+ * Written out key by key rather than sorted into an object and handed to
+ * `JSON.stringify`, because a JavaScript object does not preserve the order you
+ * insert integer-like keys in: it emits those first, in ascending numeric
+ * order. `{"1","10","2","alpha"}` is Python's order and `{"1","2","10","alpha"}`
+ * is what an object round-trip produces, which is a different digest for the
+ * same catalog.
+ *
+ * Numbers are JavaScript doubles, and this writes back whatever `JSON.parse`
+ * produced. `1.0` therefore serializes as `1` and `-0.0` as `0` - the source
+ * spelling is already gone by the time the value gets here, and re-deriving it
+ * is not possible. Both forms are the same double on the data plane too, so
+ * this only ever narrows the spelling, never the value.
+ *
+ * Two shapes a double cannot carry at all: an integer beyond
+ * `Number.MAX_SAFE_INTEGER`, which arrives already rounded, and a float that
+ * overflows a double, which arrives as `Infinity` and would be written out as
+ * `null`. `findUnsafeNumberLiteral` refuses both in a component.json rather
+ * than letting the build ship a number the source never wrote.
+ */
+export function canonicalJson(value: unknown): string {
+  return escapeNonAscii(encodeCanonical(value));
+}
+
+function encodeCanonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(encodeCanonical).join(",")}]`;
+  if (plainObject(value)) {
+    const members = Object.keys(value)
+      .sort(byCodePoint)
+      .map((key) => `${JSON.stringify(key)}:${encodeCanonical(value[key])}`);
+    return `{${members.join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+// Python sorts by Unicode code point; JavaScript's default sort compares UTF-16
+// code units, which orders astral-plane keys differently. Compare code points so
+// a builder's exotic props_schema key cannot make the two planes disagree.
+function byCodePoint(a: string, b: string): number {
+  const ca = Array.from(a);
+  const cb = Array.from(b);
+  for (let i = 0; i < Math.min(ca.length, cb.length); i++) {
+    const delta = (ca[i].codePointAt(0) ?? 0) - (cb[i].codePointAt(0) ?? 0);
+    if (delta !== 0) return delta;
+  }
+  return ca.length - cb.length;
+}
+
+function escapeNonAscii(json: string): string {
+  // U+007F..U+FFFF, matching Python's ensure_ascii, which escapes everything
+  // outside the printable ASCII range - DEL included.
+  return json.replace(
+    /[\u007f-\uffff]/g,
+    (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+export function sha256Hex(bytes: Buffer | string): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+// --- loading ----------------------------------------------------------------
+
+/** A `dharta.toml` read once and reused by every genui code path. */
+export interface ManifestSource {
+  path: string;
+  text: string;
+  parsed: Record<string, unknown>;
+}
+
+export interface LoadedGenui extends ManifestSource {
+  section: GenuiSection | null;
+}
+
+/** Read `dir/dharta.toml`. Throws when it is missing or unparseable. */
+export async function readManifest(dir: string): Promise<ManifestSource> {
+  const manifestPath = path.join(dir, "dharta.toml");
+  let text: string;
+  try {
+    text = await fs.readFile(manifestPath, "utf8");
+  } catch {
+    throw new GenuiError(
+      `No dharta.toml at ${manifestPath}. Run this from an agent folder, or pass its path.`,
+    );
+  }
+  try {
+    return { path: manifestPath, text, parsed: TOML.parse(text) as Record<string, unknown> };
+  } catch (error) {
+    throw new GenuiError(`Could not parse ${manifestPath}: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Read and parse an agent's `[genui]` section once. Every command path threads
+ * the result rather than re-reading the manifest: `dharta dev`'s doctor already
+ * holds a parsed one and hands it straight in.
+ */
+export async function loadGenui(
+  source: string | ManifestSource,
+  options: ParseGenuiOptions = {},
+): Promise<LoadedGenui> {
+  const manifest = typeof source === "string" ? await readManifest(source) : source;
+  return {
+    ...manifest,
+    section: parseGenuiSection(manifest.parsed, { ...options, text: manifest.text }),
+  };
+}
+
+// Release-relative paths are split on "/" only, matching pathlib's Path.parts
+// on the POSIX data plane: there, a backslash is an ordinary filename
+// character, and treating it as a separator here would reject paths the server
+// accepts.
+function relativeParts(relative: string): string[] {
+  return relative.split("/").filter((part) => part !== "" && part !== ".");
+}
+
+// A release-relative path may not escape the agent folder - the data plane
+// rejects the same thing in load_genui_bundle.
+function requireInsideRelease(relative: string, label: string): string {
+  if (
+    path.isAbsolute(relative) ||
+    relative.startsWith("/") ||
+    relativeParts(relative).includes("..")
+  ) {
+    throw new GenuiError(`[genui] ${label} must stay inside the release: ${relative}`);
+  }
+  return relative;
+}
+
+/**
+ * Walk a release-relative path's parent components, refusing a symlink or a
+ * non-directory exactly the way bundle.py's `_read_regular_file` does. Returns
+ * the absolute leaf path.
+ *
+ * `withPath` names the offending component in the message. The read path leaves
+ * it off so a pre-flight refusal reads exactly like the release rejection it
+ * predicts; the build turns it on, because there the developer needs to know
+ * which link to remove.
+ */
+async function walkBundleParents(
+  root: string,
+  relative: string,
+  options: { withPath: boolean; onMissingParent: "throw" | "stop" },
+): Promise<string | null> {
+  const parts = relativeParts(relative);
+  let cursor = root;
+  for (const part of parts.slice(0, -1)) {
+    cursor = path.join(cursor, part);
+    let stats;
+    try {
+      stats = await fs.lstat(cursor);
+    } catch {
+      // Python reaches a missing parent as "crosses a non-directory". The
+      // rejection is the same either way; which sentence is more useful
+      // depends on the caller, so it decides.
+      if (options.onMissingParent === "throw") {
+        throw new GenuiError(missingBundleMessage(relative));
+      }
+      return null;
+    }
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+      throw new GenuiError(
+        options.withPath
+          ? `${CROSSES_SYMLINK}: ${path.relative(root, cursor)}`
+          : CROSSES_SYMLINK,
+      );
+    }
+  }
+  return path.join(root, ...parts);
+}
+
+function missingBundleMessage(relative: string): string {
+  return `[genui] bundle does not exist: ${relative} - run \`dharta genui build\` to build it.`;
+}
+
+/**
+ * Read the bundle exactly the way bundle.py's `_read_regular_file` does: no
+ * symlink anywhere on the path, a regular file at the leaf, and nothing larger
+ * than the cap. `lstat` throughout, because the point is the link itself, not
+ * what it points at - a symlinked bundle resolves fine locally and is refused
+ * by the release validator's O_NOFOLLOW open.
+ */
+async function readBundleBytes(root: string, relative: string): Promise<Buffer> {
+  const file = await walkBundleParents(root, relative, {
+    withPath: false,
+    onMissingParent: "throw",
+  });
+  let stats;
+  try {
+    stats = await fs.lstat(file!);
+  } catch {
+    throw new GenuiError(missingBundleMessage(relative));
+  }
+  if (stats.isSymbolicLink() || !stats.isFile()) throw new GenuiError(NOT_A_REGULAR_FILE);
+  if (stats.size > MAX_BUNDLE_BYTES) {
+    throw new GenuiError(`${NOT_A_REGULAR_FILE} no larger than 5 MiB`);
+  }
+  return fs.readFile(file!);
+}
+
+/**
+ * The write-side of the same policy. Without it the build happily writes
+ * THROUGH a symlink that every later read then refuses, so `build` would report
+ * success and `check` would immediately contradict it.
+ */
+async function assertBundleWritable(root: string, relative: string): Promise<void> {
+  const file = await walkBundleParents(root, relative, {
+    withPath: true,
+    onMissingParent: "stop", // mkdir will create it; nothing to inspect yet
+  });
+  if (file === null) return;
+  const stats = await fs.lstat(file).catch(() => null);
+  if (stats === null) return; // does not exist yet: the normal first build
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    throw new GenuiError(`${NOT_A_REGULAR_FILE}: ${relative}`);
+  }
+}
+
+// --- check ------------------------------------------------------------------
+
+export interface GenuiCheck {
+  manifest: string;
+  /** Null when there is no [genui] section, or when it failed to parse. */
+  section: GenuiSection | null;
+  /** Every reason the data plane would reject this release. Empty = accepted. */
+  problems: string[];
+}
+
+/**
+ * Report every reason the data plane would reject this agent's `[genui]`
+ * declaration. Shared by `dharta genui check`, `dharta dev`'s doctor
+ * (warnings), and the deploy pre-flight (refusal) so all three say the same
+ * thing. Pass an already-read manifest to avoid a second read.
+ */
+export async function checkGenui(source: string | ManifestSource): Promise<GenuiCheck> {
+  let manifest: ManifestSource;
+  try {
+    manifest = typeof source === "string" ? await readManifest(source) : source;
+  } catch {
+    // A missing or unparseable dharta.toml is not a genui problem: the doctor
+    // and the deploy both report it in their own words, on their own path.
+    return { manifest: path.join(source as string, "dharta.toml"), section: null, problems: [] };
+  }
+  const dir = path.dirname(manifest.path);
+
+  let section: GenuiSection | null;
+  try {
+    section = parseGenuiSection(manifest.parsed, { text: manifest.text });
+  } catch (error) {
+    return { manifest: manifest.path, section: null, problems: [(error as Error).message] };
+  }
+  // No section: generative UI is off. Disabled: the data plane skips the
+  // catalog entirely (releases.py _validate_genui_tree), so nothing below can
+  // fail a deploy.
+  if (section === null || !section.enabled) {
+    return { manifest: manifest.path, section, problems: [] };
+  }
+
+  const problems: string[] = [];
+  try {
+    // A Tier-1-only catalog carries no file, but the data plane still
+    // synthesizes and validates a payload for it, so we do too.
+    if (section.bundle === null) {
+      validateBundlePayload(synthesizeBundlePayload(section), section);
+    } else {
+      requireInsideRelease(section.bundle, "bundle");
+      const raw = await readBundleBytes(dir, section.bundle);
+      const digest = sha256Hex(raw);
+      if (digest !== section.bundleSha256) {
+        problems.push(
+          "[genui] bundle bytes do not match bundle_sha256 " +
+            `(${section.bundle} is ${digest}, dharta.toml records ${section.bundleSha256}) - ` +
+            "run `dharta genui build` to rebuild it and re-record the digest.",
+        );
+      } else {
+        const text = decodeUtf8(raw, `[genui] bundle must be valid UTF-8 JSON`);
+        let payload: unknown;
+        try {
+          payload = JSON.parse(text);
+        } catch {
+          throw new GenuiError("[genui] bundle must be valid UTF-8 JSON");
+        }
+        validateBundlePayload(payload, section, text);
+      }
+    }
+  } catch (error) {
+    problems.push((error as Error).message);
+  }
+  return { manifest: manifest.path, section, problems };
+}
+
+// Decode UTF-8 strictly. Node's default replaces an invalid byte with U+FFFD,
+// which would silently ship a mangled worker or document.
+function decodeUtf8(bytes: Buffer, message: string): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new GenuiError(message);
+  }
+}
+
+export interface GenuiPreflightOptions {
+  /**
+   * The files this deploy will actually ship, release-relative. Deploy sends a
+   * Git-filtered tree (committed HEAD, or a gitignore-honoring tarball) while
+   * every check here reads the WORKING tree, so an ignored bundle passes
+   * locally and arrives missing. Asking the deploy's own file list - rather
+   * than re-deriving the answer from ignore rules - gets force-added files and
+   * non-ASCII names right for free. Optional: without it the pre-flight simply
+   * skips that question.
+   */
+  deployFiles?: () => Promise<string[]>;
+}
+
+/**
+ * Deploy pre-flight: refuse locally, before anything is pushed or uploaded,
+ * with the message the release validator would return.
+ */
+export async function genuiPreflight(
+  dir: string,
+  options: GenuiPreflightOptions = {},
+): Promise<void> {
+  const { section, problems } = await checkGenui(dir);
+  if (options.deployFiles && section?.enabled && section.bundle) {
+    problems.push(...(await missingFromDeploy(dir, section.bundle, options.deployFiles)));
+  }
+  if (problems.length === 0) return;
+  throw new Error(
+    "Generative-UI pre-flight failed - the release would be rejected:\n" +
+      problems.map((problem) => `  ${problem}`).join("\n") +
+      "\n\n  Fix the [genui] section in dharta.toml (or run `dharta genui build`), then re-deploy.",
+  );
+}
+
+async function missingFromDeploy(
+  dir: string,
+  bundle: string,
+  deployFiles: () => Promise<string[]>,
+): Promise<string[]> {
+  // A bundle that is not on disk is already reported by checkGenui, with the
+  // fix that actually applies: build it. "git is not shipping it" is true of
+  // every file that does not exist, so saying it here would name a second
+  // cause that is only a consequence of the first.
+  const onDisk = await fs
+    .stat(path.join(dir, ...relativeParts(bundle)))
+    .then(() => true)
+    .catch(() => false);
+  if (!onDisk) return [];
+
+  // Listing can fail for reasons that are the deploy's own to report (a nested
+  // repository, a git that will not run). An advisory pre-flight never blocks
+  // on its inability to answer.
+  const files = await deployFiles().catch(() => null);
+  if (files === null) return [];
+  // Compare normalized paths, not the two spellings of one path. A bundle
+  // declared with a leading "./" or a doubled slash names the file git lists
+  // plainly, on both planes: pathlib's Path.parts drops the same "." and empty
+  // segments relativeParts does. Comparing the raw strings would refuse a
+  // bundle the deploy is carrying, with a git-ignore diagnosis that is wrong.
+  const wanted = relativeParts(bundle).join("/");
+  if (files.some((file) => relativeParts(file).join("/") === wanted)) return [];
+  return [
+    `${wanted} is not among the files this deploy ships, so the release would fail on a ` +
+      "missing [genui] bundle. Git ignore rules exclude it: unignore it, or force-add it " +
+      `with \`git add -f ${wanted}\`, then commit it and re-run \`dharta deploy\`.`,
+  ];
+}
+
+export interface GenuiStatus {
+  manifest: string;
+  /** False when there is no [genui] section: generative UI is off for this agent. */
+  configured: boolean;
+  catalogId?: string;
+  version?: number;
+  enabled?: boolean;
+  bundle?: string | null;
+  bundleSha256?: string | null;
+  components: GenuiComponent[];
+}
+
+/** `dharta genui check`: the structured result. Throws when something is wrong. */
+export async function genuiCheckData(dir: string): Promise<GenuiStatus> {
+  const manifest = await readManifest(dir); // a missing manifest is an error here
+  const { section, problems } = await checkGenui(manifest);
+  if (problems.length > 0) {
+    throw new Error(
+      "[genui] check failed - a deploy would be rejected:\n" +
+        problems.map((problem) => `  ${problem}`).join("\n"),
+    );
+  }
+  if (section === null) {
+    return { manifest: manifest.path, configured: false, components: [] };
+  }
+  return {
+    manifest: manifest.path,
+    configured: true,
+    catalogId: section.catalogId,
+    version: section.version,
+    enabled: section.enabled,
+    bundle: section.bundle,
+    bundleSha256: section.bundleSha256,
+    components: section.components,
+  };
+}
+
+export function formatGenuiStatus(status: GenuiStatus): string {
+  if (!status.configured) {
+    return `No [genui] section in ${status.manifest} - generative UI is off for this agent.`;
+  }
+  const count = status.components.length;
+  const lines = [
+    `✓ [genui] catalog '${status.catalogId}' v${status.version}: ` +
+      `${count} component${count === 1 ? "" : "s"} (${describeTiers(status.components)})`,
+  ];
+  if (status.enabled === false) {
+    // The catalog is registered but not served, and neither the data plane nor
+    // this check read its bundle. Saying the digest matches would be a claim
+    // nothing verified.
+    lines.push("  enabled = false: the catalog is not served, so its bundle was not checked.");
+  } else if (status.bundle === null) {
+    lines.push(
+      "  No bundle: every component is Tier 1, so Dharta renders them with its own primitives.",
+    );
+  } else {
+    lines.push(`  Bundle ${status.bundle} matches bundle_sha256 ${status.bundleSha256}.`);
+  }
+  return lines.join("\n");
+}
+
+function describeTiers(components: GenuiComponent[]): string {
+  const parts = ([1, 2, 3] as const)
+    .map((tier) => ({ tier, count: components.filter((c) => c.tier === tier).length }))
+    .filter((entry) => entry.count > 0)
+    .map((entry) => `${entry.count} Tier ${entry.tier}`);
+  return parts.length > 0 ? parts.join(", ") : "none";
+}
+
+// --- build ------------------------------------------------------------------
+
+export interface BuildResult {
+  status: "built" | "nothing-to-build";
+  /** Release-relative bundle path, when one was written. */
+  bundle?: string;
+  digest?: string;
+  components: number;
+}
+
+const SPEC_KEYS = ["tier", "builtin", "props_schema", "events"];
+
+/**
+ * Compile `[genui.build] source` into a validated bundle payload. Nothing is
+ * written: this is the seam at the data plane's contract, so a caller can
+ * assert on the exact object a release would carry.
+ */
+export async function compileBundlePayload(
+  section: GenuiSection,
+  dir: string,
+): Promise<Record<string, unknown>> {
+  requireInsideRelease(section.source, "source");
+  const sourceDir = path.join(dir, section.source);
+  await requireExactMatch(section, sourceDir, await discoverComponents(sourceDir, section.source));
+
+  const components = await Promise.all(
+    section.components.map((component) => compileComponent(sourceDir, section.source, component)),
+  );
+  const payload = { format: BUNDLE_FORMAT, catalog_id: section.catalogId, version: section.version, components };
+  validateBundlePayload(payload, section);
+  return payload;
+}
+
+/**
+ * Compile `[genui.build] source` into the bundle at `[genui] bundle` and record
+ * its digest in dharta.toml. Validates everything the data plane validates
+ * before writing, so a bad catalog fails here rather than at deploy.
+ */
+export async function buildGenui(
+  dir: string,
+  log: (line: string) => void,
+): Promise<BuildResult> {
+  const { path: manifestPath, text, section } = await loadGenui(dir, { requireDigest: false });
+  if (section === null) {
+    throw new GenuiError(
+      `No [genui] section in ${manifestPath}. Add one (see the commented block a ` +
+        "scaffolded dharta.toml ships with) before building a component bundle.",
+    );
+  }
+
+  if (section.bundle === null) {
+    // parseGenuiSection already rejected a Tier-2/3 component without a bundle,
+    // so reaching here means Tier-1 only. Nothing is written, but the catalog
+    // the data plane will synthesize still has to be valid.
+    validateBundlePayload(synthesizeBundlePayload(section), section);
+    log(
+      `Nothing to build: [genui] declares no bundle and all ${section.components.length} ` +
+        "component(s) are Tier 1, which Dharta renders with its own primitives.",
+    );
+    return { status: "nothing-to-build", components: section.components.length };
+  }
+
+  requireInsideRelease(section.bundle, "bundle");
+  const payload = await compileBundlePayload(section, dir);
+  const digest = await writeBundle(dir, { manifestPath, text, section }, payload);
+
+  log(
+    `✓ Built ${section.components.length} component${section.components.length === 1 ? "" : "s"} ` +
+      `(${describeTiers(section.components)}) -> ${section.bundle}`,
+  );
+  log(`  bundle_sha256 = "${digest}" recorded in dharta.toml`);
+  if (!section.enabled) {
+    log("  Note: enabled = false, so this catalog is registered but not served.");
+  }
+  return {
+    status: "built",
+    bundle: section.bundle,
+    digest,
+    components: section.components.length,
+  };
+}
+
+async function writeBundle(
+  dir: string,
+  manifest: { manifestPath: string; text: string; section: GenuiSection },
+  payload: Record<string, unknown>,
+): Promise<string> {
+  const { manifestPath, text, section } = manifest;
+  const relative = section.bundle!;
+  const bytes = Buffer.from(`${canonicalJson(payload)}\n`, "utf8");
+  if (bytes.byteLength > MAX_BUNDLE_BYTES) {
+    throw new GenuiError(
+      `Built bundle is ${bytes.byteLength} bytes; the limit is ${MAX_BUNDLE_BYTES}. ` +
+        "Move the largest component to a leaner implementation or split the catalog.",
+    );
+  }
+  const digest = sha256Hex(bytes);
+
+  // Refuse to write through a symlink the read side would then reject: `build`
+  // must not report success that `check` immediately contradicts.
+  await assertBundleWritable(dir, relative);
+
+  // Record the digest, in memory, before anything lands. A manifest whose
+  // [genui] table cannot be patched (an inline table, or dotted keys) must fail
+  // with setGenuiBundleSha256's hand-edit guidance and leave no half-built tree:
+  // a bundle on disk with no matching digest is exactly the state `check`
+  // exists to catch.
+  const patched = setGenuiBundleSha256(text, digest);
+
+  const bundlePath = path.join(dir, ...relativeParts(relative));
+  await fs.mkdir(path.dirname(bundlePath), { recursive: true });
+  await fs.writeFile(bundlePath, bytes);
+
+  // Read back what actually landed, BEFORE dharta.toml records the digest. An
+  // editor, a filter driver, or a CRLF checkout can change the bytes between
+  // write and hash, and a manifest patched first would be left naming a digest
+  // the file on disk does not have - the state this check exists to prevent.
+  const written = sha256Hex(await fs.readFile(bundlePath));
+  if (written !== digest) {
+    throw new GenuiError(
+      `Wrote ${relative} but it hashes to ${written}, not the expected ${digest}. ` +
+        "Something is rewriting the file on disk (a Git filter or editor hook is the " +
+        "usual cause); the release would be rejected. dharta.toml was left untouched, so " +
+        "it still records whatever digest it had before this build.",
+    );
+  }
+
+  try {
+    await fs.writeFile(manifestPath, patched, "utf8");
+  } catch (error) {
+    // The bundle is on disk and dharta.toml still names the previous digest,
+    // so `check` reports a mismatch until the two agree. Nothing is lost: the
+    // build is a pure function of the sources, so a rerun produces the same
+    // bytes and records the same digest.
+    throw new GenuiError(
+      `Wrote ${relative}, but could not record its digest in ${manifestPath}: ` +
+        `${(error as Error).message}. The bundle is built and correct; only the manifest ` +
+        "is behind, so `dharta genui check` reports a digest mismatch until it is written. " +
+        "Fix the cause (a read-only file, a full disk), then run `dharta genui build` " +
+        "again - it rebuilds the same bytes, so repeating it is safe.",
+    );
+  }
+  return digest;
+}
+
+/**
+ * Every component directory under `sourceDir`, named by its path relative to
+ * it. A directory holding a `component.json` IS a component and is not
+ * descended into, so a namespaced name like `charts/Bar` (legal in the
+ * identifier both planes share) lives at `charts/Bar/component.json`.
+ *
+ * Unlike the bundle path these follow symlinks - the source layout is a CLI
+ * concern the data plane never sees, and `readdir`'s Dirent would report a
+ * symlinked component folder as a link rather than a directory and silently
+ * hide it.
+ */
+async function discoverComponents(sourceDir: string, label: string): Promise<string[]> {
+  const found: string[] = [];
+  const walk = async (absolute: string, relative: string): Promise<void> => {
+    let names: string[];
+    try {
+      names = await fs.readdir(absolute);
+    } catch {
+      if (relative !== "") return;
+      throw new GenuiError(
+        `[genui.build] source folder not found: ${label}. Create one directory per component ` +
+          `there (for example ${label}/Card/${COMPONENT_SPEC_FILE}), or set ` +
+          '`source = "<path>"` in [genui.build].',
+      );
+    }
+    for (const name of names.sort()) {
+      // Dot-directories are tooling, never components.
+      if (name.startsWith(".")) continue;
+      const child = path.join(absolute, name);
+      const stats = await fs.stat(child).catch(() => null);
+      if (!stats?.isDirectory()) continue;
+      const childRelative = relative === "" ? name : `${relative}/${name}`;
+      const isComponent = await fs
+        .stat(path.join(child, COMPONENT_SPEC_FILE))
+        .then((spec) => spec.isFile())
+        .catch(() => false);
+      if (isComponent) found.push(childRelative);
+      else await walk(child, childRelative);
+    }
+  };
+  await walk(sourceDir, "");
+  return found.sort();
+}
+
+// The manifest's `components` array is the builder's declaration of what this
+// release ships and at what trust tier. A build never edits it: a mismatch is a
+// question only the builder can answer, so name both sides and stop.
+async function requireExactMatch(
+  section: GenuiSection,
+  sourceDir: string,
+  found: string[],
+): Promise<void> {
+  const declared = new Set(section.components.map((c) => c.name));
+  const onDisk = new Set(found);
+  const missing = [...declared].filter((name) => !onDisk.has(name)).sort();
+  const extra = found.filter((name) => !declared.has(name));
+  if (missing.length === 0 && extra.length === 0) return;
+
+  // A component is DISCOVERED by its component.json, so a folder that exists
+  // but has no spec reads as "missing" here. Say the more useful thing.
+  for (const name of missing) {
+    const folder = componentDir(sourceDir, section.source, name);
+    const exists = await fs.stat(folder).then((st) => st.isDirectory()).catch(() => false);
+    if (exists) {
+      throw new GenuiError(
+        `[genui] component '${name}': ${section.source}/${name}/${COMPONENT_SPEC_FILE} is missing.`,
+      );
+    }
+  }
+
+  const lines = ["[genui] source folders do not match the components declared in dharta.toml."];
+  if (missing.length > 0) {
+    lines.push(`  Declared but missing from ${section.source}/: ${missing.join(", ")}`);
+  }
+  if (extra.length > 0) {
+    lines.push(`  Present in ${section.source}/ but not declared: ${extra.join(", ")}`);
+  }
+  lines.push(
+    "  Add the missing folders, or add/remove entries in the [genui] components array.",
+    "  `dharta genui build` never edits that array - the trust tier is your declaration.",
+  );
+  throw new GenuiError(lines.join("\n"));
+}
+
+interface ComponentSpec {
+  builtin?: string;
+  props_schema?: Record<string, unknown>;
+  events?: Record<string, unknown>;
+}
+
+// A component name is only ever a JSON string on the data plane, but the CLI
+// turns it into a path - and the identifier both planes share permits "." and
+// "/", so "a/../b" is a legal name. Resolve here, once, and refuse to climb out
+// of the source folder.
+function componentDir(sourceDir: string, label: string, name: string): string {
+  const parts = relativeParts(name);
+  if (name.startsWith("/") || parts.includes("..")) {
+    throw new GenuiError(
+      `[genui] component '${name}' cannot be a source path: it escapes ${label}/.`,
+    );
+  }
+  return path.join(sourceDir, ...parts);
+}
+
+async function compileComponent(
+  sourceDir: string,
+  label: string,
+  component: GenuiComponent,
+): Promise<Record<string, unknown>> {
+  const dir = componentDir(sourceDir, label, component.name);
+  const where = `${label}/${component.name}/${COMPONENT_SPEC_FILE}`;
+
+  let raw: string;
+  try {
+    raw = await fs.readFile(path.join(dir, COMPONENT_SPEC_FILE), "utf8");
+  } catch {
+    throw new GenuiError(`[genui] component '${component.name}': ${where} is missing.`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new GenuiError(
+      `[genui] component '${component.name}': ${where} is not valid JSON (${(error as Error).message}).`,
+    );
+  }
+  if (!plainObject(parsed)) {
+    throw new GenuiError(`[genui] component '${component.name}': ${where} must be a JSON object.`);
+  }
+  const unsafe = findUnsafeNumberLiteral(raw);
+  if (unsafe !== null) {
+    throw new GenuiError(
+      `[genui] component '${component.name}': ${where} has the number ${unsafe.literal} at ` +
+        `${unsafe.path}, which ` +
+        (unsafe.kind === "integer"
+          ? "is outside the range JavaScript represents exactly (up to " +
+            `${Number.MAX_SAFE_INTEGER}). The build would round it and ship a number you ` +
+            "never wrote, while the data plane keeps yours exactly."
+          : "overflows a JavaScript double to Infinity. The build would ship `null` where " +
+            "you wrote a number, while the data plane reads the same literal as a float " +
+            "and keeps it.") +
+        " Write it as a string, or use a number a double can hold.",
+    );
+  }
+  const unknownKeys = Object.keys(parsed).filter((key) => !SPEC_KEYS.includes(key));
+  if (unknownKeys.length > 0) {
+    throw new GenuiError(
+      `[genui] component '${component.name}': ${where} has unknown key(s) ` +
+        `${unknownKeys.join(", ")}. Supported: ${SPEC_KEYS.join(", ")}.`,
+    );
+  }
+  const tier = parsed.tier;
+  if (tier !== 1 && tier !== 2 && tier !== 3) {
+    throw new GenuiError(`[genui] component '${component.name}': ${where} needs tier 1, 2, or 3.`);
+  }
+  if (tier !== component.tier) {
+    throw new GenuiError(
+      `[genui] component '${component.name}': ${where} declares tier ${tier} but ` +
+        `dharta.toml declares tier ${component.tier}. The manifest is the trust declaration; ` +
+        "make them agree.",
+    );
+  }
+  if (parsed.builtin !== undefined && typeof parsed.builtin !== "string") {
+    throw new GenuiError(
+      `[genui] component '${component.name}': ${where} builtin must be a string.`,
+    );
+  }
+  for (const key of ["props_schema", "events"] as const) {
+    if (parsed[key] !== undefined && !plainObject(parsed[key])) {
+      throw new GenuiError(
+        `[genui] component '${component.name}': ${where} ${key} must be an object.`,
+      );
+    }
+  }
+  const spec: ComponentSpec = {
+    builtin: parsed.builtin as string | undefined,
+    props_schema: parsed.props_schema as Record<string, unknown> | undefined,
+    events: parsed.events as Record<string, unknown> | undefined,
+  };
+
+  const out: Record<string, unknown> = { name: component.name, tier: component.tier };
+  if (spec.props_schema !== undefined) out.props_schema = spec.props_schema;
+  if (spec.events !== undefined) out.events = spec.events;
+  out.implementation = await readImplementation(dir, label, component, spec);
+  return out;
+}
+
+async function readImplementation(
+  dir: string,
+  label: string,
+  component: GenuiComponent,
+  spec: ComponentSpec,
+): Promise<Record<string, unknown>> {
+  if (component.tier === 1) {
+    // A Tier-1 component is an alias for a Dharta builtin; the common case is
+    // that the folder is named after the builtin it aliases.
+    return { builtin: spec.builtin ?? component.name };
+  }
+  if (spec.builtin !== undefined) {
+    throw new GenuiError(
+      `[genui] component '${component.name}': builtin is Tier-1 only; ` +
+        `a Tier-${component.tier} component ships its own source.`,
+    );
+  }
+  const file = component.tier === 2 ? TIER2_SOURCE_FILE : TIER3_SOURCE_FILE;
+  const field = component.tier === 2 ? "worker" : "html";
+  const where = `${label}/${component.name}/${file}`;
+  let bytes: Buffer;
+  try {
+    bytes = await fs.readFile(path.join(dir, file));
+  } catch {
+    throw new GenuiError(
+      `[genui] component '${component.name}' is tier ${component.tier}, so it needs ${where}.`,
+    );
+  }
+  // The bundle is UTF-8 JSON. Decoding leniently would replace an invalid byte
+  // with U+FFFD and ship a silently corrupted worker or document.
+  return {
+    [field]: decodeUtf8(
+      bytes,
+      `[genui] component '${component.name}': ${where} is not valid UTF-8.`,
+    ),
+  };
+}