@unoverse-platform/studio 0.1.90 → 0.1.92

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;
+}

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

@@ -0,0 +1,246 @@
+/**
+ * Reading a developer's project off disk into publishable items.
+ *
+ * One item per thing a universe can hold: a component, an atom, a style set, a node, a
+ * skill, a prompt block. Each carries its content and a fingerprint, and nothing else is
+ * decided here: WHO published it and WHERE it came from are set by the server from the
+ * authenticated caller, never from this payload (publishRoute.ts).
+ *
+ * THE MARKETPLACE IS NEVER COLLECTED. `rx/marketplace` is the design system, installed
+ * from `@unoverse-platform/marketplace`, and a developer builds ON it rather than owning
+ * it. In a developer's project the folder does not even exist; in THIS monorepo it does,
+ * and publishing from here would push the design system source into a universe that is
+ * supposed to receive it as a package. Same exclusion the linter already applies when it
+ * computes org dirs, for the same reason.
+ *
+ * The unit is a PROJECT, not a file and not all of rx/. A project is what a developer
+ * works in and what they can reason about publishing; per-file selection is a chore nobody
+ * performs correctly, and a half-published project is worse than either extreme.
+ */
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join, relative, basename } from "node:path";
+import { fingerprintOf } from "./fingerprint.js";
+import { parse as parseYaml } from "yaml";
+import { readDiskPackages } from "../manifests/source.js";
+
+/** One publishable thing: what it is, what it contains, and what it was built on. */
+export interface CollectedItem {
+  kind: string;
+  name: string;
+  /** The files as authored. A node row also carries its package envelope and folder name. */
+  definition: { files: Record<string, string>; package?: Record<string, unknown>; dir?: string };
+  fingerprint: string;
+  org: string;
+  base_version: string;
+}
+import { designSystemVersion } from "./baseVersion.js";
+
+/** Folders under rx/ that are never a developer's own project. */
+const NOT_A_PROJECT = new Set(["marketplace", "_schema", "orgs"]);
+
+const isDef = (f: string) => f.endsWith(".yaml") || f.endsWith(".json");
+
+/**
+ * Where the design system is, mirroring definitions.ts marketplaceDir(). In this monorepo
+ * it is source on disk; in a developer's project it is the installed bundle, because
+ * sync-starter.sh deliberately ships neither the source nor a way to publish it.
+ */
+function designSystemDir(designRoot: string): string {
+  const onDisk = join(designRoot, "marketplace");
+  if (existsSync(onDisk)) return onDisk;
+  const nodesHome = join(designRoot, "..", "nodes");
+  for (const c of [
+    join(nodesHome, "marketplace", "definitions"),
+    join(designRoot, "..", "plugins", "node_modules", "@unoverse-platform", "marketplace", "definitions"),
+  ])
+    if (existsSync(c)) return c;
+  return onDisk; // nothing found: the version will hash to an empty set, which is honest
+}
+
+/** Every project a developer could publish, by name. */
+export function listProjects(designRoot: string): string[] {
+  if (!existsSync(designRoot)) return [];
+  return readdirSync(designRoot)
+    .filter((e) => !e.startsWith(".") && !NOT_A_PROJECT.has(e))
+    .filter((e) => statSync(join(designRoot, e)).isDirectory())
+    .sort();
+}
+
+/** Every definition file under a folder, relative-pathed, as one object. */
+function filesUnder(dir: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!existsSync(dir)) return out;
+  const walk = (d: string): void => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      if (e.name.startsWith(".")) continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (isDef(e.name) || e.name.endsWith(".md")) out[relative(dir, p)] = readFileSync(p, "utf8");
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+/**
+ * Collect one project into items.
+ *
+ * A component is a FOLDER (its envelope, layouts, states, sub-partials), so the item's
+ * definition is every file in it keyed by relative path. That mirrors how a node row is
+ * already stored (`{ files: {...} }`, manifests/source.ts rowsSource), so both kinds read
+ * back the same way.
+ */
+export function collectProject(designRoot: string, project: string): CollectedItem[] {
+  const root = join(designRoot, project);
+  if (!existsSync(root)) throw new Error(`No project "${project}" in ${designRoot}`);
+
+  // WHAT THIS WAS BUILT ON, stamped on every item. Computed once per collection: it is the
+  // same design system for the whole project, and hashing it per item would be wasteful and
+  // could disagree with itself mid-run if a file changed.
+  const base_version = designSystemVersion(designSystemDir(designRoot));
+
+  const items: CollectedItem[] = [];
+  // A COMPONENT (and, since 2026-08-24, a SKILL) row's name is the qualified ref
+  // (`<org>/<name>`): the items table's identity is (kind, name) with no org in the
+  // key, and both names are unique only WITHIN an org — two orgs may ship
+  // `course-card` or `hr-education-coach`, so the org must be in the name for the
+  // rows to coexist (the same trick a style row already uses: its name IS the org).
+  // A prompt block is NEVER qualified this way — see the blocks/ walk below for why.
+  // Apps keep their bare ids: those are org-qualified by convention
+  // (`<org>-chat`). docs/unoverse/UNOVERSE_COMPONENT_ORGS.md.
+  const QUALIFIED_KINDS = new Set(["component", "skill", "template"]);
+  const add = (kind: string, name: string, definition: CollectedItem["definition"]) =>
+    items.push({
+      kind,
+      name: QUALIFIED_KINDS.has(kind) ? `${project}/${name}` : name,
+      definition,
+      fingerprint: fingerprintOf(definition),
+      org: project,
+      base_version,
+    });
+
+  // `apps` publishes as kind `app`, NOT `recipe`. A recipe is a workflow graph
+  // that is copied onto a canvas and never installed; an app is installed and tracked, so
+  // taking a newer version is the point rather than a hazard (migrations 017 + 029).
+  //
+  // A DEFINITION IS EITHER A FOLDER OR A SINGLE FILE, and both are normal. A component
+  // that grew layouts and states is a folder; an atom is one file, and templates are a
+  // mix. Collecting only folders silently dropped all 24 atoms and two templates, which
+  // is the worst kind of bug in a publisher: it succeeds and ships less than you authored.
+  //
+  // Both become the same shape, a map of relative path to contents, so nothing downstream
+  // has to care which it was. A single file is simply a map with one entry.
+  // APP MEANS APP, TEMPLATE MEANS TEMPLATE (owner ruling 2026-08-28, migration
+  // 029): apps publish as kind `app` and the Template Model kind owns the bare
+  // word. Forgetting a design dir here ships deploys that silently drop every
+  // artifact of that kind.
+  for (const [dir, kind] of [["components", "component"], ["apps", "app"], ["templates", "template"], ["atoms", "atom"]] as const) {
+    const home = join(root, dir);
+    if (!existsSync(home)) continue;
+    for (const e of readdirSync(home, { withFileTypes: true })) {
+      if (e.name.startsWith(".") || e.name === "README.md") continue;
+      if (e.isDirectory()) {
+        const files = filesUnder(join(home, e.name));
+        if (Object.keys(files).length) add(kind, e.name, { files });
+      } else if (isDef(e.name)) {
+        // The name is the definition's, without the extension: `card.yaml` is `card`,
+        // addressed the same way whether it later grows into a folder.
+        add(kind, e.name.replace(/\.(ya?ml|json)$/, ""), { files: { [e.name]: readFileSync(join(home, e.name), "utf8") } });
+      }
+    }
+  }
+
+  // styles/ is ONE item: the org's token overrides, which only mean anything together.
+  const styles = filesUnder(join(root, "styles"));
+  if (Object.keys(styles).length) add("style", project, { files: styles });
+
+  // skills/ — ORG-QUALIFIED, same trick as a component: `${project}/${name}` is the
+  // identity, so two orgs may each ship "hr-education-coach" without one silently
+  // taking the other's row (items/loaders.ts loadParsedSkill resolves the qualified
+  // form back to this same folder). One item per skill folder, same shape as a
+  // component: SKILL.md plus any references/ it carries.
+  const skillsHome = join(root, "skills");
+  if (existsSync(skillsHome)) {
+    for (const e of readdirSync(skillsHome, { withFileTypes: true })) {
+      if (!e.isDirectory() || e.name.startsWith(".")) continue;
+      if (!existsSync(join(skillsHome, e.name, "SKILL.md"))) continue; // not a skill folder
+      const files = filesUnder(join(skillsHome, e.name));
+      if (Object.keys(files).length) add("skill", e.name, { files });
+    }
+  }
+
+  // blocks/ — NAME STAYS BARE, unlike a skill. A block is referenced inline in authored
+  // component text as `{{prompt.name}}` (packages'/engine's template resolver), a single
+  // FLAT name across the whole platform with no room for an org segment. Org-qualifying
+  // it would break every existing `{{prompt.X}}` reference, so only where the block
+  // lives moves; what it is called does not. Two orgs shipping the same block name still
+  // collide at the row (last publish wins) — an accepted limit, not solved here.
+  const blocksHome = join(root, "blocks");
+  if (existsSync(blocksHome)) {
+    const walk = (d: string): void => {
+      for (const e of readdirSync(d, { withFileTypes: true })) {
+        if (e.name.startsWith(".")) continue;
+        const p = join(d, e.name);
+        if (e.isDirectory()) walk(p);
+        else if (e.name.endsWith(".md")) {
+          const definition = { files: { [relative(blocksHome, p)]: readFileSync(p, "utf8") } };
+          items.push({
+            kind: "prompt-block",
+            name: basename(e.name, ".md"),
+            definition,
+            fingerprint: fingerprintOf(definition),
+            org: project,
+            base_version,
+          });
+        }
+      }
+    };
+    walk(blocksHome);
+  }
+
+  // nodes/ — THE WORKSPACE'S NODE PACKAGES, one row per node, shaped exactly as the
+  // marketplace stores a node (core/items/catalogue.ts) so the row source composes them
+  // on the same path as disk: the raw files, plus the package envelope their $refs and
+  // credential shapes resolve against. The name is the node's `type`, bare: a saved
+  // workflow stores that identity and nothing else.
+  //
+  // Until 2026-09-05 deploy never looked here, so `deploy studio` shipped a developer's
+  // components and skills and silently left every node behind.
+  //
+  // NOT FROM THE PLATFORM TREE. The monorepo's nodes ship inside the core image and are
+  // read from disk there; publishing them as rows under whichever org happened to be
+  // deployed would double every platform node. A design system on disk is the mark of
+  // the platform tree (the same test designSystemDir makes), and a developer's workspace
+  // never has one.
+  const nodesHome = join(designRoot, "..", "nodes");
+  if (existsSync(nodesHome) && !existsSync(join(designRoot, "marketplace"))) {
+    for (const pkg of collectNodePackages(nodesHome)) {
+      for (const raw of pkg.nodes) {
+        const type = nodeType(raw.files["node.yaml"]);
+        if (!type) continue; // lint has already refused it; nothing to name a row by
+        add("node", type, {
+          package: { name: pkg.name, packageFile: pkg.packageFile ?? null, credentials: pkg.credentials, shared: pkg.shared },
+          dir: raw.dir,
+          files: raw.files,
+        });
+      }
+    }
+  }
+
+  return items;
+}
+
+/** The workspace's node packages, read the way the platform reads its own. */
+function collectNodePackages(nodesHome: string) {
+  return readDiskPackages(nodesHome).filter((pkg) => pkg.name !== "marketplace");
+}
+
+/** `type:` off a node.yaml: the one scalar the row is named by. Unparseable means none. */
+function nodeType(nodeYaml: string | undefined): string {
+  try {
+    const doc = parseYaml(nodeYaml ?? "");
+    return typeof doc?.type === "string" ? doc.type : "";
+  } catch {
+    return "";
+  }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * The content fingerprint of an item.
+ *
+ * ONE implementation, because two would decide differently and nobody would notice. The
+ * publisher computes it before sending; the universe compares it against the row it holds
+ * to decide installed / update / unchanged. A second copy that canonicalises keys in a
+ * different order makes every publish look like a change, and every unchanged item look
+ * stale, which is the kind of wrong that erodes trust in the whole marketplace view.
+ *
+ * KEY ORDER IS NOT CONTENT. Objects are serialised with sorted keys, so re-saving a
+ * definition through a different YAML writer does not read as an edit. That property is
+ * load-bearing: converting rx/ from JSON to YAML rewrote 242 files and must have altered
+ * nothing a universe consumes (013_items.sql).
+ *
+ * Truncated to 16 hex characters. This identifies content, it does not defend against a
+ * forged one: integrity is the node content hash (manifests/integrity.ts), and authority
+ * is the publish gate.
+ */
+import { createHash } from "crypto";
+
+/** Deterministic JSON: sorted keys, arrays in order, primitives as JSON. */
+function canonical(v: unknown): string {
+  if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
+  if (Array.isArray(v)) return `[${v.map(canonical).join(",")}]`;
+  const o = v as Record<string, unknown>;
+  return `{${Object.keys(o)
+    .sort()
+    .map((k) => `${JSON.stringify(k)}:${canonical(o[k])}`)
+    .join(",")}}`;
+}
+
+export function fingerprintOf(definition: unknown): string {
+  return createHash("sha256").update(canonical(definition)).digest("hex").slice(0, 16);
+}

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

@@ -0,0 +1,212 @@
+/**
+ * Publishing a project: collect, lint, compare, send.
+ *
+ * The shape is deliberate. NOTHING LEAVES THE MACHINE until the rules pass, because the
+ * cheapest place to catch a malformed definition is where the developer can fix it. The
+ * universe validates again on receipt (it must not trust a client), but a developer should
+ * never learn about a raw hex value from an HTTP error.
+ *
+ * Then a COMPARISON before a write. "What am I about to do" is answered by fingerprints:
+ * new, changed, unchanged, or refused because the name belongs to someone else. Publishing
+ * blind is how a project half-lands and nobody can tell by looking.
+ *
+ * See docs/architecture/DECLARATIVE_NODES.md §9.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { collectProject, type CollectedItem } from "./collect.js";
+
+/** One lint finding. `error` blocks a publish; `warn` and `hint` inform. */
+export interface Finding {
+  level: string;
+  file: string;
+  line?: number;
+  msg: string;
+}
+
+/** What publishing WOULD do, per item. `refused` carries the reason. */
+export interface PublishPlan {
+  create: CollectedItem[];
+  update: CollectedItem[];
+  unchanged: CollectedItem[];
+  refused: Array<CollectedItem & { why: string }>;
+  /** Rows the universe holds for this project that the workspace no longer does. */
+  remove: Array<{ kind: string; name: string }>;
+  /** True when the universe could not answer the sync check (server predates it):
+   *  removals were NOT reconciled and "up to date" must not be claimed. */
+  syncUnavailable?: boolean;
+}
+
+/**
+ * Lint a project, returning findings. Errors mean nothing is sent.
+ *
+ * The design linter needs the whole design home, not one project: a developer's components are
+ * built ON TOP of the design system, so linting a project in isolation resolves every
+ * shared atom against nothing. It reports on all projects; we keep the findings for this
+ * one, plus anything about the tree itself.
+ */
+export async function lintForPublish(designRoot: string, project: string): Promise<{ problems: Finding[]; errors: Finding[] }> {
+  const { lintDefinitions } = await import("../lint/design/index.mjs");
+  const result = lintDefinitions(designRoot);
+  /**
+   * NODES TOO. A workspace keeps its node packages beside design/ (the same `nodes/` the
+   * Studio Nodes screen reads), and until 2026-09-05 this gate never looked at them: a
+   * node with an events row out of order or a host missing from allowedHosts deployed as
+   * cleanly as a correct one. The node linter is the same library the platform's own CI
+   * runs. A workspace with no nodes/ folder has nothing to lint and is not an error.
+   */
+  const nodesHome = join(designRoot, "..", "nodes");
+  if (existsSync(nodesHome)) {
+    const { lintNodes } = await import("../lint/nodes/index.mjs");
+    result.problems.push(...lintNodes(nodesHome).problems);
+  }
+  /**
+   * SCOPED TO THE PROJECT BEING DEPLOYED, on paths that may be relative. The old
+   * check looked for "/design/" with a leading slash, which a relative path never
+   * has, so every other project's findings leaked through and a bpp comment blocked
+   * a lyceum deploy (observed live 2026-08-21). Boundary regexes hold for absolute
+   * and relative paths alike; findings outside the design tree (the tree itself,
+   * nodes, prompts) still always count.
+   */
+  const inDesign = (f: string) => /(^|\/)design\//.test(f);
+  const inProject = (f: string) => new RegExp(`(^|/)design/${project}(/|$)`).test(f);
+  const mine = result.problems.filter((p: Finding) => !p.file || !inDesign(p.file) || inProject(p.file));
+  return { problems: mine, errors: mine.filter((p: Finding) => p.level === "error") };
+}
+
+/**
+ * What publishing WOULD do, without doing it.
+ *
+ * Compares each collected item against the universe's current fingerprint for the same
+ * (kind, name). Four outcomes, and the fourth is the one worth surfacing early: a name
+ * owned by another publisher is refused, and finding that out before a publish beats
+ * finding it out halfway through one.
+ */
+export async function planPublish(
+  items: CollectedItem[],
+  universe: string,
+  token: string,
+  /** The project being deployed; names the org whose universe rows the sync reconciles. */
+  project = "",
+  fetchImpl: typeof fetch = fetch,
+): Promise<PublishPlan> {
+  const plan: PublishPlan = { create: [], update: [], unchanged: [], refused: [], remove: [] };
+
+  /**
+   * DEPLOY IS A SYNC (ruled 2026-08-21): what the workspace no longer holds, the
+   * universe should not keep serving under this project's name. The universe lists its
+   * rows for the project; anything absent from the collected items joins the plan as a
+   * removal, shown and confirmed like everything else.
+   *
+   * ONE GUARD, against the catastrophic misread: a workspace that holds NO items for
+   * the project (a fresh clone missing its files, the wrong folder entirely) does not
+   * get to empty the universe. Removals are proposed only when the workspace holds at
+   * least one item — deleting the last one is done by name, deliberately.
+   *
+   * AND A SECOND GUARD, ON KINDS. Absence only means "deleted" for a kind this
+   * collector actually LOOKED for. A CLI that predates a kind collects none of it, sees
+   * rows it cannot account for, and proposes deleting every one — which is exactly what
+   * happened live on 2026-08-24: an older global `unoverse` removed all three freshly
+   * published skill and prompt-block rows, because its collector had never heard of
+   * them. Version skew between a machine's CLI and its universe is normal and must not
+   * be destructive, so a kind that contributed NOTHING to this collection is left
+   * entirely alone. Deleting the last item OF A KIND is therefore done by name, the
+   * same deliberate act as emptying a project.
+   */
+  if (project && items.length > 0) {
+    try {
+      const res = await fetchImpl(`${universe}/publish`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body: JSON.stringify({ op: "list", project }),
+      });
+      if (res.ok) {
+        const doc = (await res.json().catch(() => null)) as { items?: Array<{ kind: string; name: string }> } | null;
+        const have = new Set(items.map((i) => `${i.kind}/${i.name}`));
+        const collectedKinds = new Set(items.map((i) => i.kind));
+        for (const r of doc?.items ?? []) {
+          if (!collectedKinds.has(r.kind)) continue; // this collector never looked for it
+          if (!have.has(`${r.kind}/${r.name}`)) plan.remove.push(r);
+        }
+      } else {
+        // An older universe answers this op with an error: no removals proposed, the
+        // additive behavior every deploy had before — but SAID, never silent. A deploy
+        // that could not check deletions and prints "up to date" is lying by omission
+        // (observed live 2026-08-21: an hour of retests against a server that could
+        // not answer, each one claiming there was nothing to do).
+        plan.syncUnavailable = true;
+      }
+    } catch {
+      plan.syncUnavailable = true; /* unreachable universe also fails later, on the real sends */
+    }
+  }
+
+  for (const item of items) {
+    // ASK THE GATE, not the item store. `/api/items` is deliberately shut (§9.10), so a
+    // publisher cannot read rows directly; and asking the publish route means the plan is
+    // produced by exactly the code that will act on it.
+    let verdict: any;
+    try {
+      const res = await fetchImpl(`${universe}/publish`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body: JSON.stringify({ ...item, dryRun: true }),
+      });
+      verdict = await res.json().catch(() => ({}));
+      if (res.status === 409) {
+        plan.refused.push({ ...item, why: verdict?.error ?? "refused" });
+        continue;
+      }
+      if (!res.ok) throw new Error(verdict?.error ?? `HTTP ${res.status}`);
+    } catch (e: any) {
+      throw new Error(`Could not reach ${universe}. ${e?.message ?? ""}`.trim());
+    }
+
+    if (verdict.unchanged) plan.unchanged.push(item);
+    else if (verdict.mode === "update") plan.update.push(item);
+    else plan.create.push(item);
+  }
+
+  return plan;
+}
+
+/**
+ * Send what the plan says to send. Unchanged items are skipped rather than written: a
+ * redeploy of something nobody edited must not read as a change to anyone reviewing.
+ */
+export async function sendPublish(
+  plan: PublishPlan,
+  universe: string,
+  token: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ sent: Array<CollectedItem & { mode?: string }>; failed: Array<CollectedItem & { why: string }> }> {
+  const sent: Array<CollectedItem & { mode?: string }> = [];
+  const failed: Array<CollectedItem & { why: string }> = [];
+
+  for (const item of [...plan.create, ...plan.update]) {
+    const res = await fetchImpl(`${universe}/publish`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify(item),
+    });
+    const body = (await res.json().catch(() => ({}))) as { mode?: string; error?: string };
+    if (res.ok) sent.push({ ...item, mode: body.mode });
+    // The server's refusal message is written to be read; do not paraphrase it.
+    else failed.push({ ...item, why: body.error ?? `HTTP ${res.status}` });
+  }
+  // Removals LAST, after the writes landed: a sync that dies mid-run has then added
+  // before it has taken away, which is the recoverable order.
+  for (const r of plan.remove ?? []) {
+    const res = await fetchImpl(`${universe}/publish`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify({ op: "remove", kind: r.kind, name: r.name }),
+    });
+    const body = (await res.json().catch(() => ({}))) as { error?: string };
+    if (res.ok) sent.push({ ...(r as CollectedItem), mode: "removed" });
+    else failed.push({ ...(r as CollectedItem), why: body.error ?? `HTTP ${res.status}` });
+  }
+  return { sent, failed };
+}
+
+export { collectProject };

