@unoverse-platform/studio 0.1.90 → 0.1.92

package/vendor/base/src/manifests/executor/toolBridge.ts

@@ -0,0 +1,266 @@
+/**
+ * Build the tool bridge from the platform's own harness.
+ *
+ * Every MCP judgement lives in ../../agent-mcp and is reached from here: what a
+ * tool is, what a discovery result unlocks, when a turn ends, how much of a result the
+ * model needs. The loop only owns the wire format. That split is what stops each agent
+ * family re-making these decisions and drifting apart, which is how GLM and Grok ended
+ * up unable to launch spatial apps.
+ *
+ * Returns undefined when nothing granted tools, and the node then runs as a single request.
+ */
+import type { ToolBridge } from "../runtime/index.js";
+
+export async function toolBridgeFor(executionContext: any): Promise<ToolBridge | undefined> {
+  const api = executionContext?.api;
+  if (!api?.callService) return undefined;
+
+  const harness: any = await import("../../agent-mcp/index.js");
+
+  let schema: any;
+  try {
+    schema = await api.callService("getSchema", {}, executionContext);
+  } catch {
+    return undefined; // no MCP provider wired
+  }
+  if (!schema?.methods) return undefined;
+
+  const core = new Set<string>(Object.keys(schema.methods));
+
+  // Identity for a HELD app call: it renders on the caller's live session and elicits
+  // from that human, so it needs the conversation, the turn, and the caller's token.
+  // Using auth HERE is correct and different from exposing it to a manifest: this is the
+  // platform calling its own internal /mcp on the user's behalf, not data deciding where
+  // a secret goes.
+  const pub = executionContext?.publishingContext;
+  const identity = {
+    conversationId: pub?.conversationId,
+    userId: pub?.userId,
+    chatId: pub?.chatId,
+    accessToken: executionContext?.auth?.accessToken,
+  };
+
+  /**
+   * Discovered PATH-B component apps, by tool name.
+   *
+   * These are NOT ordinary service calls. UNOVERSE_MCP_APP_PROTOCOL §3.3/§4b: a
+   * bindingless component app is invoked through the held `/mcp` call so the server
+   * renders it, elicits from the user, and returns their answers AND the
+   * post-elicitation guidance to the model. Routing one through callService instead
+   * would silently drop elicitation — the app would render and the model would never
+   * learn what the human said.
+   */
+  const appInvokers = new Map<string, (input: unknown) => Promise<unknown>>();
+
+  /**
+   * Which apps this run has already unlocked, by component name.
+   *
+   * The harness keys the shell-open off this set: an app opens its page ONCE per run, and a
+   * later search that surfaces the same row again must not fire a second skeleton over a page
+   * the guest is already reading. Owned per bridge, so two agents in one workflow do not
+   * share each other's unlocks.
+   */
+  const discoveredApps = new Set<string>();
+
+  /**
+   * THE GUEST'S OWN WORDS, from the search that is about to unlock a page.
+   *
+   * A page's `query:` places ask half a sentence each (§9e rule 4) — the half true of every
+   * guest — and the platform joins the half that is different for each. This is where that
+   * half is picked up: the model wrote the guest's ask into its search args a moment ago, so
+   * nothing has to be re-derived or, worse, re-invented.
+   *
+   * Captured on the CALL and read on the ABSORB, because `absorb` receives only the result.
+   * Whoever knows the situation supplies it (§9d) — the shell-open passes it on rather than
+   * the server guessing what the conversation was about.
+   */
+  let lastAsk = "";
+
+  const stringify = (r: unknown): string => (typeof r === "string" ? r : JSON.stringify(r));
+
+  /**
+   * PAGES ALREADY OPEN IN THIS CONVERSATION (the latch's other half, 2026-09-02).
+   *
+   * A follow-up send addressed at an open page starts a FRESH agent, and the page's tool
+   * was minted in an earlier run and died with it — so the agent could only chat at the
+   * page (observed live: three consecutive turns of clarifying questions at a latched
+   * page it had no tool to edit). At bridge build the open pages are read from the
+   * server's open-apps resource and their tools minted exactly like an unlock mint,
+   * minus the shell-open — the page is already on screen. The same resource read RE-ARMS
+   * read-first server-side, so this new agent's first authored call is answered with the
+   * current page rather than rendered blind. Fail-soft: any error means nothing
+   * pre-minted, which is exactly the old behaviour.
+   */
+  const preMinted: any[] = [];
+  if (identity.conversationId) {
+    try {
+      const { client, close } = await harness.connectPlatformMcp({ accessToken: identity.accessToken });
+      try {
+        const res = (await client.readResource({ uri: `unoverse://conversations/${identity.conversationId}/open-apps` })) as {
+          contents?: Array<{ text?: string }>;
+        };
+        const open = JSON.parse(res?.contents?.[0]?.text ?? "[]") as Array<{ methodName: string; appUri: string; title?: string; description?: string }>;
+        for (const o of open) {
+          if (!o?.methodName || !o?.appUri) continue;
+          const mcp = {
+            id: o.appUri,
+            title: o.title ?? "",
+            description: `${o.description || o.title || o.methodName} ${harness.APP_ETIQUETTE}`,
+            workflowId: "",
+            nodeId: "",
+            methodName: o.methodName,
+            component: harness.componentTypeFromAppUri(o.appUri),
+            appUri: o.appUri,
+            schema: { methods: {} },
+          };
+          const def = await harness.resolveToolDefNative(mcp, { accessToken: identity.accessToken });
+          appInvokers.set(def.name, harness.componentAppInvoker(mcp, identity));
+          discoveredApps.add(mcp.component);
+          preMinted.push({
+            ...def,
+            description:
+              `${def.description}\n\nTHIS PAGE IS ALREADY OPEN in this conversation — the user is looking at it now. ` +
+              `To act on their message, call this tool with the parts to change; your first call is answered with the current page so you read before editing.`,
+          });
+          console.log(`[manifests] open page re-minted for this turn: ${def.name}`);
+        }
+      } finally {
+        await close();
+      }
+    } catch {
+      /* no open pages, or a server without the resource — nothing pre-minted */
+    }
+  }
+
+  return {
+    async discover() {
+      return [
+        ...Object.entries<any>(schema.methods).map(([name, m]) => ({
+          name,
+          description: m.description || `Execute ${name}`,
+          parameters: m.input || { type: "object", properties: {} },
+        })),
+        ...preMinted,
+      ];
+    },
+
+    async call(name, args) {
+      const app = appInvokers.get(name);
+      if (app) return stringify(await app(args));
+      if (harness.DISCOVERY_TOOL_NAMES.includes(name)) {
+        const a = (args ?? {}) as Record<string, unknown>;
+        const q = typeof a.query === "string" ? a.query : Array.isArray(a.queries) ? String(a.queries[0] ?? "") : "";
+        if (q.trim()) lastAsk = q.trim();
+      }
+      // THE ARGUMENTS GO OUT AS THE MODEL WROTE THEM. A wire-level rewrite used to strip
+      // queries the conversation had already searched; it was removed 2026-08-16 because it
+      // silently competed with the tool descriptions for the same decision, and the
+      // descriptions are where it belongs. What a turn should search, and whether that turn
+      // wants app cards, is the MCP prompt's call — see shared/schema.yaml.
+      return stringify(await api.callService(name, args, executionContext));
+    },
+
+    /**
+     * THE HARNESS'S OWN ABSORBER, called once — which is what every legacy agent did
+     * (`runOpenAIAgent.ts:580`) and what this bridge stopped doing.
+     *
+     * It was re-implemented here as two halves, a mint and a lean, and the step BETWEEN them
+     * was simply absent: the shell-open. `handleDiscoveryResult` says so at the top of itself
+     * — "never re-implemented in an adapter" — and the reason is this exact failure. Nothing
+     * errored. The tool was minted, the model answered, and the page never appeared until the
+     * model composed it, with none of the `__draftRefs` that let the server paint the hero
+     * and galleries from the rows the search had already returned.
+     *
+     * `onAppUnlocked` is where the mint goes now: the harness decides WHEN an app is newly
+     * unlocked, and this decides what a tool looks like to the model. Awaited, so the tool is
+     * registered before the model's next turn reads it.
+     */
+    async absorb(toolName, resultContent) {
+      const minted: any[] = [];
+      const content = await harness.handleDiscoveryResult(
+        toolName,
+        resultContent,
+        discoveredApps,
+        identity,
+        (m: string) => console.log(`[manifests] ${m}`),
+        async (mcp: any) => {
+          // The app's input schema is read LIVE from its URI at mint time; spatial rows
+          // carry no schema copy. For a BRIEFED component that schema is the instruction
+          // channel, so the model hydrates real fields instead of following prose.
+          const def = await harness.resolveToolDefNative(mcp, { accessToken: identity.accessToken });
+          const invoke = harness.componentAppInvoker(mcp, identity);
+          appInvokers.set(def.name, invoke);
+
+          /**
+           * THE PAGE FILLS BEFORE THE WRITER GETS THE PEN (owner ruling 2026-09-01 night).
+           *
+           * The shell-open renders the page skeleton and runs the page's OWN fill — its
+           * searches, the director's picks, the tiles (§9e). It used to be fire-and-forget
+           * while the tool was minted immediately, so the model composed captions for a page
+           * it had never seen; a read-first bounce tried to repair that and depended on the
+           * model re-sending, which it sometimes simply did not (observed 15:45: bounce, no
+           * resend, ghost headings shipped). So the ORDER is now physical: the shell call is
+           * AWAITED, and only then is the tool minted — with the page's chosen places in the
+           * tool's own description. The writer cannot write blind, and nothing needs bouncing.
+           *
+           * The guest loses nothing: the skeleton and the tiles render during this await; only
+           * the model's captions start those few seconds later. A failed shell mints the tool
+           * with its plain description — a page that arrives the old way, never a dead turn.
+           *
+           * `__draftRefs` carries the UNLOCKING SEARCH'S ranked row ids (the server drafts
+           * ref-only parts from them); the execution ids trace the page's searches into the
+           * run's own timeline.
+           */
+          const draftRefs = harness.rankedRowIds(resultContent);
+          let chosenNote = "";
+          try {
+            const opened = await invoke({
+              __draftRefs: draftRefs,
+              ...(lastAsk ? { __ask: lastAsk } : {}),
+              ...(executionContext?.workflowId ? { __workflowId: executionContext.workflowId } : {}),
+              ...(executionContext?.executionId ? { __executionId: executionContext.executionId } : {}),
+              ...(executionContext?.nodeId ? { __nodeId: executionContext.nodeId } : {}),
+            });
+            const msg = typeof (opened as { message?: unknown })?.message === "string" ? (opened as { message: string }).message : "";
+            const chosen = msg.match(/THE PAGE'S CONTENT IS ALREADY CHOSEN — [^\n]*?never a different plan\./)?.[0];
+            if (chosen) chosenNote = `\n\n${chosen}`;
+            console.log(`[manifests] shell opened: ${def.name}${draftRefs.length ? ` (${draftRefs.length} draft refs)` : ""}${lastAsk ? ` ask="${lastAsk}"` : ""}${chosen ? " — chosen places ride the tool description" : ""}`);
+          } catch (e: any) {
+            console.log(`[manifests] shell open failed for ${def.name} — ${e?.message ?? e}`);
+          }
+          minted.push({ name: def.name, description: `${def.description}${chosenNote}`, parameters: def.parameters });
+        },
+      );
+
+      /**
+       * PATH-A apps, minted here because the absorber's callback does not cover them.
+       *
+       * `onAppUnlocked` fires only for a bindingless PATH-B component app — the kind that
+       * needs a shell-open and a live schema read. A workflow-bound app carries its contract
+       * on the row and needs neither, so the harness has nothing to unlock and never calls
+       * back. It still has to become a tool, which is what this does.
+       *
+       * Deduped downstream by tool name, so re-minting on a later search is harmless.
+       */
+      if (harness.DISCOVERY_TOOL_NAMES.includes(toolName))
+        for (const mcp of harness.parseDiscoveredMCPs([{ name: toolName, resultContent }]))
+          if (!harness.isBindinglessComponentApp(mcp)) {
+            const def = harness.toolDefFromDiscoveredMCP(mcp);
+            minted.push({ name: def.name, description: def.description, parameters: def.parameters });
+          }
+
+      /**
+       * SKILLS IN FORCE, lifted before the lean drops them. Handed back beside `minted`
+       * because they are the same kind of fact: something the reply UNLOCKED that the loop
+       * must act on, rather than anything the model asked for.
+       */
+      const skills = harness.parseRegionSkills(resultContent);
+
+      return { content, minted, skills };
+    },
+
+    endsTurn(calls) {
+      return harness.isTurnEndingHandoff(calls, core);
+    },
+  };
+}

package/vendor/base/src/manifests/index.ts

@@ -0,0 +1,280 @@
+/**
+ * Manifest node loading.
+ *
+ * Reads declarative node manifests from a SOURCE, composes each folder into one
+ * definition, and registers it through exactly the same path a code plugin uses. A
+ * manifest node is therefore indistinguishable downstream: same registry, same
+ * /nodes payload, same catalog ranking, same canvas.
+ *
+ * RELOADABLE BY DESIGN. `loadManifests` can be called again at any time and will
+ * replace what it loaded before. That is the point of the format: installing or
+ * updating a node should never restart a universe. When the source becomes Postgres,
+ * an install is a row write followed by this call.
+ *
+ * See docs/architecture/DECLARATIVE_NODES.md.
+ */
+import {
+  getNodeRegistry,
+  getPluginNodeMap,
+  getCredentialRegistry,
+  replaceCredentialType,
+  unregisterCredentialType,
+  deleteNode,
+} from "../registry.js";
+import { composeNode, composeCredentials, packageVersion, packageMeta, ManifestError, type ComposedNode, type PackageMeta } from "./compose.js";
+import { hashNode, assertUnchanged, IntegrityError } from "./integrity.js";
+import { executorForKind, setManifestLookup } from "./executor/index.js";
+import { diskSource, rowsSource, type ManifestSource, type RawPackage } from "./source.js";
+import { fetchNodeRows } from "./rows.js";
+import { isPluginEnabled } from "../plugins/state.js";
+import { NODES_HOME, databaseOnly } from "../paths.js";
+import { boot } from "../boot.js";
+
+/** Marketplace name for a manifest package, so it shares one row with its code half. */
+export const packageIdFor = (name: string) => `@unoverse-platform/${name}`;
+
+/** Packages the current source offers, whether enabled or not. */
+export async function listManifestPackages(source: ManifestSource = diskSource(NODES_HOME)): Promise<string[]> {
+  return (await source.listPackages()).map((p) => packageIdFor(p.name));
+}
+
+export async function isManifestPackage(name: string, source?: ManifestSource): Promise<boolean> {
+  return (await listManifestPackages(source)).includes(name);
+}
+
+/**
+ * Display metadata per manifest package, keyed by marketplace name.
+ *
+ * A manifest package has no plugin-state row, so /plugins had nothing to show for it.
+ * Populated on every load and read by routePlugins.
+ */
+const packageMetas = new Map<string, PackageMeta>();
+
+export function getManifestPackageMeta(name: string): PackageMeta | undefined {
+  return packageMetas.get(name);
+}
+
+/** Node types this loader owns, so a reload can retract exactly what it added. */
+const loadedTypes = new Map<string, ComposedNode>();
+
+/**
+ * Credential types this loader owns.
+ *
+ * Tracked separately from the registry because retraction must be SURGICAL: a
+ * credential registered by a code plugin is not ours to remove, and clearing the whole
+ * registry on reload would take those with it. Only names in here are ever replaced or
+ * deleted.
+ */
+const loadedCredentials = new Set<string>();
+
+export function getLoadedManifestCredentials(): string[] {
+  return [...loadedCredentials];
+}
+
+// The two shared executors resolve their manifest by node type through this, which is
+// what keeps them at two classes rather than one per node, and lets a reload swap a
+// node's behaviour without re-registering anything.
+setManifestLookup((type) => loadedTypes.get(type));
+
+export function getManifestNode(type: string): ComposedNode | undefined {
+  return loadedTypes.get(type);
+}
+
+export function getLoadedManifestTypes(): string[] {
+  return [...loadedTypes.keys()];
+}
+
+export interface LoadResult {
+  nodes: number;
+  credentials: number;
+  errors: string[];
+}
+
+/**
+ * Where each loaded manifest package came from. Derived, never stored.
+ *
+ * A stored row goes stale: a package that moved from npm to manifests on disk kept
+ * rendering as installed, with a Remove button that would have disabled the manifest.
+ * `postgres:` origin means installed and removable; anything else is a folder on disk.
+ */
+export function manifestPackageOrigins(): Map<string, { source: "local" | "npm"; version: string }> {
+  const out = new Map<string, { source: "local" | "npm"; version: string }>();
+  for (const node of loadedTypes.values())
+    out.set(packageIdFor(node.packageName), {
+      source: node.origin.startsWith("postgres:") ? "npm" : "local",
+      version: node.packageVersion ?? "1.0.0",
+    });
+  return out;
+}
+
+/**
+ * Load (or reload) every manifest node from `source`.
+ *
+ * A broken node is skipped with a named error and never takes the others down: one
+ * bad YAML file must not cost a universe its whole catalog.
+ */
+export async function loadManifests(source?: ManifestSource): Promise<LoadResult> {
+  const registry = getNodeRegistry();
+  const pluginNodeMap = getPluginNodeMap();
+  const result: LoadResult = { nodes: 0, credentials: 0, errors: [] };
+
+  // TWO sources, in precedence order, FIRST ONE WINS. An explicit source (tests, a
+  // one-off load) wins outright; otherwise DISK beats rows, because a manifest present
+  // in the monorepo is being authored right now and must beat whatever was installed.
+  // Same local-wins first-principle the node loader already applies to npm copies.
+  // Under UNOVERSE_DATABASE_ONLY the disk half is dropped, so a developer sees the node
+  // set a deployed universe would have: whatever is installed, and nothing else.
+  const sources: ManifestSource[] = source
+    ? [source]
+    : databaseOnly()
+      ? [rowsSource(fetchNodeRows)]
+      : [diskSource(NODES_HOME), rowsSource(fetchNodeRows)];
+
+  const packages: RawPackage[] = [];
+  const seen = new Set<string>();
+  for (const s of sources) {
+    let batch: RawPackage[];
+    try {
+      batch = await s.listPackages();
+    } catch (err: any) {
+      result.errors.push(`source "${s.name}" failed: ${err?.message ?? err}`);
+      continue;
+    }
+    for (const pkg of batch) {
+      // Merge by node type rather than by package: a MIXED package can have some nodes
+      // on disk and others only installed, and dropping the whole package because its
+      // name was seen would lose the ones that are only in the database.
+      const nodes = pkg.nodes.filter((n) => !seen.has(n.dir));
+      for (const n of nodes) seen.add(n.dir);
+      const existing = packages.find((p) => p.name === pkg.name);
+      if (existing) existing.nodes.push(...nodes);
+      else if (nodes.length || Object.keys(pkg.credentials).length) packages.push({ ...pkg, nodes });
+    }
+  }
+  if (!packages.length) return result;
+
+  // Retract what a previous load added, so a reload cannot leave a deleted node or
+  // credential behind. Anything no longer present simply disappears.
+  const previous = new Set(loadedTypes.keys());
+  const previousCredentials = new Set(loadedCredentials);
+  loadedTypes.clear();
+  loadedCredentials.clear();
+
+  const credentialRegistry = getCredentialRegistry();
+  const disabledPackages: string[] = [];
+
+  packageMetas.clear();
+  for (const pkg of packages) {
+    packageMetas.set(packageIdFor(pkg.name), packageMeta(pkg));
+    // Disabled in the marketplace means GONE, not hidden: its nodes and credential
+    // types are retracted below exactly as if the package had been removed from the
+    // source. That is what makes uninstall work without a restart.
+    if (!isPluginEnabled(packageIdFor(pkg.name))) {
+      disabledPackages.push(pkg.name);
+      continue;
+    }
+
+    try {
+      for (const cred of composeCredentials(pkg)) {
+        // A credential a CODE plugin registered is not ours to overwrite: local source
+        // wins over a manifest, the same rule as for nodes.
+        if (credentialRegistry.has(cred.name) && !previousCredentials.has(cred.name)) {
+          result.errors.push(`${pkg.name}/credentials/${cred.name}: already registered by code — manifest skipped`);
+          continue;
+        }
+        // REPLACE, not register: a package that adds a field to its credential must be
+        // able to land that change without a restart, and the first-wins path would
+        // keep the old shape forever.
+        replaceCredentialType(cred);
+        loadedCredentials.add(cred.name);
+        result.credentials++;
+      }
+    } catch (err: any) {
+      result.errors.push(err instanceof ManifestError ? err.message : `${pkg.name}/credentials: ${err?.message ?? err}`);
+    }
+
+    const types: string[] = [];
+    for (const raw of pkg.nodes) {
+      try {
+        const node = composeNode(raw, pkg);
+        node.hash = hashNode(node);
+        node.packageVersion = packageVersion(pkg);
+
+        // TAMPER CHECK, before the node reaches the registry. A source that recorded a
+        // hash at publish gets it verified now; disk records none and is governed by git
+        // instead. Failing here rather than at first execution is deliberate: a node that
+        // does not match what was approved must never become callable, not even once.
+        assertUnchanged(node, raw.hash, `${pkg.name}/${raw.dir}`);
+
+        // A code node of the same type already loaded. Never override it: local
+        // source wins over a manifest exactly as it wins over an npm copy, so a
+        // half-migrated package cannot silently swap a working executor for one that
+        // refuses to run.
+        if (registry.has(node.type) && !previous.has(node.type)) {
+          result.errors.push(`${pkg.name}/${raw.dir}: type "${node.type}" is already registered by code — manifest skipped`);
+          continue;
+        }
+
+        registry.set(node.type, {
+          ...(node.definition as any),
+          // ONE of two shared classes, never a class per node.
+          executor: executorForKind(node.kind),
+          executionMode: node.kind === "CallbackNode" ? "generator" : "single",
+        });
+        loadedTypes.set(node.type, node);
+        types.push(node.type);
+        result.nodes++;
+      } catch (err: any) {
+        // An integrity failure is not the same class of problem as a malformed manifest,
+        // so it says so and is never folded into the quiet "skipped" count below.
+        if (err instanceof IntegrityError) console.error(`[unoverse:manifests] TAMPER: ${err.message}`);
+        result.errors.push(
+          err instanceof ManifestError || err instanceof IntegrityError
+            ? err.message
+            : `${pkg.name}/${raw.dir}: ${err?.message ?? err}`,
+        );
+      }
+    }
+
+    if (types.length) {
+      // Merge rather than replace: a MIXED package has code nodes here already, and
+      // dropping them would lose the package→types provenance /plugins reads.
+      const existing = pluginNodeMap.get(`@unoverse-platform/${pkg.name}`) ?? [];
+      pluginNodeMap.set(`@unoverse-platform/${pkg.name}`, [...new Set([...existing, ...types])]);
+
+    }
+  }
+
+  // Anything this loader owned last time and no longer produces is gone. Surgical on
+  // purpose: only names this loader registered are ever retracted, so uninstalling a
+  // manifest package cannot take a code plugin's node or credential with it.
+  for (const stale of previous) if (!loadedTypes.has(stale)) deleteNode(stale);
+  for (const stale of previousCredentials)
+    if (!loadedCredentials.has(stale) && unregisterCredentialType(stale))
+      console.log(`[unoverse:manifests] retracted credential type ${stale}`);  // a real change of state
+
+  // At boot this is one row in the readout. A LATER reload (the watcher, an install,
+  // an uninstall) is an event on an otherwise quiet screen, so it still speaks.
+  if (boot.isBooting()) {
+    boot.manifests({
+      nodes: result.nodes,
+      credentials: result.credentials,
+      // "already registered by code" is the local-wins rule working, not a fault, so it
+      // is reported as a shadow with its type named rather than as an error.
+      shadowed: result.errors.flatMap((e) => {
+        const m = /type "([^"]+)" is already registered by code/.exec(e);
+        return m ? [m[1]] : [];
+      }),
+      disabled: disabledPackages,
+    });
+    for (const e of result.errors)
+      if (!/already registered by code/.test(e)) boot.notice("warn", `manifest skipped: ${e}`);
+  } else {
+    console.log(
+      `[unoverse:manifests] ${result.nodes} node(s), ${result.credentials} credential type(s) from ${sources.map((s) => s.name).join(" + ")}` +
+        (result.errors.length ? `, ${result.errors.length} skipped` : ""),
+    );
+    for (const e of result.errors) console.warn(`  ! ${e}`);
+  }
+  return result;
+}

