@unoverse-platform/studio 0.1.90 → 0.1.92

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

@@ -0,0 +1,539 @@
+/**
+ * Compose a node folder into ONE definition.
+ *
+ * A node is authored as up to five files split by rate of change (node, interface,
+ * config, api, test). Nothing downstream should know or care: this turns them into
+ * the single object the registry already stores, so a manifest node and a code node
+ * are indistinguishable to the catalog, the canvas and the engine.
+ *
+ * Any section may instead be inlined into node.yaml. Defined in BOTH places is an
+ * error, never a merge — silently merging would make a stale file invisible.
+ *
+ * NOTE: the $ref and section rules here are also implemented in
+ * scripts/lib/lint-nodes.mjs, which must run without the server (it ships in the
+ * starter kit). Keep the two in step; the linter is the one developers see first.
+ *
+ * See docs/architecture/DECLARATIVE_NODES.md §5.
+ */
+import * as YAML from "yaml";
+import type { RawNode, RawPackage } from "./source.js";
+
+/** The sections that may live in their own file OR inline in node.yaml. */
+const SECTIONS = ["interface", "config", "api", "test"] as const;
+
+/**
+ * The builder's run-authorization controls, ONE canonical copy (who-can-run-it.md).
+ * Injected into every runnable node's composed config schema; see the chrome comment
+ * in composeNode. The wording is the doc's: change it here and the doc together.
+ *
+ * EXPORTED because a node is built by TWO paths, and for a year only this one injected
+ * the controls. `composeNode` builds manifest nodes; the Unoverse server synthesizes a
+ * node per design component (runtime/components/meta.ts) and never passed through here,
+ * so no Component box has ever carried a Require sign-in toggle while the docs said every
+ * runnable node does. The second path imports this constant rather than restating it: two
+ * copies of a control that decides who may run something is how they drift.
+ */
+export const RUN_AUTH_CHROME = {
+  authRequired: {
+    type: "boolean",
+    title: "Require sign-in",
+    description:
+      "Only a signed-in caller may run this step. Leave off and it runs for whoever " +
+      "the workflow's trigger admitted, which is the usual answer.",
+    default: false,
+    "ui:widget": "toggle",
+  },
+  authRole: {
+    type: "string",
+    title: "Require role",
+    description:
+      "A claim the caller's account must carry, as noun:verb (finance:approve, " +
+      "payments:refund). Leave blank to require only that they are signed in.",
+    default: "",
+    "ui:dependencies": { authRequired: true },
+  },
+} as const;
+type Section = (typeof SECTIONS)[number];
+
+/**
+ * DEEP for plain objects, so overriding one field does not delete its siblings.
+ *
+ * A shallow spread made `{ $ref: x, body: { mode: 'intent' } }` REPLACE the imported body
+ * entirely: every other key — the filters, the result cap, the query itself — vanished, and
+ * the request still went out, valid and wrong. Nothing failed, because a body with fewer
+ * keys is a legal body. That is the worst shape of bug this format can produce, and the
+ * whole point of a $ref with siblings is "import a block and adjust one field".
+ *
+ * Arrays REPLACE rather than concatenating: a list is an ordered whole, and merging two
+ * would give an author no way to shorten one.
+ */
+function deepMerge(base: any, over: any): any {
+  if (base === null || typeof base !== "object" || Array.isArray(base)) return over;
+  if (over === null || typeof over !== "object" || Array.isArray(over)) return over;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) out[k] = k in base ? deepMerge(base[k], v) : v;
+  return out;
+}
+
+export interface ComposedNode {
+  type: string;
+  kind: "PromiseNode" | "CallbackNode";
+  packageName: string;
+  /**
+   * Hosts this node may call, from its package's `allowedHosts`. Empty means NONE: a
+   * package that declares no allowedHosts cannot reach the network at all.
+   *
+   * SECURITY.md treats a node as trusted code bounded by provenance, and a template
+   * expression as untrusted data bounded by having no credentials in scope. A
+   * manifest node is neither: it arrives as data yet holds a credential and a URL.
+   * This is its boundary.
+   */
+  allowedHosts: string[];
+  /**
+   * WHO MAY RUN THIS NODE, from node.yaml (DECLARATIVE_NODES.md §9.13). The inbound
+   * question, about the CALLER. Not a call's `credential`, which is outbound.
+   *
+   * Carried here because it was previously read out of the YAML by lint and then dropped:
+   * the executor received a node object with no `auth` field at all, so the check could not
+   * have been written even if someone had tried. A declaration nothing can read is worse
+   * than no declaration, because it looks decided.
+   */
+  auth: { required: boolean; role?: string };
+  /**
+   * NAMED FUNCTIONS the package's expressions may call, collected from `helpers:` in every
+   * shared/ file (DECLARATIVE_NODES.md §5.4).
+   *
+   * PACKAGE-scoped, not node-scoped, for the same reason `shared/` is: two nodes in one
+   * package almost always project the same vendor's rows the same way, and the alternative
+   * is the copy-paste that `$ref` exists to prevent.
+   */
+  helpers: Record<string, { args?: string[]; body: string }>;
+  origin: string;
+  /** The registry-shaped definition. */
+  definition: Record<string, any>;
+  /** The api block, carried for the executor. Absent means the node does nothing yet. */
+  api: Record<string, any> | null;
+  /** The version the package declares, so /plugins need not trust a stale row. */
+  packageVersion?: string;
+  /**
+   * `sha256:<hex>` over this composed document, filled in by the loader.
+   *
+   * Set after composition rather than inside it, because the hash is OVER the composed
+   * result and a field cannot be part of what it summarises.
+   */
+  hash?: string;
+}
+
+export class ManifestError extends Error {}
+
+function parse(yaml: string, where: string): any {
+  let doc: any;
+  try {
+    doc = YAML.parse(yaml);
+  } catch (err: any) {
+    throw new ManifestError(`${where} is not valid YAML: ${String(err?.message ?? err).split("\n")[0]}`);
+  }
+  if (doc && typeof doc === "object") delete doc.$schema;
+  return doc ?? {};
+}
+
+/**
+ * Resolve a `$ref` against the package's `shared/` folder.
+ *
+ * SHORT FORM, and the one to write:
+ *     url:  { $ref: endpoints#responses }
+ *     enum: { $ref: models#enum }
+ *     toolExchange:
+ *       $ref: tools          # whole file
+ *       maxTurns: 5          # local keys layer on top and win
+ *
+ * No path, because there was never a real path: shared fragments are package-scoped and
+ * the directory part was always thrown away. `../../shared/endpoints.yaml#/responses`
+ * still works, but it is arithmetic that buys nothing.
+ *
+ * A LONE $ref REPLACES. A $ref WITH SIBLINGS MERGES, local winning, which is what lets a
+ * node import a whole shared block and adjust one field.
+ */
+function resolveRefs(value: any, pkg: RawPackage, where: string, depth = 0): any {
+  if (depth > 10) throw new ManifestError(`${where}: $ref nested more than 10 deep, probably a cycle`);
+  if (Array.isArray(value)) return value.map((v) => resolveRefs(v, pkg, where, depth));
+  if (!value || typeof value !== "object") return value;
+
+  const keys = Object.keys(value);
+  if (typeof value.$ref === "string") {
+    const [target, frag = ""] = value.$ref.split("#");
+    // `endpoints`, `endpoints.yaml`, or `../../shared/endpoints.yaml` — all the same file.
+    const stem = (target.split("/").pop() ?? "").replace(/\.ya?ml$/, "");
+    const body = pkg.shared[`${stem}.yaml`] ?? pkg.shared[`${stem}.yml`];
+    if (body === undefined)
+      throw new ManifestError(`${where}: $ref "${value.$ref}" — no shared/${stem}.yaml in package "${pkg.name}"`);
+    const doc = parse(body, `${pkg.name}/shared/${stem}.yaml`);
+    const hit = frag
+      .replace(/^\//, "")
+      .split("/")
+      .filter(Boolean)
+      .reduce((a: any, k: string) => (a == null ? a : a[k]), doc);
+    if (hit === undefined) throw new ManifestError(`${where}: $ref "${value.$ref}" resolved to nothing`);
+    const imported = resolveRefs(hit, pkg, where, depth + 1);
+    if (keys.length === 1) return imported;
+
+    // Siblings present: merge, local wins.
+    const local = Object.fromEntries(
+      keys.filter((k) => k !== "$ref").map((k) => [k, resolveRefs(value[k], pkg, where, depth)]),
+    );
+    if (imported === null || typeof imported !== "object" || Array.isArray(imported))
+      throw new ManifestError(`${where}: $ref "${value.$ref}" is not an object, so it cannot be merged with sibling keys`);
+    return deepMerge(imported as any, local) as any;
+  }
+  return Object.fromEntries(keys.map((k) => [k, resolveRefs(value[k], pkg, where, depth)]));
+}
+
+/**
+ * Who published the package. Absent means unknown, which the UI must show as third
+ * party rather than assume: "we could not tell" and "we vouch for it" are different
+ * answers and only one of them is safe to guess.
+ */
+function packagePublisher(pkg: RawPackage): string | null {
+  if (!pkg.packageFile) return null;
+  const doc: any = parse(pkg.packageFile, `${pkg.name}/package.yaml`) ?? {};
+  return typeof doc.publisher === "string" && doc.publisher.trim() ? doc.publisher.trim() : null;
+}
+
+/**
+ * WHO MAY RUN THIS NODE, read off node.yaml (DECLARATIVE_NODES.md §9.13).
+ *
+ * FAILS CLOSED on a malformed or missing block. Lint requires `auth.required` and rejects a
+ * `role` alongside `required: false`, but lint runs at author time and a manifest can arrive
+ * as a database row that never met it. Defaulting the absent case to "open" would mean the
+ * one path that skipped lint is also the one that skips authorization.
+ *
+ * The unsatisfiable pair is collapsed rather than thrown on: a role implies an authenticated
+ * caller, so `role` with `required: false` is read as `required: true`. Throwing at LOAD
+ * would take the whole package down for one bad node, and admitting everyone would be the
+ * opposite of what the author asked for.
+ */
+export function nodeAuth(node: any): { required: boolean; role?: string } {
+  const raw = node?.auth;
+  const role = typeof raw?.role === "string" && raw.role.trim() ? raw.role.trim() : undefined;
+  // `typeof null === "object"`, so null must be excluded explicitly or reading `.required`
+  // off it throws — turning a fail-closed path into a crash, which is a different failure
+  // with a much worse error message.
+  if (raw === null || typeof raw !== "object")
+    // No block at all. Lint makes this impossible in the tree; a pasted manifest is why it
+    // is handled here, and "signed in" is the safe reading of a node that never said.
+    return { required: true, role };
+  if (typeof raw.required !== "boolean") return { required: true, role };
+  return { required: raw.required || role !== undefined, role };
+}
+
+/**
+ * Every `helpers:` declaration across the package's shared/ folder, merged into one bag.
+ *
+ * Collected from ALL shared files rather than one reserved filename, because a helper belongs
+ * next to the thing it serves: the row projection sits in the same file as the search that
+ * produces the rows. A dedicated helpers.yaml would separate them again, which is the problem
+ * this is fixing.
+ *
+ * A DUPLICATE NAME THROWS. Two files defining `row` would otherwise resolve by directory
+ * order, so which one ran depended on a filename — and the loser would look defined, be
+ * readable, and never execute.
+ */
+export function packageHelpers(pkg: RawPackage): Record<string, { args?: string[]; body: string }> {
+  const out: Record<string, { args?: string[]; body: string }> = {};
+  const from: Record<string, string> = {};
+  for (const [file, body] of Object.entries(pkg.shared ?? {})) {
+    if (!/\.ya?ml$/.test(file)) continue;
+    const doc = parse(body, `${pkg.name}/shared/${file}`);
+    const declared = doc?.helpers;
+    if (declared === undefined) continue;
+    if (declared === null || typeof declared !== "object" || Array.isArray(declared))
+      throw new ManifestError(`${pkg.name}/shared/${file}: "helpers" must be a map of name → { args, body }`);
+    for (const [name, def] of Object.entries(declared as Record<string, any>)) {
+      if (name in out)
+        throw new ManifestError(
+          `${pkg.name}: helper "${name}" is defined in both shared/${from[name]} and shared/${file} — a name may only be declared once`,
+        );
+      if (!def || typeof def !== "object" || typeof def.body !== "string" || !def.body.trim())
+        throw new ManifestError(`${pkg.name}/shared/${file}: helper "${name}" needs a non-empty string "body"`);
+      if (def.args !== undefined && (!Array.isArray(def.args) || def.args.some((a: any) => typeof a !== "string")))
+        throw new ManifestError(`${pkg.name}/shared/${file}: helper "${name}" — "args" must be a list of names`);
+      out[name] = { args: def.args, body: def.body };
+      from[name] = file;
+    }
+  }
+  return out;
+}
+
+/** A package's declared allowedHosts hosts. Absent or empty means the package cannot call out. */
+export function packageAllowedHosts(pkg: RawPackage): string[] {
+  if (!pkg.packageFile) return [];
+  const doc = parse(pkg.packageFile, `${pkg.name}/package.yaml`);
+  return Array.isArray(doc.allowedHosts) ? doc.allowedHosts.map((h: string) => String(h).toLowerCase()) : [];
+}
+
+/** The version a package declares for itself, so state does not keep reporting an old npm one. */
+/**
+ * The hosts THIS node may call: its own list when it declares one, else the package's.
+ *
+ * The package sets the CEILING and a node may only narrow it. A node that named a host its
+ * package did not would otherwise be a way to widen the boundary from inside the thing the
+ * boundary contains, which is the mistake this codebase has now made twice.
+ *
+ * Why it matters in practice: `gtm` calls two vendors, so its package list holds both, and
+ * without this every Apollo node is also permitted to reach Hunter. One node, one vendor is
+ * what a reviewer expects when they read a node's page.
+ */
+export function nodeAllowedHosts(node: any, fromPackage: string[], where: string): string[] {
+  const own = node.allowedHosts;
+  if (!Array.isArray(own) || !own.length) return fromPackage;
+
+  const narrowed = own.map((h: string) => String(h).toLowerCase());
+  const widened = narrowed.filter((h) => !fromPackage.includes(h));
+  if (widened.length)
+    throw new ManifestError(
+      `${where}: node.yaml allows ${widened.map((h) => `"${h}"`).join(", ")}, which package.yaml does not. ` +
+        `A node may only NARROW its package's allowedHosts, never widen them.`,
+    );
+  return narrowed;
+}
+
+export function packageVersion(pkg: RawPackage): string | undefined {
+  if (!pkg.packageFile) return undefined;
+  const doc = parse(pkg.packageFile, `${pkg.name}/package.yaml`);
+  return doc.version ? String(doc.version) : undefined;
+}
+
+/**
+ * A package's display envelope: what the marketplace shows ABOUT the package rather
+ * than about its nodes.
+ *
+ * Manifest packages have no plugin-state row to carry this, so without it the Installed
+ * list falls back to the bare folder name and no mark: "airtable" with an empty square
+ * instead of "Airtable" with its logo. The information was always in package.yaml; it
+ * just had no route out.
+ */
+export interface PackageMeta {
+  displayName?: string;
+  description?: string;
+  category?: string;
+  logoUrl?: string;
+  features?: string[];
+  publisher?: string | null;
+  version?: string;
+}
+
+export function packageMeta(pkg: RawPackage): PackageMeta {
+  if (!pkg.packageFile) return {};
+  const doc: any = parse(pkg.packageFile, `${pkg.name}/package.yaml`) ?? {};
+  return {
+    displayName: doc.displayName ? String(doc.displayName) : undefined,
+    description: doc.description ? String(doc.description) : undefined,
+    category: doc.category ? String(doc.category) : undefined,
+    logoUrl: doc.logoUrl ? String(doc.logoUrl) : undefined,
+    features: Array.isArray(doc.features) ? doc.features.map(String) : undefined,
+    publisher: packagePublisher(pkg),
+    version: doc.version ? String(doc.version) : undefined,
+  };
+}
+
+export function composeNode(raw: RawNode, pkg: RawPackage): ComposedNode {
+  const where = `${pkg.name}/${raw.dir}`;
+  // The package envelope, so a node can inherit what belongs to the whole package.
+  const pkgMeta = packageMeta(pkg);
+
+  const nodeFile = raw.files["node.yaml"];
+  if (!nodeFile) throw new ManifestError(`${where}: no node.yaml`);
+  const node = parse(nodeFile, `${where}/node.yaml`);
+
+  const parts: Partial<Record<Section, any>> = {};
+  for (const s of SECTIONS) {
+    // Two ways to say the same thing, and exactly one may be used:
+    //   inline in node.yaml    small sections that are not worth a file
+    //   <s>.yaml               the common case
+    //   <s>/<key>.yaml         one file per top-level key
+    // The FILENAME IS THE KEY: api/request.yaml is what sat under `request:`. That
+    // leaves no merge order to reason about and no way to define a key twice.
+    //
+    // `api` is ALWAYS the folder form, no exceptions, so every node reads the same way:
+    // one file per call, plus the events table. Enforced below and by lint.
+    const folder = Object.keys(raw.files).filter((f) => f.startsWith(`${s}/`)).sort();
+    const onDisk = raw.files[`${s}.yaml`];
+    const inline = node[s];
+
+    const ways = [folder.length ? `${s}/` : null, onDisk !== undefined ? `${s}.yaml` : null, inline !== undefined ? "node.yaml" : null].filter(Boolean);
+    if (ways.length > 1)
+      throw new ManifestError(`${where}: "${s}" is defined in ${ways.join(" and ")} — pick one, this is never a merge`);
+
+    let doc: any;
+    if (folder.length) {
+      doc = {};
+      for (const f of folder) {
+        const key = f.slice(s.length + 1).replace(/\.ya?ml$/, "");
+        doc[key] = parse(raw.files[f], `${where}/${f}`);
+      }
+    } else doc = onDisk !== undefined ? parse(onDisk, `${where}/${s}.yaml`) : inline;
+
+    if (doc !== undefined) parts[s] = resolveRefs(doc, pkg, `${where}/${s}.yaml`);
+    delete node[s];
+  }
+
+  if (parts.api !== undefined && !Object.keys(raw.files).some((f) => f.startsWith("api/")))
+    throw new ManifestError(
+      `${where}: api must be a FOLDER (api/request.yaml, api/events.yaml, ...), not api.yaml or an inline api block — every node has the same shape`,
+    );
+
+  // RETIRED SHAPES, refused at composition.
+  //
+  // Lint catches these while authoring, but an already-PUBLISHED package does not get
+  // linted: it arrives as a row and goes straight here. Without this, an older marketplace
+  // version composes to an api block with no `run`, so a PromiseNode registers happily and
+  // then dies on first execution with "has only service methods", while a CallbackNode
+  // fails on a kind mismatch that names neither the cause nor the fix.
+  //
+  // Failing here instead says what to do, at the moment the universe loads the package.
+  for (const [old, now] of [["request", "run (a LIST of calls)"], ["steps", "run"], ["provides", "service"]] as const)
+    if (parts.api && (parts.api as any)[old] !== undefined)
+      throw new ManifestError(
+        `${where}: api/${old}.yaml is from an older manifest format and cannot be loaded — it is now api/${now}. ` +
+          `Re-publish this package from a current source tree (DECLARATIVE_NODES.md §5).`,
+      );
+
+  if (!node.type) throw new ManifestError(`${where}: node.yaml has no type`);
+  if (node.kind !== "PromiseNode" && node.kind !== "CallbackNode")
+    throw new ManifestError(`${where}: node.yaml kind must be PromiseNode or CallbackNode, got ${JSON.stringify(node.kind)}`);
+
+  const iface = parts.interface ?? {};
+  const config = parts.config ?? {};
+  const api = parts.api ?? null;
+
+  // A tool exchange or a streaming transport makes this a CallbackNode. The manifest
+  // DECLARES kind so it is visible on the node; this refuses the declaration when it
+  // contradicts what the node actually does, which used to surface only at run time.
+  // The LAST step is the one whose reply becomes the node's answer, so it is the only one
+  // whose transport can make the node stream. Every earlier step settles by definition.
+  const finalCall = api?.run?.[api.run.length - 1];
+  // `ws` streams by definition: a duplex session emits for as long as the call lasts. Listed
+  // beside sse for the same reason — the node cannot settle once, so it is a CallbackNode.
+  const streams = ["sse", "ndjson", "awsEventStream", "ws"].includes(finalCall?.transport);
+  /**
+   * SPAWN implies an actor. CONTINUE DOES NOT, and this rule used to say it did.
+   *
+   * The premise was that a re-fired node must be a generator. It is false, and the LoopStart /
+   * LoopEnd pair is the counter-example that found it: LoopStart is a settle-once node that runs,
+   * returns, and then runs AGAIN because LoopEnd routes a `continue` signal back to it along an
+   * ordinary edge. Each pass is a separate execution, which is exactly why the loop's index has to
+   * live in Redis rather than in a closure.
+   *
+   * Getting this wrong is not cosmetic. `ManifestCallbackExecutor` has `initializeState`, and the
+   * registry reads the presence of that method to record executionMode "generator" — so forcing
+   * CallbackNode here would hand LoopStart an actor and have the engine drive it a different way
+   * than the node it replaces. The retired executor is a `PromiseNode` with a CONTINUE input, and
+   * that combination has to stay expressible.
+   *
+   * SPAWN stays, because SPAWN is by definition "initialise an actor" (09-signal-routing.md). What
+   * makes a node a CallbackNode is emitting more than once from ONE execution: a streaming
+   * transport, or a tool exchange's turns.
+   */
+  const spawns = (iface.inputs ?? []).some((i: any) => i?.signal === "SPAWN");
+  /**
+   * RUN-AUTHORIZATION CHROME (UNOVERSE_NODE_ACCESS_CHROME.md, decided 2026-08-21).
+   *
+   * The builder's two access controls are injected HERE, once, into the schema every
+   * host is served, instead of being authored into every node's config.yaml. They used
+   * to be compulsory boilerplate in all 76 configs, held byte-identical by a lint rule,
+   * which is the signature of a thing the platform should own: a rule whose job is to
+   * keep N copies identical means there should be one copy.
+   *
+   * Injected at COMPOSE rather than by each front end, so no renderer can forget them
+   * the way SpatialSearch once shipped without them. The executor is untouched:
+   * authorize.ts already reads the raw instance values and takes the stricter of these
+   * and node.yaml's `auth` floor.
+   *
+   * An ANNOTATION (no inputs, no outputs, no api) is never run, so there is nobody to
+   * authorize and it gets no section — the same exception lint always made.
+   *
+   * A manifest still declaring the fields is superseded, not merged: the canonical
+   * definition wins, so a stale copy cannot loosen a default or reword the contract.
+   * (Lint refuses the names outright; this handles installed packages published before
+   * the flip.)
+   */
+  const annotation = !(iface.outputs ?? []).length && !(iface.inputs ?? []).length && !api;
+  const authoredSchema = config.configSchema ?? {};
+  const authoredProps = { ...(authoredSchema.properties ?? {}) };
+  delete authoredProps.authRequired;
+  delete authoredProps.authRole;
+  const composedSchema = annotation
+    ? authoredSchema
+    : { type: "object", ...authoredSchema, properties: { ...authoredProps, ...RUN_AUTH_CHROME } };
+  const authoredOrder: string[] | null = config["ui:order"] ?? null;
+  const composedOrder =
+    annotation || !authoredOrder
+      ? authoredOrder
+      : [...authoredOrder.filter((f) => f !== "authRequired" && f !== "authRole"), "authRequired", "authRole"];
+  const derived = streams || spawns || api?.toolExchange ? "CallbackNode" : "PromiseNode";
+  if (node.kind !== derived)
+    throw new ManifestError(
+      `${where}: declares kind "${node.kind}" but is a ${derived} (` +
+        (streams ? `its last step's transport "${finalCall.transport}" streams` : api?.toolExchange ? "it declares a toolExchange" : "an input carries a SPAWN signal") +
+        `)`,
+    );
+
+  return {
+    type: node.type,
+    kind: node.kind,
+    packageName: pkg.name,
+    origin: raw.origin,
+    allowedHosts: nodeAllowedHosts(node, packageAllowedHosts(pkg), where),
+    auth: nodeAuth(node),
+    helpers: packageHelpers(pkg),
+    api,
+    // Shaped for the registry (see platform/pluginAPI.ts registerNode), so a manifest
+    // node is indistinguishable from a code node everywhere downstream.
+    definition: {
+      type: node.type,
+      name: node.name ?? node.type,
+      description: node.description ?? "",
+      // The catalog ranker embeds this; losing it here would make the node invisible
+      // to the building agent no matter how well it works.
+      whenToUse: node.whenToUse ?? "",
+      // Trust surface, carried on the definition so it travels with the node into the
+      // catalog and needs no second lookup: WHO shipped it, and WHAT it may call.
+      // A manifest node arrives as data yet holds a credential and a URL, so these two
+      // answer "what am I accepting" without opening the YAML.
+      publisher: packagePublisher(pkg),
+      allowedHosts: nodeAllowedHosts(node, packageAllowedHosts(pkg), where),
+      category: node.category ?? "general",
+      version: node.version ?? "1.0.0",
+      color: node.color ?? "#6366f1",
+      // INHERITED from the package unless the node overrides it. A logo is a property
+      // of the vendor, not of one endpoint, so repeating it per node is 25 copies of
+      // one string that drift the moment a URL changes (Airtable shipped a dead one in
+      // four files). Declare it once in package.yaml; a node only names its own if it
+      // genuinely differs.
+      logoUrl: node.logoUrl ?? pkgMeta.logoUrl ?? null,
+      // How the canvas draws it. Absent means the ordinary node card.
+      template: node.template ?? null,
+      visibility: node.visibility ?? "public",
+      capabilities: node.capabilities ?? null,
+      inputs: iface.inputs ?? [],
+      outputs: iface.outputs ?? [],
+      credentials: iface.credentials ?? [],
+      serviceConnectors: iface.serviceConnectors ?? null,
+      isService: (iface.serviceConnectors ?? []).some((s: any) => s?.isService === true),
+      configSchema: composedSchema,
+      // The authored field order for the settings form, with the access chrome appended
+      // last (settings about access, not about the job). Null when nothing was authored:
+      // the canvas falls back to schema declaration order, which also puts chrome last.
+      "ui:order": composedOrder,
+      testData: parts.test?.testData ?? null,
+    },
+  };
+}
+
+export function composeCredentials(pkg: RawPackage): Record<string, any>[] {
+  return Object.entries(pkg.credentials).map(([file, body]) => {
+    const doc = parse(body, `${pkg.name}/credentials/${file}`);
+    if (!doc.name) throw new ManifestError(`${pkg.name}/credentials/${file}: no name`);
+    return { name: doc.name, displayName: doc.displayName ?? doc.name, description: doc.description ?? "", properties: doc.properties ?? [] };
+  });
+}

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

@@ -0,0 +1,107 @@
+/** Emit-repeatedly. Streaming, iteration, or a tool exchange. */
+import { performApi, performService } from "../runtime/index.js";
+import { assertAuthorized } from "../runtime/authorize.js";
+import { manifestFor } from "./lookup.js";
+import { contextFor } from "./context.js";
+import { sessionFor, stateStoreFor, audioLaneFor } from "./session.js";
+import { refireAfterDocMutation } from "./refire.js";
+import { toolBridgeFor } from "./toolBridge.js";
+import { hydrateMemory, ingestMemoryTurn } from "./memory.js";
+
+export class ManifestCallbackExecutor {
+  logger: any = console;
+  executionContext: any = null;
+  constructor(readonly nodeType: string) {}
+
+  /**
+   * The SERVICE channel: a method another node called over a service edge.
+   *
+   * Independent of the workflow channel. A service call returns a value to the caller
+   * and does NOT fire this node's output connectors; a graph trigger fires the outputs
+   * and does not answer a caller. The two never cross (08-mcp-services.md).
+   */
+  async handleServiceCall(method: string, params: any, config: any, executionContext: any): Promise<unknown> {
+    const node = manifestFor(this.nodeType);
+    // The service channel is gated too, and it is the one that would be missed. A node
+    // reached over a service edge never fires its own connectors, so it is easy to think of
+    // as an internal detail of the caller. It is not: it runs this node's calls with this
+    // node's credentials, and leaving it open would make a service edge the way around a
+    // role rather than a way to reuse a capability.
+    assertAuthorized(node, executionContext, config);
+    const result = await performService(
+      node,
+      method,
+      params ?? {},
+      contextFor(node, {}, config, executionContext),
+      stateStoreFor(executionContext),
+      // The caller's live session, for a method that renders content cards. Assembled HERE
+      // because the token is deliberately absent from the manifest's context and must stay
+      // that way: the executor holds it and hands it to platform code, never to the manifest.
+      sessionFor(executionContext),
+    );
+    await refireAfterDocMutation(node, method, config, executionContext);
+    return result;
+  }
+
+  /** Presence of this method is what makes the registry record executionMode "generator". */
+  initializeState(): Record<string, unknown> {
+    return { emitted: 0 };
+  }
+
+  /**
+   * emit() sends outputs, the RETURN VALUE signals completion. They are separate
+   * channels: returning the outputs instead of emitting them loses them, and omitting
+   * isComplete leaks the actor and can hang the workflow.
+   */
+  async handleEvent(
+    event: { type: string; inputs?: any; config?: any },
+    state: Record<string, unknown>,
+    emit: (output: any) => void,
+    executionContext?: any,
+  ): Promise<Record<string, unknown>> {
+    const node = manifestFor(this.nodeType);
+    // Same gate on the streaming path. `this.executionContext` is the fallback the callback
+    // channel already uses, so the identity checked here is the identity the run carries.
+    assertAuthorized(node, executionContext ?? this.executionContext, event.config);
+    // The USER-MEMORY lane, before the run: when the node's config declares the toggle,
+    // the person's context snapshot rides the prompt (memory.ts — the executor's job,
+    // never a manifest's). No toggle, no prompt, headless → passes through untouched.
+    const hydratedConfig = await hydrateMemory(event.config, executionContext ?? this.executionContext);
+    const ctx = contextFor(node, event.inputs, hydratedConfig, executionContext ?? this.executionContext);
+
+    let emitted = 0;
+    const { outputs } = await performApi(
+      node,
+      ctx,
+      (e) => {
+        // A `send` row addresses another NODE, not one of this node's connectors, so it never
+        // becomes an output and never counts as one. It is delivered after the run, at the
+        // executor boundary, which is the only layer holding the execution context.
+        if (!e.emit) return;
+        emitted++;
+        emit({ __outputs: { [e.emit]: e.value } });
+      },
+      node.api?.toolExchange ? await toolBridgeFor(executionContext ?? this.executionContext) : undefined,
+      stateStoreFor(executionContext ?? this.executionContext),
+      // Only this executor gets the lane. A duplex session is always a CallbackNode, so a
+      // PromiseNode has no use for it and should not be handed one.
+      audioLaneFor(executionContext ?? this.executionContext),
+      // The caller's live session, for a node that publishes template data — assembled by
+      // the executor and never seen by the manifest, exactly as on the promise path.
+      sessionFor(executionContext ?? this.executionContext),
+    );
+
+    // The settled result: whatever `finalize` produced, plus any connector the stream
+    // never touched. Emitting the last streamed value again would double it.
+    const streamed = new Set(node.api?.response?.events?.map((r: any) => r.emit) ?? []);
+    const settled = Object.fromEntries(Object.entries(outputs).filter(([k]) => !streamed.has(k)));
+    if (Object.keys(settled).length) emit({ __outputs: settled });
+
+    // The turn complete — original input + final answer to user memory (fire-and-forget,
+    // self-gating on the toggle; the ORIGINAL prompt, not the hydrated one, because the
+    // memory block prepended above must not be re-ingested as something the user said).
+    await ingestMemoryTurn(node.type, event.config, executionContext ?? this.executionContext, outputs);
+
+    return { ...state, emitted, isComplete: true };
+  }
+}