package/vendor/base/src/lint/context.mjs

@@ -0,0 +1,56 @@
+/**
+ * The state one lint run accumulates, and the only thing every rule module shares.
+ *
+ * It is MUTABLE and RESET per run, deliberately. The linter began as a CLI that ran once
+ * and exited, so module-level arrays were harmless; Studio and the publish route lint over
+ * and over in one process, and findings from the previous run would silently accumulate
+ * into the next. `reset()` is what makes a second call return the same answer as the first.
+ */
+import { relative } from "node:path";
+
+/** Every finding, in discovery order. Sorted for presentation by the caller. */
+export const problems = [];
+
+/** Fragment path -> the set of nodes referencing it. Powers the shared/ pruning rules. */
+export const refCounts = new Map();
+
+/** Node -> the executor kind derived for it, shown as a summary rather than a finding. */
+export const derivedKinds = new Map();
+
+/** Credential name -> where it was declared, for cross-package collision rules. */
+export const allCredentials = new Map();
+
+/** Where this run is reading. Set by lintNodes(), read by rel() and the loaders. */
+export const state = { nodesHome: "", schemaDir: "", schemas: {} };
+
+export function reset(nodesHome, schemaDir) {
+  problems.length = 0;
+  seen.clear();
+  refCounts.clear();
+  derivedKinds.clear();
+  allCredentials.clear();
+  state.nodesHome = nodesHome;
+  state.schemaDir = schemaDir;
+  state.schemas = {};
+}
+
+/**
+ * One finding. `error` fails a build; `warn` and `hint` inform.
+ *
+ * DEDUPED. The design linter walks a definition and its expansions, so the same rule can fire
+ * on the same line twice; a caller seeing it twice would think there were two problems.
+ * `line` is optional: the design linter knows where in the file, the node linter reports per file.
+ */
+const seen = new Set();
+export const report = (level, file, msg, line) => {
+  const key = `${level}|${file}|${line ?? ""}|${msg}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+  problems.push(line === undefined ? { level, file, msg } : { level, file, msg, line });
+};
+
+/** Shortest readable form: a walk out of the tree is worse than the absolute path. */
+export const rel = (p) => {
+  const r = relative(process.cwd(), p);
+  return r.startsWith("..") ? p : r;
+};