package/vendor/base/src/manifests/integrity.ts

@@ -0,0 +1,93 @@
+/**
+ * THE CONTENT HASH. Its own file, like allowedHosts.ts, because it is a security control.
+ *
+ * AllowedHosts answers "what can this node do?". It does NOT answer "is this the node I
+ * approved?", and only the second question is about tampering. See SECURITY.md
+ * §"Manifest integrity — phase 1, the content hash".
+ *
+ * WHAT IS HASHED: the COMPOSED document, which includes the package envelope.
+ *
+ * Not the node's own files alone, and this is the whole point rather than a detail.
+ * `allowedHosts` is declared in package.yaml, so a hash over only api/run.yaml would leave the
+ * allowlist that bounds the node editable by anyone who can edit the node. Hashing the
+ * composition is what makes the allowedHosts declaration itself tamper-evident.
+ *
+ * Canonical JSON, not the YAML bytes, so reformatting or editing a comment does not break
+ * the seal while everything that actually EXECUTES stays covered. A comment cannot change
+ * behaviour; a changed URL, credential reference or expression always can.
+ *
+ * WHEN: at load, and only at load. Verification is a boot-time cost of milliseconds across
+ * a package. Nothing is hashed while a node is running, and nothing ever should be: a
+ * per-call check would be the one design that actually slows nodes down.
+ *
+ * WHAT THIS IS NOT: a hash stored beside the thing it protects is tamper EVIDENCE, not
+ * tamper PREVENTION. Someone with database write access can change the manifest and the
+ * hash in one transaction. It catches a hand-edited row, a stray script, drift between git
+ * and a universe, and corruption. Defeating an attacker who already owns the database is
+ * what signing is for, and that is phase 2.
+ */
+import { createHash } from "node:crypto";
+import type { ComposedNode } from "./compose.js";
+
+/** Prefixed so a stored value says what produced it, and a future scheme can coexist. */
+const PREFIX = "sha256";
+
+/**
+ * Canonical JSON: object keys sorted at every depth, arrays left alone.
+ *
+ * Sorting keys makes the hash independent of the order YAML happened to be written in, so
+ * moving `transport` above `auth` in a file is not a tamper. Array order is PRESERVED and
+ * must be: the order of `run` is the order the calls happen, and the order of `events` is
+ * the connector order lint enforces. Sorting those would erase real meaning.
+ */
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort())
+      out[key] = canonical((value as Record<string, unknown>)[key]);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * The hash of a composed node: `sha256:<hex>`.
+ *
+ * `origin` is deliberately EXCLUDED. It is the absolute path on disk or a `postgres:` id,
+ * so including it would give the same node a different hash on every machine and make the
+ * value useless for comparing what a developer reviewed against what a universe is running.
+ * Everything else about the node is in scope, including `allowedHosts`.
+ */
+export function hashNode(node: ComposedNode): string {
+  const subject = {
+    type: node.type,
+    kind: node.kind,
+    packageName: node.packageName,
+    allowedHosts: node.allowedHosts,
+    definition: node.definition,
+    api: node.api,
+  };
+  return `${PREFIX}:${createHash("sha256").update(JSON.stringify(canonical(subject))).digest("hex")}`;
+}
+
+export class IntegrityError extends Error {}
+
+/**
+ * Refuse a node whose content does not match the hash its source recorded.
+ *
+ * A source with no expected hash is NOT an error: manifests on disk are governed by git,
+ * which is a better integrity control than a hash file sitting next to the thing it
+ * protects, and demanding one would make local authoring impossible. The check applies
+ * where a hash was recorded, which in practice means rows.
+ */
+export function assertUnchanged(node: ComposedNode, expected: string | undefined, where: string): void {
+  if (!expected) return;
+  const actual = hashNode(node);
+  if (actual === expected) return;
+  throw new IntegrityError(
+    `${where}: content hash mismatch. Recorded ${expected}, computed ${actual}. ` +
+      `This node's manifest has changed since it was published, so it will NOT be registered. ` +
+      `Re-deploy it from source rather than editing the stored copy (SECURITY.md §Manifest integrity).`,
+  );
+}

package/vendor/base/src/manifests/rows.ts

@@ -0,0 +1,33 @@
+/**
+ * Reading installed node rows.
+ *
+ * The engine owns database access (this server has no Postgres client), so rows come
+ * over the same internal hop plugin state already uses. Kept in its own file so
+ * `source.ts` stays a pure shape-conversion with no transport in it.
+ *
+ * A failure here THROWS. It used to answer [] instead, which is indistinguishable from
+ * a universe that owns nothing, and on a deployed universe rows are the only node
+ * source, so a boot that lost the race to the engine silently served an empty catalog.
+ * The loader records a thrown source and carries on, so one dead source still cannot
+ * lose the other.
+ */
+import type { ItemRow } from "./source.js";
+
+const ENGINE = process.env.WORKFLOW_SERVICE_URL || "http://localhost:4101";
+
+export async function fetchNodeRows(): Promise<ItemRow[]> {
+  let res: Response;
+  try {
+    res = await fetch(`${ENGINE}/items?kind=node`);
+  } catch (error: any) {
+    // Unreachable: the engine is not up yet, or not where we think it is. Both are worth
+    // retrying, and neither means this universe has no nodes.
+    throw new Error(`could not reach the engine at ${ENGINE} to read node rows: ${error?.message ?? error}`);
+  }
+  if (!res.ok) throw new Error(`the engine answered ${res.status} reading node rows from ${ENGINE}/items?kind=node`);
+
+  const data = (await res.json()) as { items?: Array<{ name: string; definition: any; enabled?: boolean }> };
+  // A disabled row is retracted, not hidden: it must not register, exactly as an
+  // uninstalled one would not. Enabled is the running state, presence is possession.
+  return (data.items ?? []).filter((r) => r.enabled !== false).map((r) => ({ name: r.name, definition: r.definition }));
+}